طلبات مجمّعة

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

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

نظرة عامة

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

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

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

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

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

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

ملاحظة: من المرجّح أن تؤدي أحجام الدفعات الأكبر إلى بدء عملية تحديد معدل الصعوبة. لا يُنصح بإرسال دفعات أكبر من 50 طلبًا.

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

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

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

تنسيق طلب الحزمة

الطلب المجمّع هو طلب HTTP عادي واحد يحتوي على عدة طلبات للحصول على البيانات من واجهة برمجة التطبيقات Gmail API، باستخدام نوع المحتوى multipart/mixed. ضمن طلب HTTP الرئيسي هذا، يحتوي كل جزء على طلب HTTP مُدمَج.

يبدأ كل جزء برأس Content-Type: application/http 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. ومع ذلك، تنطبق المفاهيم نفسها على Gmail 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--