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

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

نمای کلی

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مثال

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

درخواست

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

• با استفاده از متد CreateSlideRequest ، یک منبع presentations.pages به یک ارائه موجود با مقدار insertionIndex برابر با 1 اضافه کنید.

• با استفاده از متد CreateShapeRequest یک shapeType از نوع TEXT_BOX به اسلاید جدید اضافه کنید.

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

{
   "requests":[
      {
         "createSlide":{
            "insertionIndex":1,
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "elementProperties":{
               "pageObjectId":"newSlide",
               "size":{
                  "height":{
                     "magnitude":50,
                     "unit":"PT"
                  },
                  "width":{
                     "magnitude":200,
                     "unit":"PT"
                  }
               }
            },
            "shapeType":"TEXT_BOX",
            "objectId":"newTextBox"
         }
      },
      {
         "insertText":{
            "objectId":"newTextBox",
            "text":"Hello World"
         }
      }
   ]
}

پاسخ

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

{
   "requiredRevisionId": ID
   "presentationId": "",
   "replies":[
      {
         "createSlide":{
            "objectId":"newSlide"
         }
      },
      {
         "createShape":{
            "objectId":"newTextBox"
         }
      },
      {
         
      }
   ],
   "writeControl":{
      "requiredRevisionId": REVISION_ID
   }
}