تحسين الأداء

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

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

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

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

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

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

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

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

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

المثال

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

طلب بسيط: هذا الطلب من نوع GET‏ HTTP لا يتضمّن مَعلمة 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

يعتمد تنسيق قيمة المَعلمة في طلب 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/* تحدّد جميع الكائنات داخل pagemap.

المزيد من الأمثلة على استخدام مَعلمة fields

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