Method: documents.batchUpdate

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

每個 request 必須先經過驗證才能套用。如果有任何要求無效，整個請求就會失敗，系統不會套用任何要求。

某些要求會透過 replies 提供一些資訊，讓您瞭解應如何套用。有些要求不需要傳回資訊，而每個要求都會傳回空白的回覆。回覆的順序會與要求相符。

舉例來說，假設您在呼叫 updateUpdate 時加上四則更新，只有第三次傳回資訊。回應包含兩份空白回覆、第三方要求的回覆，以及另一個空白的回覆。

由於其他使用者可能編輯了文件，因此文件可能不會反映您的變更內容，所以協作者的變更內容可能有所更動。如果沒有協作者，文件應該就會反映您的變更。無論如何，您要求的更新一律會以不可分割的形式套用。

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

詳情請參閱授權指南。

寫入控制項

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

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 可做為目標修訂版本，但對於經常編輯的文件而言，此視窗的 ID 可能較短。