Method: documents.batchUpdate

문서에 하나 이상의 업데이트를 적용합니다.

각 request는 적용되기 전에 검증됩니다. 유효하지 않은 요청이 있으면 전체 요청이 실패하고 아무것도 적용되지 않습니다.

일부 요청에는 적용 방법에 관한 정보를 제공하는 replies가 있습니다. 다른 요청은 정보를 반환할 필요가 없으며 각각 빈 대답을 반환합니다. 대답 순서는 요청 순서와 일치합니다.

예를 들어 업데이트 4개로 batchUpdate를 호출하고 세 번째 업데이트만 정보를 반환한다고 가정해 보겠습니다. 이 경우 대답에는 빈 답글 2개, 세 번째 요청에 대한 답글, 또 다른 빈 답글이 순서대로 포함됩니다.

다른 사용자가 문서를 수정하고 있을 수 있으므로 문서에 변경사항이 정확하게 반영되지 않을 수 있습니다. 공동작업자의 변경사항에 따라 변경사항이 수정될 수 있습니다. 공동작업자가 없는 경우 문서에 변경사항이 반영됩니다. 어떤 경우든 요청의 업데이트는 원자적으로 함께 적용됩니다.

HTTP 요청

POST https://docs.googleapis.com/v1/documents/{documentId}:batchUpdate

URL은 gRPC 트랜스코딩 구문을 사용합니다.

경로 매개변수

매개변수
documentId

string

업데이트할 문서의 ID입니다.

요청 본문

요청 본문에는 다음과 같은 구조의 데이터가 포함됩니다.

JSON 표현 
{
  "requests": [
    {
      object (Request)
    }
  ],
  "writeControl": {
    object (WriteControl)
  }
}
필드
requests[]

object (Request)

문서에 적용할 업데이트 목록입니다.
writeControl

object (WriteControl)

쓰기 요청이 실행되는 방식을 제어합니다.

응답 본문

documents.batchUpdate 요청의 응답 메시지

성공한 경우 응답 본문은 다음과 같은 구조의 데이터를 포함합니다.

JSON 표현 
{
  "documentId": string,
  "replies": [
    {
      object (Response)
    }
  ],
  "writeControl": {
    object (WriteControl)
  },
  "suggestionResponses": [
    {
      object (SuggestionResponse)
    }
  ],
  "commentUpdateState": enum (CommentUpdateState)
}
필드
documentId

string

업데이트가 적용된 문서의 ID입니다.
replies[]

object (Response)

업데이트의 답장입니다. 이는 업데이트와 1:1로 매핑되지만 일부 요청에 대한 대답은 비어 있을 수 있습니다.
writeControl

object (WriteControl)

요청을 적용한 후 업데이트된 쓰기 제어입니다.
suggestionResponses[]

object (SuggestionResponse)

각 업데이트의 영향을 받은 제안입니다. 이는 업데이트와 1:1로 매핑됩니다.

commentUpdateState

enum (CommentUpdateState)

댓글 업데이트가 일괄 요청에 적용되었는지 여부입니다.

승인 범위

다음 OAuth 범위 중 하나가 필요합니다.

  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file

자세한 내용은 승인 가이드를 참고하세요.

WriteControl

쓰기 요청이 실행되는 방식을 제어합니다.

JSON 표현 
{
  "writeMode": enum (WriteMode),

  "requiredRevisionId": string,
  "targetRevisionId": string
}
필드
writeMode

enum (WriteMode)

요청 업데이트가 문서에 적용되는 방식입니다.

지정하지 않으면 요청 업데이트가 일반 수정사항으로 적용됩니다.

통합 필드 control. 문서를 쓸 버전을 결정하고 해당 버전이 문서의 현재 버전이 아닌 경우 요청이 어떻게 작동해야 하는지 결정합니다. 두 필드가 모두 지정되지 않은 경우 업데이트가 최신 버전에 적용됩니다. control은 다음 중 하나여야 합니다.
requiredRevisionId

string

쓰기 요청이 적용되는 문서의 선택적 revision ID입니다. 문서의 최신 버전이 아닌 경우 요청이 처리되지 않고 400 잘못된 요청 오류가 반환됩니다.

필수 수정 버전 ID가 응답에 반환되면 요청이 적용된 후의 문서 수정 버전 ID를 나타냅니다.
targetRevisionId

string

쓰기 요청이 적용되는 문서의 선택적 타겟 revision ID입니다.

API를 사용하여 문서를 읽은 후 공동작업자 변경사항이 발생한 경우 이 쓰기 요청으로 생성된 변경사항이 공동작업자 변경사항에 적용됩니다. 이렇게 하면 공동작업자의 변경사항과 요청의 변경사항이 모두 포함된 문서의 새 버전이 생성되며, Docs 서버에서 충돌하는 변경사항을 해결합니다. 타겟 버전 ID를 사용하는 경우 API 클라이언트를 문서의 또 다른 공동작업자로 생각할 수 있습니다.

타겟 버전 ID는 문서의 최신 버전에 쓰기 전용으로 사용할 수 있습니다. 타겟 버전이 최신 버전보다 너무 오래된 경우 요청이 처리되지 않고 400 잘못된 요청 오류가 반환됩니다. 문서의 최신 버전을 가져온 후 요청을 다시 시도해야 합니다. 일반적으로 수정 버전 ID는 읽은 후 몇 분 동안 타겟 수정 버전으로 사용할 수 있지만 자주 수정되는 문서의 경우 이 기간이 더 짧을 수 있습니다.

WriteMode

요청 업데이트가 문서에 적용되는 방식을 결정합니다.

열거형
WRITE_MODE_UNSPECIFIED 쓰기 모드가 지정되지 않았습니다. 기본값은 EDIT 동작입니다.
EDIT 모든 업데이트를 일반 수정사항으로 적용합니다.
SUGGEST 모든 업데이트를 추천으로 적용합니다.

SuggestionResponse

특정 업데이트의 영향을 받은 추천입니다.

JSON 표현 
{
  "createdSuggestionIds": [
    string
  ],
  "updatedSummarySuggestionIds": [
    string
  ],
  "deletedSuggestionIds": [
    string
  ],
  "acceptedSuggestionIds": [
    string
  ],
  "rejectedSuggestionIds": [
    string
  ]
}
필드
createdSuggestionIds[]

string

업데이트 중에 생성된 추천의 ID입니다.
updatedSummarySuggestionIds[]

string

업데이트 중에 요약이 업데이트된 추천의 ID입니다.
deletedSuggestionIds[]

string

업데이트 중에 삭제된 추천의 ID입니다.
acceptedSuggestionIds[]

string

업데이트 중에 수락된 추천의 ID입니다.
rejectedSuggestionIds[]

string

업데이트 중에 거부된 추천의 ID입니다.

CommentUpdateState

일괄 요청의 댓글 업데이트 상태입니다.

열거형
COMMENT_UPDATE_STATE_UNSPECIFIED 댓글 업데이트 상태가 지정되지 않았습니다.
NO_UPDATES_REQUESTED 일괄 요청에서 댓글 업데이트가 요청되지 않았습니다.
ALL_SAVED 요청된 모든 댓글 업데이트가 일괄 요청에 적용되었습니다.
ALL_FAILED_UNKNOWN_REASON 요청된 모든 댓글 업데이트가 실패했습니다.