تحسين الأداء

الضغط باستخدام 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، وتبقى حالة المورد بدون تغيير. على سبيل المثال، إذا حاولت حذف قيمة حقل مطلوب، سيعرض الخادم رسالة خطأ.

صيغة بديلة عندما لا يكون فعل 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 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 معيّنًا في كلّ من الطلب الخارجي والمكالمة الفردية، ستتجاوز قيمة عنوان المكالمة الفردية قيمة عنوان طلب الدفعة الخارجي. تنطبق العناوين الخاصة بمكالمة فردية على تلك المكالمة فقط.

على سبيل المثال، إذا قدّمت عنوان Authorization لطلب معيّن، سيتم تطبيق هذا العنوان على هذا الطلب فقط. إذا قدّمت عنوان Authorization للطلب الخارجي، سينطبق هذا العنوان على جميع الطلبات الفردية ما لم يتم تجاوزه بعناوين Authorization خاصة بها.

عندما يتلقّى الخادم الطلب المجمّع، يطبّق مَعلمات طلب البحث والرؤوس الخاصة بالطلب الخارجي (حسب الاقتضاء) على كل جزء، ثم يعامل كل جزء كما لو كان طلب 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--