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

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

نظرة عامة

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

الطلب

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

• إضافة ورقة إلى جدول بيانات حالي يحتوي على sheetId من 12345 باستخدام AddSheetRequest.
• أضِف البيانات إلى ورقة البيانات الجديدة، بدءًا من الخلية A1، باستخدام UpdateCellsRequest.
• أضِف namedRange أو عرض فلتر إلى ورقة البيانات الجديدة.

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

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

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

الإجابة

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

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]