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