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

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

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

סקירה כללית

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

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

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

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

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

הערה: מערכת הקריאות באצווה של Google Ad Experience Report API משתמשת בתחביר זהה לזה של מערכת העיבוד ברצף (batch processing) של OData, אבל הסמנטיקה שלהן שונה.

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

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

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

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

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

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

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

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

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

כשהשרת מקבל את הבקשה באצווה, הוא מחיל את הפרמטרים והכותרות של השאילתה החיצונית (לפי הכללים) על כל חלק, ואז מתייחס לכל חלק כאילו היה בקשת 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--