درخواست های دسته ای

این سند نشان می‌دهد که چگونه فراخوانی‌های API را دسته‌بندی کنید تا تعداد اتصالاتی که کلاینت شما باید برقرار کند، کاهش یابد. دسته‌بندی می‌تواند با کاهش رفت و برگشت‌های شبکه و افزایش توان عملیاتی، کارایی یک برنامه را بهبود بخشد.

نمای کلی

هر اتصالی که کلاینت شما ایجاد می‌کند، منجر به مقدار مشخصی سربار می‌شود. API گوگل شیت از دسته‌بندی پشتیبانی می‌کند تا به کلاینت شما اجازه دهد چندین شیء درخواست را که هر کدام نوع درخواستی را برای اجرا مشخص می‌کنند، در یک درخواست دسته‌ای قرار دهد. یک درخواست دسته‌ای می‌تواند با ترکیب چندین زیردرخواست در یک فراخوانی واحد به سرور و بازیابی یک پاسخ واحد، عملکرد را افزایش دهد.

ما کاربران را تشویق می‌کنیم که همیشه چندین درخواست را با هم دسته بندی کنند. در اینجا چند نمونه از موقعیت‌هایی که می‌توانید از دسته بندی استفاده کنید، آورده شده است:

• شما به تازگی استفاده از API را شروع کرده‌اید و داده‌های زیادی برای آپلود دارید.
• شما باید فراداده‌ها یا ویژگی‌هایی مانند قالب‌بندی را در چندین شیء به‌روزرسانی کنید.
• شما باید اشیاء زیادی را حذف کنید.

محدودیت‌ها، مجوزها و ملاحظات وابستگی

در اینجا لیستی از موارد دیگری که باید هنگام استفاده از به‌روزرسانی دسته‌ای در نظر بگیرید، آورده شده است:

• هر درخواست دسته‌ای، شامل تمام زیردرخواست‌ها، به عنوان یک درخواست API در محدودیت استفاده شما محاسبه می‌شود.
• یک درخواست دسته‌ای یک بار احراز هویت می‌شود. این احراز هویت واحد برای همه اشیاء به‌روزرسانی دسته‌ای در درخواست اعمال می‌شود.
• سرور، زیردرخواست‌ها را به همان ترتیبی که در درخواست دسته‌ای ظاهر می‌شوند، پردازش می‌کند. زیردرخواست‌های بعدی می‌توانند به اقداماتی که در طول زیردرخواست‌های قبلی انجام شده است، وابسته باشند. برای مثال، در همان درخواست دسته‌ای، کاربران می‌توانند متن را در یک سند موجود وارد کرده و سپس آن را سبک‌بندی کنند.

جزئیات دسته‌ای

یک درخواست دسته‌ای شامل یک فراخوانی متد batchUpdate با چندین زیردرخواست برای مثال، اضافه کردن و سپس قالب‌بندی یک صفحه گسترده است.

هر درخواست قبل از اعمال، اعتبارسنجی می‌شود. تمام زیردرخواست‌ها در به‌روزرسانی دسته‌ای به صورت خودکار اعمال می‌شوند. یعنی اگر هر درخواستی معتبر نباشد، کل به‌روزرسانی ناموفق است و هیچ یک از تغییرات (که به طور بالقوه وابسته هستند) اعمال نمی‌شوند.

برخی از درخواست‌ها، پاسخ‌هایی حاوی اطلاعات مربوط به درخواست‌های اعمال‌شده ارائه می‌دهند. برای مثال، تمام درخواست‌های به‌روزرسانی دسته‌ای برای افزودن اشیاء، پاسخ‌هایی را برمی‌گردانند تا بتوانید به فراداده‌های شیء تازه اضافه‌شده، مانند شناسه یا عنوان، دسترسی داشته باشید.

با این رویکرد، می‌توانید با استفاده از یک درخواست به‌روزرسانی دسته‌ای API با چندین زیردرخواست، یک سند کامل گوگل بسازید.

قالب درخواست دسته‌ای

یک درخواست ، یک درخواست JSON واحد است که شامل چندین زیردرخواست تو در تو با یک ویژگی مورد نیاز است: requests . درخواست‌ها در آرایه‌ای از درخواست‌های منفرد ساخته می‌شوند. هر درخواست از JSON برای نمایش شیء درخواست و شامل ویژگی‌های آن استفاده می‌کند.

قالب پاسخ دسته‌ای

قالب پاسخ برای یک درخواست دسته‌ای مشابه قالب درخواست است. پاسخ سرور شامل یک پاسخ کامل از شیء پاسخ واحد است.

ویژگی اصلی شیء JSON، replies نام دارد. پاسخ‌ها در یک آرایه برگردانده می‌شوند، که هر پاسخ به یکی از درخواست‌ها، همان ترتیب اندیس درخواست مربوطه را اشغال می‌کند. برخی از درخواست‌ها پاسخی ندارند و پاسخ در آن اندیس آرایه خالی است.

مثال

مثال زیر استفاده از دسته‌بندی با Sheets API را نشان می‌دهد.

درخواست

این مثال از درخواست دسته‌ای نشان می‌دهد که چگونه:

• با استفاده از AddSheetRequest ، یک برگه به ​​صفحه گسترده موجود با sheetId برابر با ۱۲۳۴۵ اضافه کنید.
• با استفاده از UpdateCellsRequest ، داده‌ها را به برگه جدید اضافه کنید، از سلول A1 شروع کنید.
• یک نمای namedRange یا filter به برگه جدید اضافه کنید.

با اضافه کردن شناسه برگه در درخواست، کاربران می‌توانند از شناسه برگه برای سایر زیردرخواست‌ها در همان فراخوانی API استفاده کنند. این کار با جلوگیری از چرخه نوشتن-خواندن-نوشتن، عملکرد را بهبود می‌بخشد.

برای فهرستی از انواع درخواست‌های به‌روزرسانی دسته‌ای، که در دسته‌های مختلف گروه‌بندی شده‌اند، به جدول زیر عملیات به‌روزرسانی دسته‌ای مراجعه کنید.

{
   "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
            }
         }
      }
   }
]