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

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

نمای کلی

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

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

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

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

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

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

جزئیات دسته

یک درخواست دسته ای شامل یک فراخوانی متد batchUpdate با چندین درخواست فرعی برای اضافه کردن و سپس فرمت کردن یک سند است.

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

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

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

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

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

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

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

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

مثال

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

درخواست کنید

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

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

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

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

  • با استفاده از فیلد 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`
}
 ،

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

نمای کلی

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

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

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

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

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

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

جزئیات دسته

یک درخواست دسته ای شامل یک فراخوانی متد batchUpdate با چندین درخواست فرعی برای اضافه کردن و سپس فرمت کردن یک سند است.

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

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

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

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

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

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

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

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

مثال

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

درخواست کنید

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

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

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

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

  • با استفاده از فیلد 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`
}