일괄 요청
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
이 문서에서는 API 호출을 일괄 처리하여 클라이언트가 수행해야 하는 연결 수를 줄이는 방법을 보여줍니다. 일괄 처리는 네트워크 왕복을 줄이고 처리량을 늘려 애플리케이션의 효율성을 개선할 수 있습니다.
개요
클라이언트가 수행하는 각 연결에는 어느 정도의 오버헤드가 수반됩니다.
Google Slides API는 클라이언트가 실행할 단일 요청 유형을 각각 지정하는 여러 요청 객체를 단일 일괄 요청에 배치할 수 있도록 일괄 처리를 지원합니다. 일괄 요청은 여러 하위 요청을 서버에 대한 단일 호출로 결합하여 성능을 향상하고 단일 응답을 다시 가져올 수 있습니다.
사용자는 항상 여러 요청을 함께 일괄 처리하는 것이 좋습니다. 다음은 일괄 처리를 사용할 수 있는 상황의 몇 가지 예입니다.
-
API를 이제 막 사용하기 시작했고 업로드할 데이터가 많습니다.
-
여러 객체의 서식과 같은 메타데이터 또는 속성을 업데이트해야 합니다.
- 많은 객체를 삭제해야 합니다.
한도, 승인, 종속 항목 고려사항
일괄 업데이트를 사용할 때 고려해야 할 기타 항목 목록은 다음과 같습니다.
-
모든 하위 요청을 포함한 각 일괄 요청은 사용량 한도에 대해 하나의 API 요청으로 계산됩니다.
-
일괄 요청은 한 번 인증됩니다. 이 단일 인증은 요청의 모든 일괄 업데이트 객체에 적용됩니다.
-
서버는 일괄 요청에 표시된 순서와 동일한 순서로 하위 요청을 처리합니다. 후반 하위 요청은 이전 하위 요청 중에 취해진 작업에 따라 달라질 수 있습니다. 예를 들어 동일한 일괄 요청에서 사용자는 기존 문서에 텍스트를 삽입한 다음 스타일을 지정할 수 있습니다.
일괄 처리 세부정보
일괄 요청은 프레젠테이션을 추가한 후 서식을 지정하는 등 여러 하위 요청이 있는 batchUpdate 메서드 호출 하나로 구성됩니다.
각 요청은 적용되기 전에 검증됩니다. 일괄 업데이트의 모든 하위 요청은 원자적으로 적용됩니다. 즉, 요청이 유효하지 않으면 전체 업데이트가 실패하고 종속될 수 있는 변경사항이 적용되지 않습니다.
일부 요청은 적용된 요청에 관한 정보가 포함된 응답을 제공합니다.
예를 들어 객체를 추가하는 모든 일괄 업데이트 요청은 새로 추가된 객체의 메타데이터(예: ID 또는 제목)에 액세스할 수 있도록 응답을 반환합니다.
이 방법을 사용하면 여러 하위 요청이 포함된 하나의 API 일괄 업데이트 요청을 사용하여 전체 Google 문서를 빌드할 수 있습니다.
요청은 requests이라는 필수 속성이 있는 여러 개의 중첩된 하위 요청이 포함된 단일 JSON 요청입니다. 요청은 개별 요청의 배열로 구성됩니다. 각 요청은 JSON을 사용하여 요청 객체를 나타내고 속성을 포함합니다.
일괄 요청의 응답 형식은 요청 형식과 유사합니다. 서버의 응답에는 단일 응답 객체의 전체 대답이 포함됩니다.
기본 JSON 객체의 속성 이름은 replies입니다. 대답은 배열로 반환되며, 요청에 대한 각 대답은 해당 요청과 동일한 색인 순서를 차지합니다. 일부 요청에는 응답이 없으며 해당 배열 색인의 응답이 비어 있습니다.
예
다음 코드 샘플은 Slides API에서 일괄 처리를 사용하는 방법을 보여줍니다.
요청
이 예시 일괄 요청은 다음 작업을 수행하는 방법을 보여줍니다.
{
"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
}
}
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-08-29(UTC)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[],[],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```"]]
