الطلبات المجمّعة

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

نظرة عامة

ينتج عن كل عملية ربط يجريها عميلك مقدار معين من النفقات العامة. تتيح واجهة برمجة التطبيقات Google Docs API التجميع للسماح للعميل بوضع عدة كائنات طلبات، كل عنصر يحدد نوعًا واحدًا من الطلب لتنفيذه، في طلب مُجمَّع واحد. ويمكن أن يؤدي الطلب المجمّع إلى تحسين الأداء من خلال دمج عدة طلبات فرعية في استدعاء واحد للخادم، ما يؤدي إلى استرداد ردّ واحد.

ننصح المستخدمين دائمًا بتجميع عدة طلبات معًا. في ما يلي بعض الأمثلة على الحالات التي يمكنك فيها استخدام التجميع:

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

اعتبارات الحدود والتفويض والتبعية

في ما يلي قائمة بالعناصر الأخرى التي يجب مراعاتها عند استخدام التحديث المجمع:

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

تفاصيل الدفعة

يتكون الطلب المجمّع من طلب طريقة batchUpdate واحد مع عدة طلبات فرعية، على سبيل المثال، لإضافة مستند ثم تنسيقه.

يتم التحقّق من صحة كل طلب قبل تطبيقه. يتم تطبيق كل الطلبات الفرعية في التحديث المجمّع بشكل كامل. ويعني ذلك أنّه إذا كان أي طلب غير صالح، لن ينجح التعديل بأكمله ولن يتم تطبيق أي من التغييرات (التي يُحتمل أن تكون تابعة).

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

تتيح لك هذه الطريقة إنشاء مستند Google بالكامل باستخدام طلب تعديل مجمّع واحد من واجهة برمجة التطبيقات مع عدة طلبات فرعية.

تنسيق الطلب المجمّع

الطلب هو طلب JSON واحد يحتوي على عدة طلبات فرعية مدمَجة مع سمة واحدة مطلوبة: requests. ويتم إنشاء الطلبات في مصفوفة من الطلبات الفردية. ويستخدم كل طلب JSON لتمثيل كائن الطلب واحتواء سماته.

تنسيق رد مُجمَّع

يشبه تنسيق الردّ للطلب المجمّع تنسيق الطلب. ويحتوي استجابة الخادم على رد كامل لكائن استجابة واحد.

يُطلَق على سمة كائن JSON الرئيسي اسم replies. ويتم عرض الاستجابات في مصفوفة، وتشغل كل استجابة لأحد الطلبات ترتيب الفهرس نفسه للطلب المقابل. بعض الطلبات لا تحتوي على ردود، وتكون الاستجابة في فهرس الصفيف هذا فارغة.

مثال

يعرض نموذج الرمز البرمجي التالي استخدام التجميع باستخدام واجهة برمجة تطبيقات "مستندات Google".

الطلب

يوضح هذا المثال على الطلب المجمّع كيفية:

  • يمكنك إدراج نص "Hello World" في بداية مستند حالي، مع الفهرس location من 1، باستخدام InsertTextRequest.

  • يمكنك تعديل كلمة "مرحبًا" باستخدام UpdateTextStyleRequest. يحدد كل من startIndex وendIndex القيمة range للنص المنسّق داخل المقطع.

  • باستخدام textStyle، اضبط نمط الخط على الغامق واللون إلى الأزرق لكلمة "مرحبًا" فقط.

  • يمكنك باستخدام الحقل WriteControl التحكّم في كيفية تنفيذ طلبات الكتابة. لمزيد من المعلومات، يُرجى الاطّلاع على إنشاء اتّساق الحالة باستخدام WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

استبدِل REQUIRED_REVISION_ID بمعرّف النسخة السابقة للمستند الذي تم تطبيق طلب الكتابة عليه.

الإجابة

يعرض هذا المثال على الرد المجمّع معلومات عن كيفية تطبيق كل طلب فرعي ضمن الطلب المجمّع. ولا تحتوي السمة InsertTextRequest أو UpdateTextStyleRequest على استجابة، لذا تتألف قيم الفهرس في الصفيف في [0] و[1] من أقواس معقوفة فارغة. يعرض الطلب المجمّع كائن WriteControl الذي يوضح كيفية تنفيذ الطلبات.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}