ويتناول هذا المستند بعض الأساليب التي يمكنك استخدامها لتحسين أداء تطبيقك. في بعض الحالات، يتم استخدام أمثلة من واجهات برمجة تطبيقات أخرى أو واجهات برمجة تطبيقات عامة لتوضيح الأفكار المعروضة. ومع ذلك، تنطبق المفاهيم نفسها على Google Drive API.
الضغط باستخدام 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. التي يتعين على عميلك إجراؤها.
يدور هذا المستند تحديدًا حول إجراء طلب مجمّع من خلال إرسال طلب HTTP. بدلاً من ذلك، إذا كنت تستخدم مكتبة برامج Google لإنشاء طلب مجمّع، يُرجى الاطّلاع على مستندات مكتبة البرامج.
نظرة عامة
ينتج عن كل اتصال 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--
عرض حقول محددة من الطلب
يعرض الخادم افتراضيًا مجموعة افتراضية من حقول الموارد الخاصة بـ
الطريقة المستخدمة. على سبيل المثال،
قد تعرض الطريقة files.list
فقط
id
وname
وmimeType
قد لا تكون هذه الحقول هي الحقول الدقيقة التي
المحتاجين. إذا كنت بحاجة إلى إرجاع حقول أخرى، يُرجى الرجوع إلى
عرض حقول معيّنة لملف معيّن: