Method: documents.batchUpdate

ドキュメントに 1 つ以上の更新を適用します。

各 request は、適用される前に検証されます。リクエストが無効な場合、リクエスト全体が失敗し、何も適用されません。

一部のリクエストには、適用方法に関する情報を提供する replies があります。他のリクエストは情報を返す必要がなく、それぞれ空の返信を返します。返信の順序はリクエストの順序と一致します。

たとえば、4 つの更新で batchUpdate を呼び出し、3 つ目の更新のみが情報を返すとします。レスポンスには、空の返信 2 つ、3 つ目のリクエストへの返信、空の返信 1 つがこの順序で含まれます。

他のユーザーがドキュメントを編集している場合があるため、ドキュメントに反映される変更が、共同編集者の変更に応じて調整されることがあります。共同編集者がいない場合は、ドキュメントに自分の変更が反映されます。いずれにしても、リクエスト内の更新はアトミックにまとめて適用されることが保証されます。

HTTP リクエスト

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

この URL は gRPC Transcoding 構文を使用します。

パスパラメータ

パラメータ
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 Bad Request エラーが返されます。

レスポンスで必要なリビジョン ID が返された場合、それはリクエストが適用された後のドキュメントのリビジョン ID を示します。
targetRevisionId

string

書き込みリクエストが適用されるドキュメントのオプションのターゲット revision ID。

API を使用してドキュメントが読み取られた後に共同編集者の変更が行われた場合、この書き込みリクエストによって生成された変更は、共同編集者の変更に対して適用されます。これにより、共同編集者の変更とリクエストの変更の両方が組み込まれたドキュメントの新しいリビジョンが作成され、ドキュメント サーバーが競合する変更を解決します。ターゲット リビジョン ID を使用する場合、API クライアントはドキュメントの別の共同編集者と見なすことができます。

ターゲット リビジョン ID は、ドキュメントの最新バージョンへの書き込みにのみ使用できます。ターゲット リビジョンが最新リビジョンから大きく遅れている場合、リクエストは処理されず、400 Bad Request エラーが返されます。リクエストは、ドキュメントの最新バージョンを取得した後に再試行する必要があります。通常、リビジョン 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 リクエストされたコメントの更新がすべて失敗しました。