שליחת בקשות בכמות גדולה

ב-12 באוגוסט 2020 הפסקנו את הגישה לקבוצת נתונים גלובלית, נקודת הקצה הגלובלית HTTP HTTP (www.googleapis.com/batch), כפי שהודענו בבלוג Google Developers. גישות אחרות לקיבוץ עדיין פועלות, כפי שמתואר בשאר הדף הזה. אם הקוד שלכם משתמש בנקודת הקצה הגלובלית של HTTP HTTP, אתם יכולים לעיין בפוסט בבלוג שכולל הוראות למעבר כדי להשתמש בגישות אחרות, כמו נקודות קצה (endpoint) ספציפיות מסוג HTTP API (www.googleapis.com/batch/API/VERSION).

במסמך הזה נסביר איך לקבץ קריאות ל-API כדי לצמצם את מספר חיבורי ה-HTTP שהלקוח צריך לבצע.

המסמך הזה עוסק באופן ספציפי בבקשת אצווה על ידי שליחת בקשת HTTP. אם במקום זאת אתם משתמשים בספריית לקוחות של Google כדי לבצע בקשה לקיבוץ קבצים, עיינו במסמכי התיעוד של ספריית הלקוח.

סקירה כללית

כל חיבור HTTP שהלקוח מייצר גורם לתקורה מסוימת. Google Ad Experience Report API תומך בקיבוץ, כדי לאפשר ללקוח להעביר מספר קריאות ל-API לבקשת HTTP אחת.

דוגמאות למצבים שבהם כדאי להשתמש בקיבוץ:

• התחלת להשתמש ב-API ויש לך הרבה נתונים להעלאה.
• משתמש ביצע שינויים בנתונים בזמן שהאפליקציה לא הייתה מחוברת לאינטרנט (מנותק מהאינטרנט). לכן, האפליקציה צריכה לסנכרן את הנתונים המקומיים עם השרת על ידי שליחת הרבה עדכונים ומחיקה.

בכל מקרה, במקום לשלוח כל שיחה בנפרד, אפשר לקבץ אותם יחד לבקשת HTTP אחת. כל הבקשות הפנימיות חייבות לעבור לאותו Google API.

אתם מוגבלים ל-1,000 שיחות בבקשת אצווה אחת. אם רוצים לבצע יותר שיחות כאלה, צריך להשתמש בכמה בקשות בכמות גדולה.

הערה: מערכת האצווה של Google Ad Experience Report API משתמשת בתחביר זהה לזה של מערכת עיבוד הנתונים בכמות גדולה, אבל הסמנטיקה שונה.

פרטי אצווה

בקשת אצווה מורכבת מקריאות API מרובות המשולבות לבקשת HTTP אחת, שניתן לשלוח אל batchPath המצוין במסמך הגילוי של ה-API. נתיב ברירת המחדל הוא /batch/api_name/api_version. קטע זה מתאר בפירוט את תחביר הקבוצות. מאוחר יותר, מופיעה דוגמה.

הערה: קבוצה של n בקשות המקובצות יחד נספרת כחלק ממגבלת השימוש שלך, כבקשות מסוג n, ולא כבקשה אחת. בקשת הקיבוץ מחולקת לקבוצת בקשות לפני העיבוד.

פורמט של בקשת אצווה

בקשת אצווה היא בקשת HTTP רגילה אחת שמכילה מספר קריאות ל-API להצגת מודעות Google, תוך שימוש בסוג התוכן multipart/mixed. בתוך בקשת ה-HTTP הראשית, כל אחד מהחלקים מכיל בקשת HTTP מקוננת.

כל חלק מתחיל בכותרת HTTP משלו ב-Content-Type: application/http. הוא יכול גם לכלול כותרת Content-ID אופציונלית. עם זאת, כותרות החלק פשוט מיועדות לסמן את תחילת החלק, והן נפרדות מהבקשה המקוננת. לאחר שהשרת פורס את בקשת האצווה לבקשות נפרדות, המערכת מתעלמת מכותרות החלקים.

הגוף של כל חלק עצמו הוא בקשת HTTP מלאה, עם פועל, כתובת URL, כותרות וגוף טקסט. בקשת ה-HTTP צריכה להכיל רק את החלק של הנתיב בכתובת ה-URL. לא ניתן להשתמש בכתובות URL מלאות בבקשות לקיבוץ.

כותרות ה-HTTP של בקשת המקבץ החיצונית, מלבד כותרות Content- כמו Content-Type, חלות על כל בקשה בקבוצה. אם תציינו כותרת HTTP נתונה בבקשה החיצונית וגם בשיחה נפרדת, הערך של כותרת השיחה המסוימת יחליף את הערך של כותרת הבקשה החיצונית&#39. הכותרות של שיחה מסוימת חלות רק על השיחה הזאת.

לדוגמה, אם תציינו כותרת הרשאה לשיחה מסוימת, הכותרת הזו תחול רק על השיחה הזו. אם תציינו כותרת הרשאה לבקשה החיצונית, הכותרת הזו תחול על כל השיחות הנפרדות, אלא אם היא תחליף אותה בכותרות של הרשאות משלהן.

כאשר השרת מקבל את הבקשה המקובצת, הוא מחיל את הפרמטרים ואת הכותרות של השאילתה החיצונית של הבקשה (לפי הצורך) על כל חלק, ומתייחס לכל חלק כאילו הייתה בקשת HTTP נפרדת.

תגובה לבקשה בכמות גדולה

תגובת השרת היא תגובת HTTP רגילה עם סוג תוכן מסוג multipart/mixed. כל חלק הוא תגובה לאחת מהבקשות בבקשה המקובצת, באותו סדר כמו הבקשות.

בדומה לחלקים בבקשה, כל חלק מכיל תגובת HTTP מלאה, כולל קוד סטטוס, כותרות וגוף ההודעה. בדומה לחלקים בבקשה, לפני כל חלק של תגובה מופיעה כותרת Content-Type שמסמן את תחילת החלק.

אם לחלק מסוים של הבקשה הייתה כותרת Content-ID, החלק התואם של התגובה כולל כותרת Content-ID תואמת. הערך המקורי הקודם למחרוזת response-, כפי שמוצג בדוגמה הבאה.

הערה: השרת עשוי לבצע את השיחות בכל סדר שהוא. אין להסתמך על כך שהם יבוצעו לפי הסדר שבו ציינתם אותם. אם רוצים לוודא ששתי שיחות מתרחשות בסדר מסוים, לא ניתן לשלוח אותן בבקשה יחידה. במקום זאת, יש לשלוח את השיחה הראשונה לבדה, ולהמתין לתגובה הראשונה לפני השליחה של השיחה השנייה.

דוגמה

בדוגמה הבאה ניתן לראות את השימוש בקיבוץ יחד עם Google Ad Experience Report API.

דוגמה לבקשת אצווה

  POST /batch/v1?key=key HTTP/1.1
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: id1

  GET /v1/sites/http%3A%2F%2F/site1%2F HTTP/1.1

  --batch_aer
  Content-Type: application/http
  Content-ID: id2

  GET /v1/sites/http%3A%2F%2F/site2%2F HTTP/1.1

  --batch_aer--
  

דוגמה לתגובה של מקבץ

זו התגובה לבקשה לדוגמה שבקטע הקודם.

  HTTP/1.1 200 OK
  Content-Type: multipart/mixed; boundary=batch_aer

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id1

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site1",
    "mobileSummary": {
      "lastChangeTime": "2019-02-05T09:46:26.521747Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site1/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2019-02-07T23:07:29.017206Z",
      "betterAdsStatus": "FAILING",
      "enforcementTime": "2018-02-15T15:00:00Z",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site1/",
      "filterStatus": "ON"
    }
  }

  --batch_aer
  Content-Type: application/http
  Content-ID: response-id2

  HTTP/1.1 200 OK
  Content-Type: application/json

  {
    "reviewedSite": "site2",
    "mobileSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-mobile?siteUrl=http://site2/",
      "filterStatus": "OFF"
    },
    "desktopSummary": {
      "lastChangeTime": "2018-03-06T16:06:33.375851Z",
      "betterAdsStatus": "PASSING",
      "reportUrl": "https://www.google.com/webmasters/tools/ad-experience-desktop?siteUrl=http://site2/",
      "filterStatus": "OFF"
    }
  }

  --batch_aer--