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

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

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

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

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

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

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

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

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

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

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

ردّ جزئي

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

لطلب استجابة جزئية، استخدِم مَعلمة الطلب 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 في الردّ.

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

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

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

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

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" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

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

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

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

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

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

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