تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

تم إيقاف طريقة واحدة محددة نهائيًا للدفعة، وهي نقطة نهاية HTTP مجمّعة (www.googleapis.com/batch)، في 12 آب (أغسطس) 2020، كما تم الإعلان عنها في مدونة Google Developers. ولا تزال الأساليب الأخرى للتجميع تعمل، كما هو موثق في بقية هذه الصفحة. وإذا كان الرمز الخاص بك يستخدم نقطة نهاية HTTP مجمّعة، اطّلِع على مشاركة المدونة للحصول على تعليمات حول النقل لاستخدام طرق أخرى، مثل نقاط نهاية HTTP مجمّعة لواجهة برمجة التطبيقات (www.googleapis.com/batch/API/VERSION).

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

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

نظرة عامة

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

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

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

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

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

ملاحظة: يستخدم نظام تجميع واجهة برمجة تطبيقات Google Mirror نفس البنية المستخدمة في نظام معالجة مجمّعة لـ OData، ومع ذلك تختلف الدلالات.

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

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

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

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

طلب الدفعة هو طلب HTTP عادي واحد يحتوي على طلبات متعددة من Google Mirror 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-، كما هو موضح في المثال التالي.

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

مثال

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

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

POST /batch HTTP/1.1
Content-Length: content_length
content-type: multipart/mixed; boundary="===============7330845974216740156=="
accept-encoding: gzip, deflate

--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_1

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_1_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_2

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_2_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: TIMELINE_INSERT_USER_3

POST /mirror/v1/timeline HTTP/1.1
Content-Type: application/json
authorization: Bearer user_3_token
accept: application/json
content-length: 24

{"text": "Hello there!"}
--===============7330845974216740156==--

مثال على ردّ الدفعة

هذا هو الرد على نموذج الطلب الوارد في القسم السابق.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Date: Tue, 22 Jan 2013 18:56:00 GMT
Expires: Tue, 22 Jan 2013 18:56:00 GMT
Cache-Control: private, max-age=0

--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_1

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "1234567890",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/1234567890",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_2

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "0987654321",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/0987654321",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=
Content-Type: application/http
Content-ID: response-TIMELINE_INSERT_USER_3

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: 304

{
 "kind": "glass#timelineItem",
 "id": "5432109876",
 "selfLink": "https://www.googleapis.com/mirror/v1/timeline/5432109876",
 "created": "2012-09-25T23:28:43.192Z",
 "updated": "2012-09-25T23:28:43.192Z",
 "etag": "\"G5BI0RWvj-0jWdBrdWrPZV7xPKw/t25selcGS3uDEVT6FB09hAG-QQ\"",
 "text": "Hello there!"
}
--batch_pK7JBAk73-E=_AA5eFwv4m2Q=--