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

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

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

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

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