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

ملاحظة مهمة: سنتوقف عن إتاحة الإصدار 2.0 JSON API في 30 أيلول (سبتمبر) 2024. لضمان استمرار عمل الوظائف، عليك تحديث تطبيقاتك التي تعتمد على الإصدار 2.0 JSON API إلى أحدث إصدار من واجهة برمجة التطبيقات. للحصول على أحدث إصدار، استخدِم الروابط في شريط التنقّل الأيمن.

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

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

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

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

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

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

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

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

• الاستجابة الجزئية: طلب يمكنك من خلاله تحديد الحقول المطلوب تضمينها في الرد (استخدِم مَعلمة الطلب fields).
• Patch (تصحيح): طلب تعديل يتم من خلاله إرسال الحقول التي تريد تغييرها فقط (استخدِم فعل 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 فقط في كل عنصر.

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

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

يمكنك أيضًا تجنُّب إرسال بيانات غير ضرورية عند تعديل الموارد. لإرسال البيانات المعدّلة للحقول المحدّدة التي تريد تغييرها فقط، استخدِم فعل 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 الخالية.

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

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

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

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