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

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

نظرة عامة

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

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

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

اعتبارات الحدود والأذونات والتبعيات

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

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

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

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

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

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

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

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

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

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

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

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

مثال

يعرض نموذج الرمز التالي كيفية استخدام التجميع مع Docs API.

طلب

يوضّح طلب الدفعة النموذجي هذا كيفية إجراء ما يلي:

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

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

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

  • باستخدام حقل 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`
}