نصائح حول الأداء

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

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

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

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

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

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

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

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

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

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

استجابة جزئية

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

لطلب رد جزئي، استخدم معلمة الطلب 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" في مواصفات 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 هي قائمة من الحقول مفصولة بفواصل، ويتم تحديد كل حقل بالنسبة إلى جذر الاستجابة. وبالتالي، إذا كنت تنفذ عملية قائمة، تكون الاستجابة عبارة عن مجموعة، وتشمل عمومًا مجموعة من الموارد. إذا كنت تجري عملية تعرض موردًا واحدًا، فسيتم تحديد الحقول وفقًا لهذا المورد. إذا كان الحقل الذي تختاره مصفوفة (أو جزءًا منها)، يعرض الخادم الجزء المحدّد من كل العناصر في المصفوفة.

في ما يلي بعض الأمثلة على مستوى المجموعة:

أمثلة	التأثير
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. إذا كنت تستخدم مكتبة عميل واجهة برمجة تطبيقات جافا، يمكنك استخدام Data.NULL_STRING بدلاً من ذلك، للحصول على التفاصيل، راجع JSON null.

ملاحظة حول المصفوفات: تستبدل طلبات التصحيح التي تحتوي على مصفوفات الصفيف الحالي بالمصفوفة التي تقدمها. لا يمكنك تعديل عناصر أو إضافتها أو حذفها في مصفوفة بطريقة جزئية.

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

يمكن أن يكون البدء ممارسة استرداد جزء من البيانات التي تريد تعديلها ممارسة مفيدة. ويُعدّ هذا مهمًا بشكل خاص للموارد التي تستخدم ETags، حيث يجب تقديم قيمة ETag الحالية في عنوان HTTP If-Match من أجل تعديل المورد بنجاح. بعد الحصول على البيانات، يمكنك تعديل القيم التي تريد تغييرها وإعادة إرسال التمثيل الجزئي المعدَّل مرة أخرى باستخدام طلب تصحيح. في ما يلي مثال يفترض أن المورد التجريبي يستخدم ETags:

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. */
  },
}

يستجيب الخادم برمز حالة 200 OK HTTP، والتمثيل الجزئي للمورد الذي تم تحديثه:

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. */
  }
}

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

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

ملاحظة: يمكنك استخدام رأس HTTP "If-Match: *" لفرض تصحيح عملية تصحيح الأخطاء عندما تكون أداة ETags قيد الاستخدام. وإذا فعلت ذلك، لن تحتاج إلى إجراء القراءة قبل الكتابة.

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

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 مع التمثيل الكامل للمورد المعدّل. في حال استخدام واجهة برمجة التطبيقات ETags، يعدّل الخادم قيم ETag عندما يعالج طلب تصحيح بنجاح، كما هو الحال مع PUT.

يعرض طلب حزمة التصحيح تمثيل المورد بالكامل ما لم تستخدم المعلمة fields لتقليل مقدار البيانات التي يعرضها.

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

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

إذا كان الجدار الناري لا يسمح بطلبات HTTP PATCH، يمكنك تنفيذ طلب HTTP POST وضبط عنوان الإلغاء على PATCH، كما هو موضّح أدناه:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

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

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

لذلك فإن استخدام التصحيحات أكثر أمانًا لهذا السبب. ما عليك سوى توفير البيانات للحقول التي تريد تغييرها، ولا يتم محو الحقول التي تم حذفها. الاستثناء الوحيد لهذه القاعدة يحدث مع العناصر أو المصفوفات المتكررة: إذا حذفتها كلها، فستظل كما هي؛ وإذا قدمت أيًا منها، فسيتم استبدال المجموعة بأكملها بالمجموعة التي تقدمها.