בקשות אצווה

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

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

סקירה כללית

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

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

• העלאת מספר גדול של מוצרים.

• מתבצעת מחיקה של מספר גדול של מוצרים.

• מתבצע אחזור של מספר גדול של מוצרים.

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

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

הערה: מערכת האצווה של Manufacturer Center API מתבססת על התחביר של מערכת עיבוד האצווה של OData, אבל הסמנטיקה שלה שונה.

פרטי אצווה

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

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

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

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

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

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

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

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

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

תשובה לבקשה באצווה

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

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

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

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

דוגמה

בדוגמה הבאה אפשר לראות איך משתמשים בקיבוץ ב-Manufacturer Center API.

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

POST https://manufacturers.googleapis.com/batch
Authorization: Bearer your_auth_token
Content-Type: multipart/mixed; boundary=--batch_item

--batch_item
Content-Type: application/http
Content-ID: 

PUT /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
Content-Type: application/json

{
   "gtin": "gtin",
   "product_name": "product_name",
   "description": "description",
   "image_link": {
       "image_url": "image_url"
   }
}
--batch_item
Content-Type: application/http
Content-ID: 

GET /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item
Content-Type: application/http
Content-ID: 

DELETE /v1/accounts/account_id/products/targetCountry:contentLanguage:productId
--batch_item--

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

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

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{
  "parent": "accounts/account_id",
  "name": "targetCountry:contentLanguage:productId",
  "targetCountry": "targetCountry",
  "contentLanguage": "contentLanguage",
  "productId": "productId"
}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa
Content-Type: application/http
Content-ID: 

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer

{}

--batch_OycPgXWaQD5f20sVgri2ETiygT65fMaa--

דרישות מוקדמות

חשבון Manufacturer Center

דוגמה באצווה

הקוד הבא מדגים איך לשלוח עדכוני מוצר בכמות גדולה באמצעות Java.

Java

String parent = "accounts/123456";
String newProductName = "US:en:product_id_1";

Image image = new Image();
image.setUrl("http://www.example.com/example.png");

Attributes attributes = new Attributes();
attributes.setGtin(ImmmutableList.of("1234567890"));
attributes.setImageLink(image);

// Creates a new BatchRequest object from the ManufacturerCenter object.
BatchRequest batch = manufacturerCenter.batch();

// JsonBatchCallback generic type is Empty to match the return type of update API.
JsonBatchCallback updateProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Empty empty, HttpHeaders responseHeaders) {
        System.out.printf("Product updated successfully.\n");
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error updating product: %s.\n", error.getMessage());
    }
}

// Adds update product request to batch object.
manufacturerCenter.accounts().products().update(parent, newProductName, attributes)
    .queue(batch, updateProductCallback);

String getProductName = "US:en:product_id_2";

// JsonBatchCallback generic type is Product to match the return type of get API.
JsonBatchCallback getProductCallback =  new JsonBatchCallback() {
    public void onSuccess(Product product, HttpHeaders responseHeaders) {
        System.out.printf("Found product: %s.\n", product.getName());
    }

    public void onFailure(GoogleJsonError error, HttpHeaders responseHeaders)
            throws IOException {
        System.out.printf("Error retrieving product: %s.\n", error.getMessage());
    }
}

// Adds get product request to batch object.
manufacturerCenter.accounts().products().get(parent, getProductName)
    .queue(batch, getProductCallback);

// Sends batch request to Manufacturer Center API.
batch.execute();