الطلبات المجمّعة

يعرض هذا المستند كيفية تجميع طلبات البيانات من واجهة برمجة التطبيقات معًا لتقليل عدد اتصالات HTTP التي يجب أن يجريها العميل.

يدور هذا المستند تحديدًا حول إجراء طلب مجمّع عن طريق إرسال طلب HTTP. بدلاً من ذلك، إذا كنت تستخدم مكتبة برامج Google لإنشاء طلب مُجمَّع، يُرجى الاطّلاع على مستندات مكتبة البرامج.

نظرة عامة

ينتج عن كل اتصال HTTP للعميل مقدار معين من النفقات العامة. تتيح واجهة برمجة التطبيقات في Manufacturer Center التجميع للسماح لعميلك بوضع العديد من طلبات البيانات من واجهة برمجة التطبيقات في طلب HTTP واحد.

أمثلة على الحالات التي قد تحتاج فيها إلى استخدام التجميع:

• تحميل عدد كبير من المنتجات.

• حذف عدد كبير من المنتجات.

• استرداد عدد كبير من المنتجات.

وفي كل حالة، بدلاً من إرسال كل استدعاء على حدة، يمكنك تجميعها معًا في طلب HTTP واحد. يجب أن تنتقل جميع الطلبات الداخلية إلى نفس واجهة برمجة تطبيقات Google.

الحد المسموح به هو 1000 مكالمة في طلب مُجمَّع واحد. إذا كان عليك إجراء مكالمات أكثر من ذلك، استخدِم طلبات مُجمَّعة متعددة.

ملاحظة: يستخدم النظام المجمّع لواجهة برمجة تطبيقات Manufacturer Center البنية نفسها التي يستخدمها نظام معالجة دُفعات OData، إلا أنّ دلالات ذلك مختلفة.

تفاصيل الدفعة

يتألف الطلب المجمّع من طلبات بيانات متعددة من واجهة برمجة التطبيقات مدمجة في طلب HTTP واحد، ويمكن إرسال هذه الطلبات إلى batchPath المحدّد في مستند استكشاف واجهة برمجة التطبيقات. المسار التلقائي هو /batch/api_name/api_version. ويصف هذا القسم بنية الدُفعة بالتفصيل، ويمكنك الاطّلاع لاحقًا على مثال.

ملاحظة: يتم احتساب مجموعة الطلبات البالغ عددها n المجمَّعة ضمن حدّ الاستخدام على أنّها n طلب، وليس كطلب واحد. يتم فصل الطلب المجمّع إلى مجموعة من الطلبات قبل معالجته.

تنسيق الطلب المجمّع

الطلب المجمّع هو طلب HTTP عادي واحد يحتوي على طلبات بيانات متعددة من واجهة برمجة التطبيقات في Manufacturer Center، باستخدام نوع المحتوى multipart/mixed. وضمن طلب HTTP الرئيسي هذا، يحتوي كل جزء من الأجزاء على طلب HTTP مدمج.

يبدأ كل جزء بعنوان HTTP يتضمّن Content-Type: application/http خاص به. ويمكن أن يحتوي أيضًا على عنوان Content-ID اختياري. ومع ذلك، تكون رؤوس الجزء موجودة فقط لتمييز بداية الجزء؛ وتكون منفصلة عن الطلب المتداخل. بعد أن يفتح الخادم الطلب المجمّع في طلبات منفصلة، يتم تجاهل عناوين الأجزاء.

النص الأساسي لكل جزء هو طلب HTTP كامل، يضم فعل وعنوان URL ورؤوس ونص. يجب أن يحتوي طلب HTTP فقط على جزء المسار من عنوان URL، ولا يُسمح بعناوين URL الكاملة في الطلبات المجمّعة.

تنطبق عناوين HTTP للطلب المجمّع الخارجي، باستثناء عناوين Content-، مثل Content-Type، على كل طلب في الدُفعة. إذا حددت عنوان HTTP معينًا في كل من الطلب الخارجي والاستدعاء الفردي، فإن قيمة عنوان الاستدعاء الفردي ستلغي قيمة رأس طلب الدفعة الخارجية. ولا تنطبق عناوين مكالمة فردية إلا على تلك المكالمة.

مثلاً، في حال توفير عنوان التفويض لاستدعاء معيّن، سيتم تطبيق هذا العنوان على ذلك الاستدعاء فقط. في حال توفير عنوان تفويض للطلب الخارجي، سيتم تطبيق هذا العنوان على جميع الطلبات الفردية ما لم يتم تجاوزه باستخدام عناوين التفويض الخاصة بها.

عندما يتلقى الخادم الطلب المجمّع، يطبق معلمات الاستعلام والعناوين الخاصة بالطلب الخارجي (حسب الحاجة) على كل جزء، ثم يعامل كل جزء كما لو كان طلب HTTP منفصلاً.

الرد على طلب مجمّع

استجابة الخادم هي استجابة HTTP عادية واحدة تتضمّن نوع محتوى multipart/mixed، وكل جزء هو الاستجابة لأحد الطلبات في الطلب المجمّع، بالترتيب نفسه الذي تظهر به الطلبات.

كما هو الحال مع الأجزاء في الطلب، يحتوي كل جزء استجابة على استجابة HTTP كاملة، بما في ذلك رمز الحالة والعناوين والنص. وكما هو الحال مع الأجزاء في الطلب، يسبق كل جزء استجابة عنوان Content-Type يشير إلى بداية الجزء.

إذا كان جزء معيّن من الطلب يتضمّن عنوان Content-ID، هذا يعني أنّ الجزء المقابل من الاستجابة يحتوي على عنوان Content-ID مطابق، وتكون القيمة الأصلية مسبوقة بالسلسلة response-، كما هو موضّح في المثال التالي.

ملاحظة: قد يُجري الخادم مكالماتك بأي ترتيب. لا تعتمد على تنفيذها بالترتيب الذي حدّدتها. إذا كنت تريد ضمان إجراء مكالمتَين بترتيب معيّن، لا يمكنك إرسالهما في طلب واحد، بدلاً من ذلك، أرسِل المكالمتَين الأولتَين بمفردهما، ثم انتظري الردّ على الطلب الأول قبل إرسال الطلب الثاني.

مثال

يوضّح المثال التالي استخدام التجميع باستخدام واجهة برمجة تطبيقات Manufacturer Center.

مثال على طلب مجمّع

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();