일괄 요청

이 문서에서는 API 호출을 일괄 처리하여 몇 가지 구성 요소를 정의합니다 일괄 처리를 통해 애플리케이션의 네트워크 왕복을 줄이고 처리량을 늘려 효율성을 높일 수 있습니다.

개요

클라이언트가 만드는 각 연결에 일정량의 오버헤드가 발생합니다. Google Docs API는 일괄 처리를 지원하므로 클라이언트가 각각 수행할 단일 유형의 요청을 지정하는 여러 요청 객체를 단일 일괄 요청에 배치할 수 있습니다. 일괄 요청은 다음과 같은 방법으로 성능을 향상할 수 있습니다. 여러 하위 요청을 서버에 대한 단일 호출로 결합하여 단일 응답을 반환합니다.

항상 여러 요청을 한 번에 일괄 처리하는 것이 좋습니다. 다음은 몇 가지 다음은 일괄 처리를 사용할 수 있는 상황의 예입니다.

  • 이제 막 API를 사용하기 시작했고 업로드할 데이터가 많습니다.
  • 여러 기기에서 메타데이터나 서식과 같은 속성을 객체입니다.
  • 여러 객체를 삭제해야 합니다.

한도, 승인, 종속 항목 고려사항

다음은 일괄 업데이트를 사용할 때 고려해야 할 기타 항목의 목록입니다.

  • 모든 하위 요청을 포함하여 각 일괄 요청은 하나의 API로 계산됩니다. 요청을 사용량 한도에 반영할 수도 있습니다.
  • 일괄 요청은 한 번 인증됩니다. 이 단일 인증은 요청의 모든 일괄 업데이트 객체에 적용됩니다.
  • 서버는 일괄 요청입니다 이후의 하위 요청은 이전 하위 요청을 처리할 수 있습니다. 예를 들어 동일한 일괄 요청에서 사용자는 기존 문서에 텍스트를 삽입한 다음 스타일을 지정할 수 있습니다.

일괄 처리 세부정보

일괄 요청은 하나의 batchUpdate 메서드 호출로 구성됩니다. 여러 개의 하위 요청이 있는 경우)에는 문서 추가, 서식 지정 등이 포함됩니다.

각 요청은 적용되기 전에 검증됩니다. 일괄 처리의 모든 하위 요청 원자적으로 적용됩니다 즉, 유효하지 않은 요청이 있는 경우 전체 업데이트에 실패했으며 (종속될 수 있음) 변경사항이 적용됩니다.

일부 요청은 적용된 요청에 대한 정보를 응답과 함께 제공합니다. 예를 들어 객체 추가에 대한 모든 일괄 업데이트 요청은 응답을 반환하므로 새로 추가된 객체의 메타데이터(예: ID, 있습니다.

이 방법을 사용하면 하나의 API를 사용하여 전체 Google 문서를 작성할 수 있습니다. 여러 하위 요청이 있는 일괄 업데이트 요청입니다.

일괄 요청의 형식

요청은 여러 개의 필수 속성 1개(requests)가 포함된 중첩된 하위 요청 이 요청은 개별 요청의 배열로 구성됩니다. 각 요청은 요청 객체를 나타내고 해당 속성을 포함하는 JSON입니다.

일괄 응답의 형식

일괄 요청의 응답 형식은 다음과 유사합니다. 요청 형식을 지원합니다. 서버의 응답에는 단일 응답 객체가 됩니다.

기본 JSON 객체의 속성 이름은 replies입니다. 응답 는 배열로 반환되며, 요청 중 하나에 대한 각 응답은 색인 순서를 지정해야 합니다. 일부 요청에는 해당 배열 색인의 응답이 비어 있습니다.

예

다음 코드 샘플은 Docs API에서 일괄 처리를 사용하는 방법을 보여줍니다.

요청

이 일괄 요청 예시는 다음 작업을 수행하는 방법을 보여줍니다.

  • 'Hello World' 삽입 기존 문서의 시작 부분에 색인 1의 location를 사용하며, InsertTextRequest

  • UpdateTextStyleRequest를 사용하여 'Hello'라는 단어를 업데이트합니다. 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을(를) 다음으로 바꾸기 쓰기 요청이 있는 문서의 탭 ID와 버전 ID 적용됩니다.

응답

이 일괄 응답 예는 내의 각 하위 요청이 일괄 요청이 적용된 경우를 확인할 수 있습니다 물론 InsertTextRequest 드림 또는 UpdateTextStyleRequest 응답을 포함하므로 [0] 및 [1] 에 있는 배열의 색인 값은 합니다. 일괄 요청은 WriteControl 객체를 표시합니다. 요청이 실행된 방식을 보여줍니다

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