Blogger JSON API: نصائح بشأن الأداء

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

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

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

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

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

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

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

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

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

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

الاستجابة الجزئية

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

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

يُرجى العِلم أنّ المَعلمة fields تؤثّر فقط في بيانات الاستجابة، ولا تؤثّر في البيانات التي عليك إرسالها، إن وُجدت. لتقليل مقدار البيانات التي ترسلها عند تعديل الموارد، استخدِم طلب تصحيح.

مثال

يعرض المثال التالي كيفية استخدام مَعلمة fields مع واجهة برمجة تطبيقات عامة (خيالية) "تجريبية".

طلب بسيط: هذا الطلب من نوع GET‏ HTTP لا يتضمّن مَعلمة 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

يعتمد تنسيق قيمة المَعلمة في طلب 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/* تحدّد جميع الكائنات داخل 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، يُرسل رمز الحالة 200 OK HTTP مع البيانات المطلوبة. أما إذا كانت معلمَة طلب البحث fields تحتوي على خطأ أو كانت غير صالحة، يعرض الخادم رمز الحالة 400 Bad Request HTTP مصحوبًا برسالة خطأ تُخبر المستخدم بالخلل في الحقول التي اختارها (مثلاً "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 API، استخدِم Data.NULL_STRING بدلاً من ذلك. لمزيد من التفاصيل، اطّلِع على JSON null.

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

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

يمكن أن تكون هذه العملية مفيدة للبدء باسترداد استجابة جزئية تتضمّن البيانات التي تريد تعديلها. ويكون ذلك مهمًا بشكل خاص للموارد التي تستخدم علامات 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. */
  },
}

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

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