בקשות אצווה

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

בקשה באצווה מורכבת מכמה קריאות ל-API המאוגדות לבקשת HTTP אחת, שאותה אפשר לשלוח אל ה-batchPath שצוין במסמך ה-Discovery של ה-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();