إرسال طلبات مجمّعة

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

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

نظرة عامة

ينتج عن كل اتصال HTTP في العميل مقدار معين من النفقات العامة. تتيح واجهة برمجة التطبيقات Enterprise License Manager API التجميع للسماح لعميلك بتقديم عدة طلبات بيانات من واجهة برمجة التطبيقات في طلب HTTP واحد.

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

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

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

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

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

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

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

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

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

الطلب المجمّع هو طلب HTTP عادي واحد يحتوي على طلبات متعددة من واجهة برمجة تطبيقات Enterprise License Manager، وذلك باستخدام نوع المحتوى 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-، كما هو موضّح في المثال التالي.

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

مثال

يوضّح المثال التالي استخدام التجميع باستخدام واجهة برمجة تطبيقات تجريبية عامة (خيالية) تُسمى Farm API. ومع ذلك، تنطبق المفاهيم نفسها على Enterprise License Manager API.

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

POST /batch/farm/v1 HTTP/1.1
Authorization: Bearer your_auth_token
Host: www.googleapis.com
Content-Type: multipart/mixed; boundary=batch_foobarbaz
Content-Length: total_content_length

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item1:[e-mail]>

GET /farm/v1/animals/pony

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item2:[e-mail]>

PUT /farm/v1/animals/sheep
Content-Type: application/json
Content-Length: part_content_length
If-Match: "etag/sheep"

{
  "animalName": "sheep",
  "animalAge": "5"
  "peltColor": "green",
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <item3:[e-mail]>

GET /farm/v1/animals
If-None-Match: "etag/animals"

--batch_foobarbaz--

مثال على ردّ مجمّع

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

HTTP/1.1 200
Content-Length: response_total_content_length
Content-Type: multipart/mixed; boundary=batch_foobarbaz

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item1:[e-mail]>

HTTP/1.1 200 OK
Content-Type application/json
Content-Length: response_part_1_content_length
ETag: "etag/pony"

{
  "kind": "farm#animal",
  "etag": "etag/pony",
  "selfLink": "/farm/v1/animals/pony",
  "animalName": "pony",
  "animalAge": 34,
  "peltColor": "white"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item2:[e-mail]>

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: response_part_2_content_length
ETag: "etag/sheep"

{
  "kind": "farm#animal",
  "etag": "etag/sheep",
  "selfLink": "/farm/v1/animals/sheep",
  "animalName": "sheep",
  "animalAge": 5,
  "peltColor": "green"
}

--batch_foobarbaz
Content-Type: application/http
Content-ID: <response-item3:[e-mail]>

HTTP/1.1 304 Not Modified
ETag: "etag/animals"

--batch_foobarbaz--