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

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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

يبدأ كل جزء بعنوان Content-Type: application/http 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- قبل القيمة الأصلية، كما هو موضّح في المثال التالي.

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

مثال

يعرض المثال التالي كيفية استخدام التجميع مع واجهة 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.

جافا

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