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

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

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

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

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

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

استخدام موارد جزئية

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

يتوفّر نوعان من الطلبات الجزئية:

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

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

ردّ جزئي

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

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

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

المثال

يعرض المثال التالي كيفية استخدام مَعلمة fields مع واجهة برمجة تطبيقات عامة (خيالية) "تجريبية".

طلب بسيط: هذا الطلب من نوع GET‏ HTTP لا يتضمّن مَعلمة 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

يعتمد تنسيق قيمة المَعلمة في طلب fields على قواعد مستوحاة بشكل عام من بنية XPath. في ما يلي تلخيص للبنية المتوافقة مع أمثلة إضافية في الفقرة التالية.

• استخدِم قائمة قيم مفصولة بفاصلة عند اختيار أكثر من حقل.
• استخدِم a/b لاختيار حقل b مُدمج في حقل a، واستخدِم a/b/c لاختيار حقل c مُدمج في b.
  

  استثناء: في حال كانت استجابات واجهة برمجة التطبيقات تستخدم مغلفات البيانات، أي عندما تكون البيانات مُدمجة ضمن كائن data بالشكل التالي: data: { ... }، لا تدرِج "data" في مواصفات fields. يؤدي تضمين كائن البيانات مع مواصفات `fields` مثل data/a/b إلى حدوث خطأ. بدلاً من ذلك، استخدِم ببساطة مواصفات fields مثل a/b.

• استخدِم أداة اختيار فرعية لطلب حقول فرعية محددة للمصفوفات أو الكائنات، وذلك من خلال وضع العبارات بين قوسَين "( )".

  على سبيل المثال، القيمة fields=items(id,author/email) تعرض فقط معرّف العنصر والبريد الإلكتروني الخاص بالمؤلف لكل عنصر في مصفوفة العناصر. يمكنك أيضًا تحديد حقل فرعي واحد فقط، حيث تكون القيمة fields=items(id) مكافئة لـ fields=items/id.

• استخدِم أحرف البدل عند تحديد الحقول إذا لزم الأمر.

  على سبيل المثال، القيمة fields=items/pagemap/* تحدّد جميع الكائنات داخل pagemap.

المزيد من الأمثلة على استخدام مَعلمة fields

تصف الأمثلة الواردة أدناه كيفية تأثير قيمة المَعلمة 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، يُرسل رمز الحالة 200 OK HTTP مع البيانات المطلوبة. أما إذا كانت معلمَة طلب البحث fields تحتوي على خطأ أو كانت غير صالحة، يعرض الخادم رمز الحالة 400 Bad Request HTTP مصحوبًا برسالة خطأ تُخبر المستخدم بالخلل في الحقول التي اختارها (مثلاً "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",
  ...
}

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

ملاحظة: إذا كنت تستخدم مَعلمة الاستجابة الجزئية fields بالاقتران مع التصحيح، يمكنك زيادة كفاءة طلبات التعديل بشكلٍ أكبر. يقلّل طلب التصحيح حجم الطلب فقط. يقلّل الردّ الجزئي حجم الاستجابة. لذلك، لتقليل مقدار البيانات المُرسَلة في كلا الاتجاهَين، استخدِم طلب تصحيح مع مَعلمة fields.

دلالات طلب التصحيح

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

• الإضافة: لإضافة حقل غير موجود، حدِّد الحقل الجديد وقيمته.
• التعديل: لتغيير قيمة حقل حالي، حدِّد الحقل واضبطه على القيمة الجديدة.
  
• الحذف: لحذف حقل، حدِّد الحقل واضبطه على null. على سبيل المثال، "comment": null. يمكنك أيضًا حذف كائن بأكمله (إذا كان قابلاً للتعديل) من خلال ضبطه على null. إذا كنت تستخدم مكتبة عملاء Java API، استخدِم 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. */
  },
}

يستجيب الخادم برمز الحالة HTTP‏ `200 OK`، والتمثيل الجزئي للمورد المعدَّل:

200 OK

{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" g>"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‏ PATCH متوافقًا

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

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

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

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

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