نصائح حول استخدام واجهة برمجة التطبيقات

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

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

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

أمثلة	التأثير
items	عرض جميع العناصر في مصفوفة السلع، بما في ذلك جميع الحقول في كل عنصر، ولكن بدون حقول أخرى.
etag,items	تُعيد كلّ من الحقل etag وجميع العناصر في صفيف العناصر.
items/title	لا تعرض سوى الحقل title لجميع العناصر في صفيف items. عند عرض حقل مدمج، يتضمن الردّ الكائنات الرئيسية المضمّنة. لا تتضمّن الحقول الرئيسية أي حقول فرعية أخرى ما لم يتم اختيارها أيضًا بشكل صريح.
context/facets/label	لا تعرض سوى الحقل label لجميع عناصر الصفيف facets، والذي يكون مُدمجًا بحد ذاته ضمن العنصر context.
items/pagemap/*/title	لكل عنصر في صفيف items، لا يعرض سوى حقل 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)، يمكنك استخدام هذه المَعلمات لتقليل نتائج كل طلب بحث إلى حجم يمكن إدارته. بخلاف ذلك، قد لا يتم تحقيق التحسينات في الأداء التي يمكن تحقيقها من خلال الاستجابة الجزئية.