يمكنك استخدام الطلبات المجمّعة مع Merchant API لإرسال طلبات HTTP متعدّدة في طلب واحد من واجهة برمجة التطبيقات.
إذا كنت تفضّل تجميع الطلبات باستخدام مكتبات برامج العميل، يُرجى الاطّلاع على مقالة إعادة هيكلة الرمز البرمجي للطلبات المتزامنة.
الطلب المجمّع هو طلب HTTP عادي واحد يتضمّن طلبات متعدّدة من واجهة برمجة التطبيقات، باستخدام نوع المحتوى multipart/mixed. ضمن طلب HTTP الرئيسي، يحتوي كل جزء على طلب HTTP مضمّن.
يمكنك إرسال الطلب المجمّع إلى batchPath المحدّد لواجهة برمجة التطبيقات.
batchPath في Merchant API هو batch/{sub-api}/v1. يمكنك العثور على batchPath لواجهات برمجة التطبيقات الأخرى في مستندات الاكتشاف
الخاصة بها.
في ما يلي أمثلة على أسباب تجميع طلباتك:
- لقد بدأت للتو استخدام واجهة برمجة التطبيقات ولديك الكثير من البيانات لتحميلها.
- أجرى أحد المستخدمين تغييرات على البيانات أثناء عدم اتصال تطبيقك بالإنترنت، ويحتاج تطبيقك إلى مزامنة البيانات المحلّية مع الخادم.
يمنعك إرسال طلبات متعدّدة بالتوازي من الانتظار حتى اكتمال أبطأ طلب فرعي، ما يحسّن أوقات استجابة الخادم ويقلّل وقت الاستجابة.
كتابة طلب مجمّع
في ما يلي نموذج لطلب مجمّع من Merchant API. يجمع هذا الطلب بين طلب `get` لاسترداد المستودع الإقليمي لمنتج معيّن، وطلب `insert` لتعديل المستودع الإقليمي للمنتج نفسه. عليك اتّباع تنسيق المثال تمامًا:
- استخدِم
https://merchantapi.googleapis.com/batch/{sub-api}/v1كعنوان URL أساسي. - حدِّد حدًا فاصلاً لفصل كل طلب مضمّن، مثلاً:
-H 'Content-Type: multipart/mixed,boundary=batch_inventory' \ - افصل بين كل طلب مضمّن باستخدام الحد الفاصل، مثلاً:
--batch_inventory. - أدرِج
Content-Type: application/httpفي بداية كل طلب مضمّن. - استخدِم
Content-IDلتصنيف كل طلب مضمّن باستخدام رقم تعريف خاص بك. مثلاً:Content-ID: <get~en~US~123456>. - أدرِج سطرًا فارغًا بين العنوان والمسار ونص كل طلب مضمّن. إذا لم يكن الطلب المضمّن يتضمّن نصًا، اترك سطرًا فارغًا قبل الحد الفاصل التالي.
- لا تُدرِج عنوان URL الأساسي في كل طلب مضمّن فردي.
- اختم الطلب الرئيسي بحد فاصل نهائي، مثلاً:
--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 وترفض الطلب بأكمله.