تحسين الأداء

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

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

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

لتلقّي استجابة بترميز gzip، عليك إجراء ما يلي: ضبط عنوان Accept-Encoding وتعديل وكيل المستخدم ليحتوي على السلسلة gzip. في ما يلي مثال على عناوين HTTP منسَّقة بشكل صحيح لتفعيل ضغط gzip:

Accept-Encoding: gzip
User-Agent: my program (gzip)

التعامل مع الموارد الجزئية

هناك طريقة أخرى لتحسين أداء طلبات البيانات من واجهة برمجة التطبيقات وهي طلب جزء البيانات الذي يهمّك فقط. يتيح ذلك لتطبيقك تجنُّب نقل الحقول غير الضرورية وتحليلها وتخزينها، ما يتيح له استخدام الموارد، بما في ذلك الشبكة ووحدة المعالجة المركزية والذاكرة، بشكل أكثر فعالية.

ردّ جزئي

بشكلٍ تلقائي، يعيد الخادم إرسال التمثيل الكامل لمورد بعد معالجة الطلبات. للحصول على أداء أفضل، يمكنك أن تطلب من الخادم إرسال الحقول التي تحتاج إليها فقط والحصول على ردّ جزئي بدلاً من ذلك.

لطلب استجابة جزئية، استخدِم مَعلمة الطلب 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 في الردّ.

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