تحسين الأداء

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

يبدأ كل جزء بعنوان 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--