نصائح متعلّقة بالأداء

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

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

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

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

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

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

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

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

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

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