با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.
این سند نشان می‌دهد که چگونه می‌توانید تماس‌های API را با هم دسته‌بندی کنید تا تعداد اتصال‌هایی که مشتری شما باید برقرار کند را کاهش دهید. بچینگ می تواند با کاهش رفت و برگشت شبکه و افزایش توان عملیاتی، کارایی برنامه را بهبود بخشد.
نمای کلی
هر اتصالی که مشتری شما ایجاد می کند منجر به مقدار معینی سربار می شود. Google Slides API از دسته‌بندی پشتیبانی می‌کند تا به مشتری شما امکان می‌دهد چندین شی درخواست را که هر کدام یک نوع درخواست را برای انجام مشخص می‌کنند، در یک درخواست دسته‌ای قرار دهد. یک درخواست دسته ای می تواند با ترکیب چندین درخواست فرعی در یک تماس با سرور، عملکرد را افزایش دهد و یک پاسخ را بازیابی کند.
ما کاربران را تشویق می کنیم که همیشه چندین درخواست را با هم دسته بندی کنند. در اینجا چند نمونه از موقعیت هایی وجود دارد که می توانید از بچینگ استفاده کنید:
شما به تازگی استفاده از API را شروع کرده اید و داده های زیادی برای آپلود دارید.
شما باید متادیتا یا ویژگی‌هایی مانند قالب‌بندی را روی چندین شیء به‌روزرسانی کنید.
شما باید بسیاری از اشیاء را حذف کنید.
محدودیت ها، مجوزها، و ملاحظات وابستگی
در اینجا لیستی از موارد دیگری وجود دارد که باید هنگام به‌روزرسانی دسته‌ای در نظر بگیرید:
هر درخواست دسته‌ای، از جمله همه درخواست‌های فرعی، به عنوان یک درخواست API برای محدودیت استفاده شما محاسبه می‌شود.
درخواست دسته ای یک بار احراز هویت می شود. این احراز هویت واحد برای همه اشیاء به‌روزرسانی دسته‌ای در درخواست اعمال می‌شود.
سرور درخواست های فرعی را به همان ترتیبی که در درخواست دسته ای ظاهر می شوند پردازش می کند. درخواست‌های فرعی بعدی می‌تواند به اقدامات انجام شده در طول درخواست‌های فرعی قبلی بستگی داشته باشد. به عنوان مثال، در همان درخواست دسته ای، کاربران می توانند متنی را در یک سند موجود وارد کنند و سپس به آن استایل دهند.
جزئیات دسته
یک درخواست دسته ای شامل یک فراخوانی متد batchUpdate با چندین درخواست فرعی برای افزودن و سپس فرمت یک ارائه است.
هر درخواست قبل از اعمال تایید می شود. همه درخواست‌های فرعی در به‌روزرسانی دسته‌ای به صورت اتمی اعمال می‌شوند. یعنی اگر هر درخواستی معتبر نباشد، کل به روز رسانی ناموفق است و هیچ یک از تغییرات (بالقوه وابسته) اعمال نمی شود.
برخی از درخواست‌ها پاسخ‌هایی را با اطلاعات درخواست‌های اعمال شده ارائه می‌دهند. برای مثال، تمام درخواست‌های به‌روزرسانی دسته‌ای برای افزودن اشیا، پاسخ‌ها را برمی‌گردانند تا بتوانید به ابرداده‌های شی جدید اضافه‌شده، مانند شناسه یا عنوان دسترسی داشته باشید.
با این رویکرد، می‌توانید کل سند Google را با استفاده از یک درخواست به‌روزرسانی دسته‌ای API با چندین درخواست فرعی بسازید.
فرمت درخواست دسته ای
درخواست یک درخواست JSON منفرد است که شامل چندین درخواست فرعی تودرتو با یک ویژگی مورد نیاز است: requests . درخواست ها در آرایه ای از درخواست های فردی ساخته می شوند. هر درخواست از JSON برای نمایش شی درخواست و حاوی ویژگی های آن استفاده می کند.
قالب یک پاسخ دسته ای
فرمت پاسخ برای درخواست دسته ای مشابه فرمت درخواست است. پاسخ سرور حاوی یک پاسخ کامل از شیء پاسخ واحد است.
ویژگی اصلی شیء JSON replies نام دارد. پاسخ‌ها در یک آرایه برگردانده می‌شوند و هر پاسخ به یکی از درخواست‌ها همان ترتیب فهرست درخواست مربوطه را اشغال می‌کند. برخی از درخواست ها پاسخی ندارند و پاسخ در آن شاخص آرایه خالی است.
مثال
نمونه کد زیر استفاده از دسته‌بندی با Slides API را نشان می‌دهد.
این نمونه پاسخ دسته ای اطلاعاتی را در مورد نحوه اعمال هر درخواست فرعی در درخواست دسته ای نمایش می دهد. توجه داشته باشید که روش InsertTextRequest حاوی پاسخی نیست، بنابراین مقدار شاخص آرایه در [2] از پرانتزهای مجعد خالی تشکیل شده است. درخواست دسته ای خاصیت WriteControl را نشان می دهد که نحوه اجرای درخواست های نوشتن را نشان می دهد.
تاریخ آخرین به‌روزرسانی 2025-08-04 بهوقت ساعت هماهنگ جهانی.
[[["درک آسان","easyToUnderstand","thumb-up"],["مشکلم را برطرف کرد","solvedMyProblem","thumb-up"],["غیره","otherUp","thumb-up"]],[["اطلاعاتی که نیاز دارم وجود ندارد","missingTheInformationINeed","thumb-down"],["بیشازحد پیچیده/ مراحل بسیار زیاد","tooComplicatedTooManySteps","thumb-down"],["قدیمی","outOfDate","thumb-down"],["مشکل ترجمه","translationIssue","thumb-down"],["مشکل کد / نمونهها","samplesCodeIssue","thumb-down"],["غیره","otherDown","thumb-down"]],["تاریخ آخرین به‌روزرسانی 2025-08-04 بهوقت ساعت هماهنگ جهانی."],[],[],null,["# Batch requests\n\nThis document shows how to batch API calls together to reduce the number of\nconnections your client has to make. Batching can improve an application's\nefficiency by decreasing network round trips and increasing throughput.\n\nOverview\n--------\n\n\nEach connection your client makes results in a certain amount of overhead.\nThe Google Slides API supports batching to let your client place multiple\nrequest objects, each one specifying a single type of request to perform,\ninto a single batch request. A batch request can boost performance by\ncombining multiple subrequests into a single call to the server, retrieving\na single response back.\n\n\nWe encourage users to always batch multiple requests together. Here are some\nexamples of situations where you can use batching:\n\n- You've just started using the API and you have lots of data to upload.\n- You need to update metadata or properties, such as formatting, on multiple objects.\n- You need to delete many objects.\n\nLimits, authorization, \\& dependency considerations\n---------------------------------------------------\n\nHere's a list of other items to consider when employing batch updating:\n\n- Each batch request, including all subrequests, is counted as one API request toward your [usage limit](/workspace/slides/api/limits).\n- A batch request is authenticated once. This single authentication applies to all batch update objects in the request.\n- The server processes the subrequests in the same order they appear in the batch request. Latter subrequests can depend on actions taken during earlier subrequests. For example, in the same batch request, users can insert text into an existing document and then style it.\n\nBatch details\n-------------\n\n\nA batch request consists of one [batchUpdate](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate) method call\nwith multiple subrequests to, for example, add and then format a presentation.\n\n\nEach request is validated before being applied. All subrequests in the batch\nupdate are applied atomically. That is, if any request is not valid then the\nentire update is unsuccessful and none of the (potentially dependent)\nchanges are applied.\n\n\nSome requests provide responses with information about the applied requests.\nFor example, all batch update requests to add objects return responses so\nyou can access the metadata of the newly added object, such as the ID or\ntitle.\n\n\nWith this approach, you can build an entire Google document using one API\nbatch update request with multiple subrequests.\n\n### Format of a batch request\n\n\nA [request](/workspace/slides/api/reference/rest/v1/presentations/request) is a single JSON request containing multiple,\nnested subrequests with one required property: `requests`. The\nrequests are constructed in an array of individual requests. Each request uses\nJSON to represent the request object and to contain its properties.\n\n### Format of a batch response\n\n\nThe [response](/workspace/slides/api/reference/rest/v1/presentations/response) format for a batch request is similar to the\nrequest format. The server's response contains a complete reply of the single\nresponse object.\n\n\nThe main JSON object's property is named `replies`. The responses\nare returned in an array, with each response to one of the requests occupying\nthe same index order as the corresponding request. Some requests don't have\nresponses and the response at that array index is empty.\n\nExample\n-------\n\nThe following code sample shows the use of batching with the\nSlides API.\n\n### Request\n\nThis example batch request demonstrates how to:\n\n- Add a\n [`presentations.pages`](/workspace/slides/api/reference/rest/v1/presentations.pages)\n resource to an existing presentation, with an `insertionIndex` of `1`, using\n the\n [`CreateSlideRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createsliderequest)\n method.\n\n- Add a `shapeType` of type `TEXT_BOX` to the new slide using the\n [`CreateShapeRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#createshaperequest)\n method.\n\n- Insert \"Hello World\" text into the new field using the\n [`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\n method.\n\n```scdoc\n{\n \"requests\":[\n {\n \"createSlide\":{\n \"insertionIndex\":1,\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"elementProperties\":{\n \"pageObjectId\":\"newSlide\",\n \"size\":{\n \"height\":{\n \"magnitude\":50,\n \"unit\":\"PT\"\n },\n \"width\":{\n \"magnitude\":200,\n \"unit\":\"PT\"\n }\n }\n },\n \"shapeType\":\"TEXT_BOX\",\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \"insertText\":{\n \"objectId\":\"newTextBox\",\n \"text\":\"Hello World\"\n }\n }\n ]\n}\n```\n\n### Response\n\nThis example batch response displays information on how each subrequest within\nthe batch request was applied. Note the\n[`InsertTextRequest`](/workspace/slides/api/reference/rest/v1/presentations/request#inserttextrequest)\nmethod doesn't contain a response so the index value of the array at \\[2\\]\nconsists of empty curly braces. The batch request does display the\n[`WriteControl`](/workspace/slides/api/reference/rest/v1/presentations/batchUpdate#writecontrol)\nproperty, which shows how the write requests were executed. \n\n```scdoc\n{\n \"requiredRevisionId\": ID\n \"presentationId\": \"\",\n \"replies\":[\n {\n \"createSlide\":{\n \"objectId\":\"newSlide\"\n }\n },\n {\n \"createShape\":{\n \"objectId\":\"newTextBox\"\n }\n },\n {\n \n }\n ],\n \"writeControl\":{\n \"requiredRevisionId\": REVISION_ID\n }\n}\n```"]]
