تحسين الأداء

الضغط باستخدام 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 والطول فقط في كل عنصر.

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