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

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

نظرة عامة

يؤدي كل اتصال يجريه العميل إلى قدر معيّن من النفقات العامة. تتيح واجهة 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
            }
         }
      }
   }
]