تحسين الأداء

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

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

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

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

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

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

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

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

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

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

ردّ جزئي

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

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

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

مثال

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

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

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

مثال

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

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

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

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

أسلوب بديل عند عدم توفّر فعل HTTP PATCH

إذا كان جدار الحماية لا يسمح بطلبات 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 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--

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

في حال عدم تحديد المَعلمة fields، يعرض الخادم مجموعة تلقائية من الحقول الخاصة بالطريقة. على سبيل المثال، لا تعرض الطريقة files.list سوى حقول kind وid وname و mimeType.

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

بالنسبة إلى جميع طرق موارد about وcomments (باستثناء delete) وreplies (باستثناء delete)، يجب ضبط المَعلمة fields. لا تعرض هذه الطرق مجموعة تلقائية من الحقول.