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

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

يتكون الطلب المجمّع من عدة طلبات من واجهة برمجة التطبيقات تم دمجها في طلب HTTP واحد، والذي يمكن إرساله إلى batchPath المحددة في مستند استكشاف واجهة برمجة التطبيقات. المسار التلقائي هو /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 معيّنًا في كل من الطلب الخارجي والاستدعاء الفردي، ستلغي قيمة عنوان الاستدعاء الفردي قيمة رأس الطلب الخارجي. لا تسري رؤوس مكالمة فردية إلا على هذه المكالمة.

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

عندما يتلقى الخادم الطلب المجمّع، فإنه يطبّق معلمات الاستعلام ورؤوس الطلب الخارجي (حسب الاقتضاء) على كل جزء، ثم يتعامل مع كل جزء كما لو كان طلب 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();