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

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

نظرة عامة

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