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

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

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

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

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