تحسين الأداء

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

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

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

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

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

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

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

ردّ جزئي

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

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

مثال

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

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

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

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