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