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

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

نظرة عامة

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

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

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

اعتبارات الحدود والترخيص واعتبارات التبعية

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

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

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

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

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

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

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

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

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

تنسيق الرد المجمّع

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

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

مثال

يوضح المثال التالي استخدام التجميع باستخدام Docs API.

الطلب

يوضح هذا المثال على الطلب المجمّع طريقة تنفيذ ما يلي:

  • أدخل النص "Hello World" في بداية مستند حالي، بالفهرس Location من 1، باستخدام InsertTextRequest.
  • يمكنك تعديل كلمة "مرحبًا" باستخدام UpdateTextStyleRequest. تحدّد السمتان startIndex وendIndex العنصر range للنص المنسَّق داخل المقطع.`
  • باستخدام textStyle، اضبط نمط الخط ليكون غامقًا واللون باللون الأزرق.
{
   "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"
         }
      }
   ]
}

الإجابة

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

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