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

تحسين الأداء

يتناول هذا المستند بعض الأساليب التي يمكنك استخدامها لتحسين أداء تطبيقك. في بعض الحالات، يتم استخدام أمثلة من واجهات برمجة تطبيقات أخرى أو واجهات برمجة تطبيقات عامة لتوضيح الأفكار المقدَّمة. ومع ذلك، تنطبق المفاهيم نفسها على Google Drive API.

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

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

لتلقّي استجابة مُشفَّرة بتنسيق gzip، عليك إجراء أمرَين: ضبط رأس Accept-Encoding وتعديل وكيل المستخدم ليحتوي على السلسلة gzip. في ما يلي مثال على عناوين HTTP منسَّقة بشكل صحيح لتفعيل ضغط gzip:

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

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

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

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

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

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

ردّ جزئي

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

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

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

مثال

يعرض المثال التالي استخدام المَعلمة fields مع واجهة برمجة تطبيقات عامة (خيالية) باسم "Demo".

طلب بسيط: يغفل طلب 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/* جميع الكائنات في خريطة صفحة.

أمثلة	التأثير
`items`	تعرِض جميع العناصر في صفيف items، بما في ذلك جميع الحقول في كل عنصر، ولكن بدون حقول أخرى.
`etag,items`	تُعيد كلّ من الحقل `etag` وجميع العناصر في صفيف العناصر.
`items/title`	لا تعرض سوى الحقل `title` لجميع العناصر في صفيف items. عند عرض حقل مُدمَج، يتضمّن الردّ العناصر الرئيسية التي تحيط به. لا تتضمّن الحقول الرئيسية أي حقول فرعية أخرى ما لم يتم اختيارها أيضًا بشكل صريح.
`context/facets/label`	لا تعرض سوى الحقل `label` لجميع عناصر الصفيف `facets`، والذي يكون مُدمجًا بحد ذاته ضمن العنصر `context`.
`items/pagemap/*/title`	لكل عنصر في صفيف items، لا يعرض سوى حقل `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 الأقدم والمخصص للتحديث الجزئي.

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

مثال

يعرض هذا المثال طلب تصحيح بسيطًا لتعديل عنوان مورد واجهة برمجة التطبيقات "Demo" العام (الافتراضي) فقط. يحتوي المورد أيضًا على تعليق ومجموعة من الخصائص والحالة والعديد من الحقول الأخرى، ولكن لا يرسل هذا الطلب سوى حقل 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 Client Library، استخدِم 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. */
  },
}

يستجيب الخادم برمز حالة HTTP‏ 200 OK، وتمثيل جزئي للمورد المعدَّل:

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 التي يجب أن يجريها العميل.

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

يوضّح المثال التالي استخدام ميزة تجميع البيانات مع 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--

عرض حقول محدّدة من الطلب

يعرض الخادم تلقائيًا مجموعة تلقائية من حقول الموارد الخاصة بطريقة البحث المستخدَمة. على سبيل المثال، قد لا تعرض الطريقة files.list سوى id وname وmimeType. قد لا تكون هذه الحقول هي الحقول التي تحتاج إليها بالضبط. إذا كنت بحاجة إلى عرض حقول أخرى، راجِع عرض حقول معيّنة لملف.

تحسين الأداء

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

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

ردّ جزئي

مثال

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

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

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

تصحيح (تحديث جزئي)

مثال

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

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

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

معالجة الاستجابة لرقع

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

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

طلبات مجمّعة

نظرة عامة

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

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

الردّ على طلب دفعة

مثال

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

مثال على استجابة الحِزم

عرض حقول محدّدة من الطلب