Method: documents.batchUpdate

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

每個 request 都會經過驗證,然後才會套用。如有任何要求無效,整個要求就會失敗,且不會套用任何內容。

部分要求會顯示 replies,提供套用方式的相關資訊。其他要求則不需要傳回資訊,這些要求都會傳回空白回覆。回覆順序與要求順序一致。

舉例來說,假設您使用四項更新呼叫 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)

更新的回覆。這會與更新內容 1:1 對應,但部分要求的回覆內容可能為空白。

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 讀取文件後,協作者進行了變更,系統會根據協作者的變更套用這項寫入要求產生的變更。這會產生文件的新修訂版本,其中包含協作者的變更和要求中的變更,Google 文件伺服器會解決衝突的變更。使用目標修訂版本 ID 時,API 用戶端可視為文件的另一位協作者。

目標修訂版本 ID 只能用於寫入文件的近期版本。如果目標修訂版本與最新版本相差太遠,系統就不會處理要求,並傳回 400 錯誤要求錯誤。請先擷取文件的最新版本,然後再重試要求。通常在讀取修訂版本 ID 後,該 ID 仍可在幾分鐘內做為目標修訂版本使用,但如果是經常編輯的文件,這個時間可能會較短。