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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

يوضح نموذج التعليمات البرمجية التالي استخدام التجميع باستخدام Slides API.

الطلب

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

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

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

• أدرج نص "Hello World" في الحقل الجديد باستخدام الطريقة 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
   }
}