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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

الطلب

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

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

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

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

• باستخدام الحقل WriteControl، يمكنك التحكّم في كيفية تنفيذ طلبات الكتابة. لمزيد من المعلومات، يُرجى الاطّلاع على الحفاظ على اتّساق الحالة باستخدام واجهة برمجة التطبيقات (WriteControl).

{
   "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"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

استبدِل REQUIRED_REVISION_ID بمعرّف النسخة السابقة للوثيقة التي يتم تطبيق طلب الكتابة عليها.

الإجابة

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

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

مواضيع ذات صلة

• أفضل الممارسات لتحقيق أفضل النتائج