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