Method: documents.batchUpdate

為文件套用一或多項更新。

每個 request 都會先經過驗證，才能套用。如果任何要求無效，整個要求都會失敗，且不會套用任何內容。

部分要求會提供 replies，讓您瞭解這些要求的應用方式。其他要求則不需要傳回資訊。每則回應都會傳回空白回覆回覆的順序與要求的順序一致。

舉例來說，假設您使用 4 次更新來呼叫 batchUpdate，且只有第三個更新傳回資訊。回應包含兩個空白回覆、第三個要求回覆，以及另一個空白回覆。

由於其他使用者可能在編輯文件，因此文件內容可能不會確切反映您所做的變更：系統可能會根據協作者的變更來修改您所做的變更。如果沒有任何協作者，則文件會反映你所做的變更。無論如何，我們都保證會以不可分割的方式一併套用要求中的更新內容。

HTTP 要求

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

這個網址使用 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)
  }
}
欄位
documentId

string

已套用更新的文件 ID。
replies[]

object (Response)

更新的回覆。這會與更新項目一比一對應，但某些要求的回覆可能會為空白。
writeControl

object (WriteControl)

套用要求後更新的寫入控制項。

授權範圍

需要下列其中一種 OAuth 範圍：

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

詳情請參閱授權指南。

WriteControl

提供寫入要求的執行方式控制項。

JSON 表示法 
{

  // Union field control can be only one of the following:
  "requiredRevisionId": string,
  "targetRevisionId": string
  // End of list of possible types for union field control.
}
欄位
聯集欄位 control。決定要寫入的文件修訂版本，以及如果該修訂版本並非文件的目前修訂版本時應如何處置。如果未指定任何欄位，系統會將更新套用至最新的修訂版本。control 只能是下列其中一項：
requiredRevisionId

string

可套用寫入要求的文件 (選用) revision ID。如果這不是文件的最新修訂版本，系統就不會處理要求，並傳回 400 錯誤要求錯誤。

回應中傳回的必要修訂版本 ID 會指出要求套用後的文件修訂版本 ID。
targetRevisionId

string

寫入要求所套用的文件選用目標 revision ID。

在使用 API 讀取文件後，如果協作者發生了變更，這項寫入要求產生的變更就會套用至協作者的變更。這會產生新的文件修訂版本，同時納入協作者變更與要求變更，同時解決文件伺服器不一致的變更。使用目標修訂版本 ID 時，API 用戶端可視為文件的其他協作者。

目標修訂版本 ID 只能用於寫入文件的最新版本。如果目標修訂版本與最新修訂版本相差太多，系統就不會處理要求，並傳回 400 錯誤要求錯誤。擷取最新版本的文件後，應再次嘗試要求。通常修訂 ID 在讀取後會維持有效狀態，可用於做為目標修訂版本，但經常編輯的文件可能會縮短這個時間。