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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

الطلب

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

• إضافة presentations.pages مورد لعرض تقديمي حالي، مع insertionIndex من 1، باستخدام الـ CreateSlideRequest .

• أضف shapeType من النوع TEXT_BOX إلى الشريحة الجديدة باستخدام CreateShapeRequest .

• إدراج "مرحبًا بالعالم" نص إلى الحقل الجديد باستخدام InsertTextRequest .

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

الرد

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

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}