نصائح حول الأداء

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

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

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

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

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

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

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

هناك نوعان من الطلبات الجزئية:

  • الاستجابة الجزئية: طلب تحدد من خلاله الحقول التي سيتم تضمينها في الرد (استخدم معلمة الطلب fields).
  • تصحيح: طلب تحديث يتم من خلاله إرسال الحقول التي تريد تغييرها فقط (استخدم فعل HTTP PATCH).

تتوفر في الأقسام التالية المزيد من التفاصيل حول تقديم طلبات جزئية.

ردّ جزئي

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

لطلب استجابة جزئية، يمكنك استخدام مَعلمة الطلب fields لتحديد الحقول التي تريد عرضها. يمكنك استخدام هذه المَعلمة مع أي طلب يعرض بيانات الاستجابة.

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

رمز تصحيح (تحديث جزئي)

يمكنك أيضًا تجنب إرسال بيانات غير ضرورية عند تعديل الموارد. لإرسال البيانات المعدّلة للحقول المحدّدة التي تريد تغييرها فقط، استخدِم فعل HTTP PATCH. دلالات التصحيح الموضحة في هذا المستند مختلفة (وأبسط) عما كانت عليه في تطبيق GData القديم للتحديث الجزئي.

يوضح المثال المختصر أدناه كيف يؤدي استخدام رمز التصحيح إلى تقليل البيانات التي تحتاج إلى إرسالها لإجراء تحديث بسيط.

مثال

يعرض هذا المثال طلب تصحيح بسيطًا لتعديل عنوان مورد واجهة برمجة تطبيقات عام (خيال) فقط. يحتوي المورد أيضًا على تعليق ومجموعة من الخصائص والحالة والعديد من الحقول الأخرى، ولكن هذا الطلب لا يرسل سوى الحقل title، لأنّه الحقل الوحيد الذي يتم تعديله:

PATCH https://www.googleapis.com/demo/v1/324
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "title": "New title"
}

الرد:

200 OK
{
  "title": "New title",
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "accuracy": "high",
    "followers": ["Jo", "Will"],
  },
  "status": "active",
  ...
}

يعرض الخادم رمز الحالة 200 OK، مع التمثيل الكامل للمورد الذي تم تعديله. نظرًا لأنه تم تضمين الحقل title فقط في طلب التصحيح، فهذه هي القيمة الوحيدة التي تختلف عما كانت عليه من قبل.

ملاحظة: إذا استخدمت مَعلمة fields الاستجابة الجزئية مع رمز التصحيح، يمكنك زيادة كفاءة طلبات التحديث بشكل أكبر. طلب التصحيح يقلل حجم الطلب فقط. الرد الجزئي يقلل حجم الرد. لتقليل كمية البيانات المرسلة في كلا الاتجاهين، استخدم طلب تصحيح مع المعلمة fields.

دلالات طلب التصحيح

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

  • الإضافة: لإضافة حقل غير متوفّر، حدِّد الحقل الجديد وقيمته.
  • التعديل: لتغيير قيمة حقل حالي، حدِّد الحقل واضبطه على القيمة الجديدة.
  • الحذف: لحذف حقل، حدِّد الحقل واضبطه على null. مثلاً: "comment": null يمكنك أيضًا حذف عنصر بالكامل (إذا كان قابلاً للتغيير) من خلال ضبطه على null. إذا كنت تستخدم مكتبة برامج واجهة برمجة تطبيقات Java، استخدِم Data.NULL_STRING بدلاً منها. لمزيد من التفاصيل، يُرجى الاطّلاع على واجهة JSON الخالية.

ملاحظة بشأن المصفوفات: تستبدل طلبات التصحيح التي تحتوي على المصفوفات الصفيف الحالي بالمصفوفة التي تقدمها. لا يمكنك تعديل العناصر في مصفوفة أو إضافتها أو حذفها بشكل جزئي.

استخدام حزمة التصحيح في دورة قراءة-تعديل-كتابة

قد يكون من المفيد البدء باسترداد رد جزئي بالبيانات التي تريد تعديلها. ويُعدّ ذلك مهمًا على وجه الخصوص للموارد التي تستخدم علامات ETag، لأنّه يجب توفير قيمة ETag الحالية في عنوان HTTP الذي يتضمّن السمة If-Match لتعديل المورد بنجاح. بعد الحصول على البيانات، يمكنك تعديل القيم التي تريد تغييرها وإرسال التمثيل الجزئي المعدّل مرة أخرى مع طلب تصحيح. فيما يلي مثال يفترض أن مورد العرض التوضيحي يستخدم علامات ETag:

GET https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token

هذه هي الإجابة الجزئية:

200 OK
{
  "etag": "ETagString"
  "title": "New title"
  "comment": "First comment.",
  "characteristics": {
    "length": "short",
    "level": "5",
    "followers": ["Jo", "Will"],
  }
}

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

PATCH https://www.googleapis.com/demo/v1/324?fields=etag,title,comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json
If-Match: "ETagString"
{
  "etag": "ETagString"
  "title": "",                  /* Clear the value of the title by setting it to the empty string. */
  "comment": null,              /* Delete the comment by replacing its value with null. */
  "characteristics": {
    "length": "short",
    "level": "10",              /* Modify the level value. */
    "followers": ["Jo", "Liz"], /* Replace the followers array to delete Will and add Liz. */
    "accuracy": "high"          /* Add a new characteristic. */
  },
}

يستجيب الخادم برمز حالة 200 OK HTTP، والتمثيل الجزئي للمورد الذي تم تحديثه:

200 OK
{
  "etag": "newETagString"
  "title": "",                 /* Title is cleared; deleted comment field is missing. */
  "characteristics": {
    "length": "short",
    "level": "10",             /* Value is updated.*/
    "followers": ["Jo" "Liz"], /* New follower Liz is present; deleted Will is missing. */
    "accuracy": "high"         /* New characteristic is present. */
  }
}

إنشاء طلب تصحيح مباشرةً

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

ملاحظة: يمكنك استخدام عنوان HTTP يتضمّن "If-Match: *" لفرض إكمال التصحيح أثناء استخدام علامات ETag. في حال إجراء ذلك، لن تحتاج إلى القراءة قبل الكتابة.

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

PATCH https://www.googleapis.com/demo/v1/324?fields=comment,characteristics
Authorization: Bearer your_auth_token
Content-Type: application/json

{
  "comment": "A new comment",
  "characteristics": {
    "volume": "loud",
    "accuracy": null
  }
}

مع هذا الطلب، إذا كان حقل التعليق يحتوي على قيمة حالية، ستستبدلها القيمة الجديدة، وإلا سيتم ضبطها على القيمة الجديدة. وبالمثل، إذا كانت هناك خاصية الحجم، يتم استبدال قيمتها؛ إذا لم تكن كذلك، يتم إنشاؤها. تتم إزالة حقل الدقة، في حال ضبطه.

معالجة الاستجابة لإرسال رمز تصحيح

بعد معالجة طلب تصحيح صالح، تعرض واجهة برمجة التطبيقات رمز استجابة HTTP 200 OK مع التمثيل الكامل للمورد المعدّل. في حال استخدام علامات ETag من خلال واجهة برمجة التطبيقات، يعدّل الخادم قيم ETag عندما يعالج طلب تصحيح بنجاح، تمامًا كما يفعل PUT.

يعرض طلب حزمة التصحيح تمثيل المورد بأكمله ما لم تستخدم المعلمة fields لتقليل كمية البيانات التي يعرضها.

إذا أدى طلب التصحيح إلى حالة مورد جديدة غير صالحة من ناحية البنية أو دلاليًا، يعرض الخادم رمز حالة HTTP 400 Bad Request أو 422 Unprocessable Entity، وتظل حالة المورد بدون تغيير. على سبيل المثال، إذا حاولت حذف قيمة حقل مطلوب، سيعرض الخادم خطأ.

التدوين البديل عندما يكون فعل PATCH HTTP غير معتمد

في حال كان الجدار الناري لا يسمح بطلبات HTTP PATCH، يمكنك تنفيذ طلب HTTP POST وضبط عنوان الإلغاء على PATCH، كما هو موضّح أدناه:

POST https://www.googleapis.com/...
X-HTTP-Method-Override: PATCH
...

الفرق بين التصحيح والتحديث

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

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