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

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

نظرة عامة

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