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

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

نمای کلی

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

نمونه کد زیر استفاده از دسته‌بندی با API اسناد را نشان می‌دهد.

درخواست

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

  • متن "Hello World" را با استفاده از InsertTextRequest در ابتدای یک سند موجود، با location اندیس 1 ، وارد کنید.

  • کلمه "Hello" را با استفاده از UpdateTextStyleRequest به‌روزرسانی کنید. startIndex و endIndex range متن قالب‌بندی شده را در داخل سگمنت تعریف می‌کنند.

  • با استفاده از textStyle ، سبک فونت را فقط برای کلمه "Hello" روی bold و رنگ آن را روی آبی تنظیم کنید.

  • با استفاده از فیلد WriteControl ، می‌توانید نحوه اجرای درخواست‌های نوشتن را کنترل کنید. برای اطلاعات بیشتر، به بخش «ایجاد ثبات حالت با WriteControl» مراجعه کنید. 

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

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

پاسخ

این نمونه پاسخ دسته‌ای، اطلاعاتی در مورد نحوه اعمال هر زیردرخواست در درخواست دسته‌ای را نمایش می‌دهد. هیچ‌کدام از درخواست‌های InsertTextRequest یا UpdateTextStyleRequest حاوی پاسخی نیستند، بنابراین مقادیر اندیس آرایه در [0] و [1] شامل آکولادهای خالی هستند. درخواست دسته‌ای، شیء WriteControl را نمایش می‌دهد که نحوه اجرای درخواست‌ها را نشان می‌دهد.

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}