إرسال طلبات متعددة في آنٍ واحد

يمكنك استخدام الطلبات المجمّعة مع Merchant API لإرسال طلبات HTTP متعددة في طلب واحد من واجهة برمجة التطبيقات.

إذا كنت تفضّل إجراء التجميع باستخدام مكتبات العميل، يمكنك الاطّلاع على إعادة هيكلة الرمز البرمجي لتنفيذ الطلبات المتزامنة.

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

يمكنك إرسال الطلب المُجمّع إلى batchPath المحدّد لواجهة برمجة التطبيقات. batchPath لـ Merchant API هو batch/{sub-api}/v1. يمكنك العثور على batchPath لواجهات برمجة التطبيقات الأخرى في مستندات الاكتشاف الخاصة بها.

تشمل أمثلة أسباب تجميع طلباتك ما يلي:

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

يمنع إرسال طلبات متعدّدة بالتوازي انتظار أبطأ طلب فرعي، ما يحسّن أوقات استجابة الخادم ويقلّل من وقت الاستجابة للطلب.

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

في ما يلي نموذج لطلب مجمّع في Merchant API. يجمع هذا الطلب بين طلب get لاسترداد المخزون الإقليمي لمنتج معيّن، وطلب insert لتعديل المخزون الإقليمي للمنتج نفسه. يجب اتّباع تنسيق المثال التالي بدقة:

1. استخدِم https://merchantapi.googleapis.com/batch/{sub-api}/v1 كعنوان URL الأساسي.
2. حدِّد حدًا لفصل كل طلب متداخل، على سبيل المثال: -H 'Content-Type: multipart/mixed,boundary=batch_inventory' \
3. افصل بين كل طلب متداخل باستخدام الحدّ، مثلاً --batch_inventory.
4. أدرِج Content-Type: application/http في بداية كل طلب متداخل.
5. استخدِم Content-ID لتصنيف كل طلب متداخل باستخدام المعرّف الخاص بك. على سبيل المثال: Content-ID: <get~en~US~123456>.
6. أدرِج سطرًا فارغًا بين العنوان والمسار ونص كل طلب متداخل. إذا لم يتضمّن الطلب المتداخل نصًا، اترُك سطرًا فارغًا قبل الحدّ التالي.
7. لا تُدرِج عنوان URL الأساسي في كل طلب فردي متداخل.
8. اختتِم الطلب الرئيسي بحدّ نهائي، مثل --batch_inventory–.

curl https://merchantapi.googleapis.com/batch/inventories/v1 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: multipart/mixed,boundary=batch_inventory' \
--data '
--batch_inventory
Content-Type: application/http
Content-ID: <get~en~US~123456>

GET /inventories/v1/accounts/123/products/en~US~123456/regionalInventories

--batch_inventory
Content-Type: application/http
Content-ID: <post~en~US~123456>

POST /inventories/v1/accounts/123/products/en~US~123456/regionalInventories:insert
{
  "region": "123456",
  "price": {
    "amountMicros": "100000000",
    "currencyCode": "USD"
  }
}

--batch_inventory--'

ملاحظات حول الترتيب

• قد لا يتم تنفيذ الطلبات بالترتيب الذي تحدده.
• استخدِم Content-ID لتحديد الطلبات الفردية.
• إذا كنت بحاجة إلى تنفيذ طلباتك بترتيب معيّن، أرسِلها بشكل منفصل وانتظر الردّ على الطلب الأول قبل إرسال الطلب التالي.

قراءة ردّ دفعة

في ما يلي مثال على استجابة مجمّعة بتنسيق HTTP. قد لا يتطابق ترتيب الردود مع ترتيب الطلبات. استخدِم Content-ID لتحديد الطلب المضمّن الذي ينتمي إليه كل رد مضمّن. في الردود، تضيف واجهة برمجة التطبيقات البادئة response- إلى كل Content-ID.

--batch_inventory
Content-Type: application/http
Content-ID: <response-get~en~US~123456>
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer
{}
--batch_inventory
Content-Type: application/http
Content-ID: <response-post~en~US~123456>
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Vary: Origin
Vary: X-Origin
Vary: Referer
{
  "name": "accounts/123/products/en~US~123456/regionalInventories/123456",
  "region": "123456",
  "price": {
    "amountMicros": "100000000",
    "currencyCode": "USD"
  }
}
--batch_inventory--

الحدود

تخضع الطلبات المجمّعة للحدود التالية:

• ‫2,000 طلب متداخل لكل طلب مجمّع

إذا تجاوز طلب مجمّع أيًا من هذه الحدود، ستعرض واجهة برمجة التطبيقات الخطأ 400 Bad Request وترفض الطلب بأكمله.