واجهة برمجة تطبيقات Blogger JSON: نصائح بشأن الأداء

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

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

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

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

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

استخدام موارد جزئية

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

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

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

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

ردّ جزئي

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

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

لاحظ أن المعلّمة 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"quot، حيث يتم دمج الاستجابة في كائن 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 وauthor's 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 القديم مع التحديث الجزئي.

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

مثال

يوضح هذا المثال طلب تصحيح بسيطًا لتحديث عنوان مورد (عام) (وهمي) و"Demo"##Demo" فقط. يحتوي المورد أيضًا على تعليق ومجموعة من الخصائص والحالة والعديد من الحقول الأخرى، ولكن هذا الطلب يرسل الحقل 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 Empty.

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

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

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

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. */
  },
}

يستجيب الخادم برمز حالة HTTP 200 OK، وتمثيل جزئي للمورد المُعدَّل:

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: *" لإلزام حزمة التصحيحات باستخدامها. إذا فعلت ذلك، لست بحاجة إلى قراءة النص قبل الكتابة.

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

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 تمثيل كامل للمورد المعدَّل. في حال استخدمت واجهة برمجة التطبيقات (Eالعلامات) واجهة برمجة التطبيقات، يعدّل الخادم قيم ETag عند معالجة طلب تصحيح بنجاح، كما هو الحال مع PUT.

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

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

الترميز البديل عندما لا يكون إجراء فعل PATCH متوافقًا

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

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

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

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

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