يتناول هذا المستند بعض الأساليب التي يمكنك استخدامها لتحسين أداء تطبيقك. في بعض الحالات، يتم استخدام أمثلة من واجهات برمجة تطبيقات أخرى أو واجهات برمجة تطبيقات عامة لتوضيح الأفكار المقدَّمة. ومع ذلك، تنطبق المفاهيم نفسها على واجهات برمجة التطبيقات في "صور Google".
الضغط باستخدام gzip
وهناك طريقة سهلة وملائمة لتقليل معدل نقل البيانات اللازم لكل طلب، وهي تمكين الضغط بتنسيق gzip. وعلى الرغم من أن هذا يتطلب وقتًا إضافيًا لوحدة المعالجة المركزية (CPU) لفك ضغط النتائج، فإن المقايضة مع تكاليف الشبكة عادةً ما تجعل الأمر مفيدًا للغاية.
لتلقّي استجابة مُشفَّرة بتنسيق gzip، عليك إجراء أمرَين: ضبط رأس Accept-Encoding
وتعديل وكيل المستخدم ليحتوي على السلسلة gzip
. في ما يلي مثال على عناوين HTTP مكتوبة بشكل صحيح لتفعيل ضغط gzip:
Accept-Encoding: gzip User-Agent: my program (gzip)
العمل مع موارد جزئية
هناك طريقة أخرى لتحسين أداء طلبات البيانات من واجهة برمجة التطبيقات، وهي طلب الجزء الذي يهمّك من البيانات فقط. يتيح ذلك لتطبيقك تجنُّب نقل الحقول غير المطلوبة وتحليلها وتخزينها، ما يتيح له استخدام الموارد، بما في ذلك الشبكة ووحدة المعالجة المركزية والذاكرة، بكفاءة أكبر.
ردّ جزئي
يُرسِل الخادم تلقائيًا التمثيل الكامل لمورد بعد معالجة الطلبات. للحصول على أداء أفضل، يمكنك أن تطلب من الخادم إرسال الحقول التي تحتاج إليها فقط والحصول على استجابة جزئية بدلاً من ذلك.
لطلب استجابة جزئية، استخدِم مَعلمة الطلب fields
لتحديد الحقول التي تريد عرضها. يمكنك استخدام هذه المَعلمة مع أي طلب يعرض بيانات استجابة.
مثال
يعرض المثال التالي استخدام المَعلمة fields
مع واجهة برمجة تطبيقات عامة (خيالية) باسم "Demo".
طلب بسيط: يحذف طلب 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
لكل عنصر في صفيف items، لا يعرض سوى حقل 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
على سبيل المثال)، استخدِم هذه المَعلمات لتصغير نتائج كل طلب بحث إلى حجم يمكن التعامل معه. وبخلاف ذلك، قد لا يتم تحقيق مكاسب الأداء الممكنة في حالة استجابة جزئية.