تحسين الأداء

الضغط باستخدام gzip

وهناك طريقة سهلة وملائمة لتقليل معدل نقل البيانات اللازم لكل طلب، وهي تمكين الضغط بتنسيق gzip. وعلى الرغم من أن هذا يتطلب وقتًا إضافيًا لوحدة المعالجة المركزية (CPU) لفك ضغط النتائج، فإن المقايضة مع تكاليف الشبكة عادةً ما تجعل الأمر مفيدًا للغاية.

لتلقي استجابة بترميز gzip، عليك عمل شيئين: ضبط العنوان Accept-Encoding وتعديل وكيل المستخدم بحيث يتضمن السلسلة gzip. في ما يلي مثال على عناوين HTTP تم تشكيلها بشكل صحيح لتفعيل ضغط gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

استخدام الموارد الجزئية

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

هناك نوعان من الطلبات الجزئية:

• الردّ الجزئي: طلب يمكنك من خلاله تحديد الحقول المطلوب تضمينها في الردّ (استخدِم مَعلمة الطلب fields).
• رمز التصحيح: طلب تعديل يمكنك من خلاله إرسال الحقول التي تريد تغييرها فقط (استخدِم فعل HTTP PATCH).

يتوفّر مزيد من التفاصيل حول إرسال طلبات جزئية في الأقسام التالية.

ردّ جزئي

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

لطلب استجابة جزئية، استخدِم مَعلمة طلب fields لتحديد الحقول التي تريد عرضها. يمكنك استخدام هذه المعلمة مع أي طلب يعرض بيانات الاستجابة.

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

مثال

يوضح المثال التالي استخدام المعلمة fields مع عنصر تجريبي عام (خيالي) واجهة برمجة التطبيقات.

طلب بسيط: يحذف طلب HTTP GET هذا المَعلمة fields ويعرض المورد الكامل.

https://www.googleapis.com/demo/v1

الردّ الكامل على الموارد: تتضمّن بيانات الموارد الكاملة الحقول التالية، بالإضافة إلى الحقول الأخرى العديدة التي تم حذفها للإيجاز.

{
  "kind": "demo",
  ...
  "items": [
  {
    "title": "First title",
    "comment": "First comment.",
    "characteristics": {
      "length": "short",
      "accuracy": "high",
      "followers": ["Jo", "Will"],
    },
    "status": "active",
    ...
  },
  {
    "title": "Second title",
    "comment": "Second comment.",
    "characteristics": {
      "length": "long",
      "accuracy": "medium"
      "followers": [ ],
    },
    "status": "pending",
    ...
  },
  ...
  ]
}

طلب استجابة جزئية: يستخدم الطلب التالي لهذا المورد نفسه المعلمة fields لتقليل كمية البيانات المعروضة بشكل كبير.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

الاستجابة الجزئية: استجابةً للطلب أعلاه، يرسل الخادم ردًّا يحتوي على معلومات النوع فقط مع مصفوفة عناصر مصغَّرة تتضمّن فقط معلومات عنوان HTML وخاصية الطول في كل عنصر.

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

يُرجى العِلم أنّ الردّ هو كائن JSON لا يتضمن سوى الحقول المحددة والعناصر الرئيسية التي تشتمل على هذه الحقول.

وسنتناول بعد ذلك تفاصيل حول كيفية تنسيق مَعلمة fields، تليها مزيد من التفاصيل حول ما يتم عرضه في الردّ بالضبط.

ملخّص بنية مَعلمات الحقول

يستند تنسيق قيمة معلَمة طلب fields إلى بنية XPath بشكل غير دقيق. تم تلخيص بناء الجملة المتوافق أدناه، وتم توفير أمثلة إضافية في القسم التالي.

• استخدِم قائمة مفصولة بفواصل لاختيار حقول متعددة.
• استخدِم a/b لاختيار الحقل b المتداخل في الحقل a. استخدِم a/b/c لاختيار حقل c متداخل في b.
  

  استثناء: لردود واجهة برمجة التطبيقات التي تستخدم "data" برامج تضمين، حيث يتم دمج الاستجابة داخل كائن data يبدو مثل data: { ... }، لا يجب تضمين "data" في مواصفات fields. يؤدي تضمين كائن البيانات مع مواصفات حقول مثل data/a/b إلى حدوث خطأ. بدلاً من ذلك، يمكنك استخدام إحدى مواصفات fields مثل a/b.

• يمكنك استخدام أداة اختيار فرعية لطلب مجموعة من الحقول الفرعية المحدّدة للمصفوفات أو الكائنات عن طريق وضع التعبيرات بين قوسين "( )".

  على سبيل المثال: تعرض fields=items(id,author/email) معرّف السلعة وعنوان البريد الإلكتروني للمؤلف فقط لكل عنصر في مصفوفة السلع. ويمكنك أيضًا تحديد حقل فرعي واحد، حيث تكون السمة fields=items(id) معادِلة للحقل fields=items/id.

• استخدِم أحرف البدل في اختيارات الحقول، إذا لزم الأمر.

  على سبيل المثال: يختار fields=items/pagemap/* كل العناصر في خريطة صفحات.

مزيد من الأمثلة على استخدام مَعلمة الحقول

تتضمّن الأمثلة أدناه أوصافًا لكيفية تأثير قيمة مَعلمة fields في الاستجابة.

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

حدِّد الحقول التي تريد عرضها أو اختَر اختيارات الحقول.

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

في ما يلي بعض الأمثلة على مستوى المجموعة:

أمثلة	التأثير
items	عرض جميع العناصر في مصفوفة السلع، بما في ذلك جميع الحقول في كل عنصر، ولكن بدون حقول أخرى.
etag,items	تعرض كل من الحقل etag وجميع العناصر في مصفوفة السلع.
items/title	لا تعرض سوى الحقل title لجميع العناصر في مصفوفة السلع. عندما يتم إرجاع حقل متداخل، يتضمن الرد الكائنات الرئيسية المضمّنة. لا تتضمّن الحقول الرئيسية أي حقول فرعية أخرى ما لم يتم اختيارها بشكل صريح أيضًا.
context/facets/label	لا تعرض سوى الحقل label لجميع أعضاء المصفوفة facets والذي يتم دمجه ضمن الكائن context.
items/pagemap/*/title	بالنسبة إلى كل عنصر في مصفوفة العناصر، يتم عرض الحقل title فقط (إذا كان متوفّرًا) لجميع الكائنات الثانوية للسمة pagemap.

في ما يلي بعض الأمثلة على مستوى الموارد:

أمثلة	التأثير
title	تعرض الحقل title للمورد المطلوب.
author/uri	تعرض الحقل الفرعي uri للكائن author في المورد المطلوب.
links/*/href	تعرض الحقل href لجميع العناصر التي تعتبر عناصر ثانوية للدالة links.

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

إذا كان طلبك يحدِّد حقولاً معيّنة بشكل تلقائي، سيعرض الخادم الكائنات أو عناصر الصفيف بالكامل. يمكنك تحديد ردّ يتضمّن حقولاً فرعية معيّنة فقط. يمكنك إجراء ذلك باستخدام "( )" بناء جملة التحديد الفرعي، كما في المثال أدناه.

مثال	التأثير
items(title,author/uri)	لا تعرض سوى قيم title وuri للمؤلف لكل عنصر في مصفوفة العناصر.

التعامل مع الردود الجزئية

بعد أن يعالج الخادم طلبًا صالحًا يتضمّن معلَمة طلب البحث fields، يرسل مرة أخرى رمز حالة HTTP 200 OK، مع البيانات المطلوبة. إذا كانت معلَمة طلب البحث fields بها خطأ أو كانت غير صالحة بأي شكل آخر، يعرض الخادم رمز حالة HTTP 400 Bad Request، بالإضافة إلى رسالة خطأ تخبر المستخدم بالأخطاء في اختيار الحقول (على سبيل المثال، "Invalid field selection a/b").

في ما يلي مثال عن ردّ جزئي كما هو موضّح في القسم التمهيدي أعلاه. يستخدم الطلب المَعلمة fields لتحديد الحقول التي يجب عرضها.

https://www.googleapis.com/demo/v1?fields=kind,items(title,characteristics/length)

يبدو الرد الجزئي على النحو التالي:

200 OK

{
  "kind": "demo",
  "items": [{
    "title": "First title",
    "characteristics": {
      "length": "short"
    }
  }, {
    "title": "Second title",
    "characteristics": {
      "length": "long"
    }
  },
  ...
  ]
}

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

رمز التصحيح (تحديث جزئي)

يمكنك أيضًا تجنُّب إرسال بيانات غير ضرورية عند تعديل الموارد. لإرسال البيانات المعدّلة فقط للحقول المحدّدة التي تريد تغييرها، استخدِم فعل HTTP PATCH. تختلف دلالات رمز التصحيح الموضَّحة في هذا المستند (وأبسط) عن تلك التي كانت في ما يخص تنفيذ GData الأقدم والتحديث الجزئي.

يوضّح المثال القصير أدناه كيف يؤدي استخدام رمز التصحيح إلى تقليل البيانات التي تحتاج إلى إرسالها لإجراء تعديل بسيط.

مثال

يعرض هذا المثال طلب تصحيح بسيط لتحديث عنوان "نسخة تجريبية" عامة (خيالية) فقط مورد واجهة برمجة التطبيقات. يحتوي المورد أيضًا على تعليق ومجموعة من الخصائص والحالة والعديد من الحقول الأخرى، ولكن هذا الطلب يرسل فقط الحقل title، نظرًا لأنه الحقل الوحيد الذي يتم تعديله:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

الرد:

200 OK

{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

يعرض الخادم رمز الحالة 200 OK، بالإضافة إلى التمثيل الكامل للمورد المعدّل. وبما أنّ طلب رمز التصحيح لم يكُن سوى الحقل title الذي تم تضمينه، فهذه هي القيمة الوحيدة التي اختلفت عن ذي قبل.

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

دلالات طلب رمز التصحيح

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

• الإضافة: لإضافة حقل غير متوفّر، حدِّد الحقل الجديد وقيمته.
• التعديل: لتغيير قيمة حقل حالي، حدِّد الحقل واضبطه على القيمة الجديدة.
  
• الحذف: لحذف حقل، حدِّد الحقل واضبطه على null. مثلاً: "comment": null يمكنك أيضًا حذف عنصر بالكامل (إذا كان قابلاً للتغيير) من خلال ضبطه على null. إذا كنت تستخدم مكتبة برامج Java API، يمكنك استخدام Data.NULL_STRING بدلاً منها. حيث لمزيد من التفاصيل، راجِع قيمة JSON فارغة.

ملاحظة بشأن الصفائف: تستبدل طلبات التصحيح التي تحتوي على صفائف المصفوفة الحالية بالمصفوفة التي تقدّمها. لا يمكنك تعديل عناصر أو إضافتها أو حذفها في مصفوفة بشكل مجزّأ.

استخدام رمز التصحيح في دورة القراءة والتعديل والكتابة

قد يكون من المفيد البدء باسترداد رد جزئي بالبيانات التي تريد تعديلها. ويُعدّ هذا الإجراء مهمًا على وجه الخصوص للموارد التي تستخدم علامات ETag، لأنّه يجب تقديم قيمة ETag الحالية في عنوان HTTP If-Match لتعديل المورد بنجاح. بعد الحصول على البيانات، يمكنك تعديل القيم التي تريد تغييرها وإعادة التمثيل الجزئي المعدَّل مع طلب تصحيح. في ما يلي مثال يفترض أن المورد التجريبي يستخدم علامات ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

هذا هو الردّ الجزئي:

200 OK

{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

يعتمد طلب التصحيح التالي على هذا الرد. وكما هو موضّح أدناه، تستخدم أيضًا المَعلمة fields للحدّ من البيانات التي يتم عرضها في استجابة رمز التصحيح:

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"

{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

يستجيب الخادم برمز حالة OK HTTP 200، والتمثيل الجزئي للمورد الذي تم تحديثه:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

إنشاء طلب تصحيح مباشرةً

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

ملاحظة: يمكنك استخدام عنوان HTTP يتضمّن "If-Match: *" لفرض إرسال رمز التصحيح عندما تكون علامات ETag قيد الاستخدام. إذا قمت بذلك، فلن تحتاج إلى إجراء القراءة قبل الكتابة.

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

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

مع هذا الطلب، إذا كان حقل التعليق يحتوي على قيمة حالية، ستحل القيمة الجديدة محلها؛ وإلا يتم تعيينها على القيمة الجديدة. وبالمثل، إذا كانت هناك خاصية حجم، يتم استبدال قيمتها؛ وإذا لم يكن كذلك، فسيتم إنشاؤه. وتتم إزالة حقل الدقة في حال ضبطه.

التعامل مع الرد على رمز التصحيح

بعد معالجة طلب تصحيح صالح، تعرض واجهة برمجة التطبيقات رمز استجابة HTTP 200 OK مع التمثيل الكامل للمورد المعدّل. في حال استخدام علامات ETag بواسطة واجهة برمجة التطبيقات، يعدِّل الخادم قيم ETag عند معالجة طلب تصحيح بنجاح، كما هو الحال مع PUT.

يعرض طلب التصحيح تمثيل المورد بالكامل ما لم تستخدم المعلمة fields لتقليل كمية البيانات التي يعرضها.

إذا نتج عن طلب التصحيح حالة مورد جديدة غير صالحة من ناحية البنية أو دلاليًا، يعرض الخادم رمز حالة HTTP 400 Bad Request أو 422 Unprocessable Entity وتبقى حالة المورد بدون تغيير. على سبيل المثال، إذا حاولت حذف قيمة حقل مطلوب، سيعرض الخادم خطأ.

التدوين البديل عندما لا يكون فعل PATCH HTTP متاحًا

إذا كان جدار الحماية لا يسمح بطلبات HTTP PATCH، يمكنك تنفيذ طلب HTTP POST وضبط عنوان الإلغاء على PATCH، كما هو موضّح أدناه:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

الفرق بين رمز التصحيح والتحديث

من الناحية العملية، عند إرسال بيانات لطلب تعديل يستخدم فعل HTTP PUT، يجب إرسال الحقول المطلوبة أو الاختيارية فقط. وفي حال إرسال قيم للحقول التي ضبطها الخادم، سيتم تجاهلها. على الرغم من أنّ هذه الطريقة قد تبدو طريقة أخرى لإجراء تعديل جزئي، فإنّ هذه الطريقة لها بعض القيود. مع التحديثات التي تستخدم فعل HTTP PUT، يتعذّر الطلب في حال عدم توفير المَعلمات المطلوبة، كما يمحو البيانات التي تم ضبطها سابقًا في حال عدم توفير مَعلمات اختيارية.

لهذا السبب، من الآمن استخدام رمز التصحيح. يمكنك توفير بيانات للحقول التي تريد تغييرها فقط، لن يتم محو الحقول التي حذفتها. يحدث الاستثناء الوحيد لهذه القاعدة مع العناصر أو الصفائف المتكررة: إذا حذفتها جميعًا، فستظل كما هي؛ في حال توفير أيٍّ منها، يتمّ استبدال المجموعة الكاملة بالمجموعة التي تقدّمها.

نظرة عامة

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

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

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

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

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

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

تشمل القيود الإضافية ما يلي:

• قد تتسبب الطلبات المجمّعة التي تحتوي على أكثر من 100 اتصال في حدوث خطأ.
• يبلغ عدد الأحرف المسموح به في عنوان URL لكل طلب داخلي 8,000 حرف.
• لا يتوافق Google Drive مع العمليات المجمّعة للوسائط، سواء للتحميل أو التنزيل أو لتصدير الملفات.

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

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

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

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

الطلب المجمّع هو طلب HTTP عادي واحد يحتوي على طلبات بيانات متعددة من واجهة برمجة التطبيقات في Google Drive، باستخدام نوع المحتوى 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 Drive API.

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

POST https://www.googleapis.com/batch/drive/v3
Accept-Encoding: gzip
User-Agent: Google-HTTP-Java-Client/1.20.0 (gzip)
Content-Type: multipart/mixed; boundary=END_OF_PART
Content-Length: 963


--END_OF_PART
Content-Length: 337
Content-Type: application/http
content-id: 1
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id
Authorization: Bearer authorization_token
Content-Length: 70
Content-Type: application/json; charset=UTF-8

{
  "emailAddress":"example@appsrocks.com",
  "role":"writer",
  "type":"user"
}
--END_OF_PART
Content-Length: 353
Content-Type: application/http
content-id: 2
content-transfer-encoding: binary

POST https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id&sendNotificationEmail=false
Authorization: Bearer authorization_token
Content-Length: 58
Content-Type: application/json; charset=UTF-8

{
   "domain":"appsrocks.com",
   "role":"reader",
   "type":"domain"
}
--END_OF_PART--

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

هذه هي الاستجابة للطلب النموذجي في القسم السابق.

HTTP/1.1 200 OK
Alt-Svc: quic=":443"; p="1"; ma=604800
Server: GSE
Alternate-Protocol: 443:quic,p=1
X-Frame-Options: SAMEORIGIN
Content-Encoding: gzip
X-XSS-Protection: 1; mode=block
Content-Type: multipart/mixed; boundary=batch_6VIxXCQbJoQ_AATxy_GgFUk
Transfer-Encoding: chunked
X-Content-Type-Options: nosniff
Date: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Vary: X-Origin
Vary: Origin
Expires: Fri, 13 Nov 2015 19:28:59 GMT


--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-1

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "12218244892818058021i"
}

--batch_6VIxXCQbJoQ_AATxy_GgFUk
Content-Type: application/http
Content-ID: response-2

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
Date: Fri, 13 Nov 2015 19:28:59 GMT
Expires: Fri, 13 Nov 2015 19:28:59 GMT
Cache-Control: private, max-age=0
Content-Length: 35

{
 "id": "04109509152946699072k"
}

--batch_6VIxXCQbJoQ_AATxy_GgFUk--