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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

الطلب

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

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

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

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

  • استخدام WriteControl يمكنك التحكم في كيفية تنفيذ طلبات الكتابة. لمزيد من المعلومات، ، اطلع على تأسيس اتّساق الحالة مع WriteControl.

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "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"
  }
}

استبدال TAB_ID وREQUIRED_REVISION_ID بـ معرف علامة التبويب ومعرف النسخة السابقة، على التوالي، للمستند الذي يتضمن طلب الكتابة تنطبق عليه.

الرد

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

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