批次處理要求

本文說明如何批次處理 API 呼叫，以減少 用戶端連線批次處理可提高應用程式的 減少網路來回行程並提高處理量，提升效率。

總覽

用戶端每次建立連線都會帶來一定程度的負擔。 Google Docs API 支援批次作業，可讓您的用戶端一次找到多個 分別指定要執行的單一類型要求 並轉換為單一批次要求批次要求可提高效能 將多個子要求合併為對伺服器的單一呼叫， 使用者只會收到一項回應

我們建議使用者一律一次批次處理多個要求。以下是一些 以下舉例說明可使用批次處理的情況：

  • 您剛開始使用 API，有許多資料需要上傳。
  • 你需要更新多個項目的中繼資料或屬性，例如格式 如需儲存大量結構化物件 建議使用 Cloud Bigtable
  • 您需要刪除多個物件。

限制、授權與依附元件考量

以下列出使用批次更新時，需要考量的其他事項：

  • 每個批次要求 (包括所有子要求) 都會計為一個 API 要求改用用量限制。
  • 批次要求只會驗證一次。單一驗證 要求中的所有批次更新物件
  • 伺服器會按照子要求出現在子要求中的順序 批次要求。較晚的子要求取決於 先前的子要求舉例來說，在同一個批次要求中，使用者可以 將文字插入現有文件中，然後設定樣式。

批次詳細資料

批次要求包含一個 batchUpdate 方法呼叫 包含多個子要求，例如新增文件並設定格式

每個要求在套用前都會經過驗證。批次中的所有子要求 系統會以不可分割的形式套用更新也就是說，如果任何要求無效， 整個更新失敗，且不具備任何 (可能相依) 系統就會套用變更

部分要求會提供回應，內含已套用要求的相關資訊。 例如，所有新增物件的批次更新要求都會傳回回應， 可以存取新加入物件的中繼資料 (例如 ID 或 標題。

透過此做法，您可以使用單一 API 建立完整的 Google 文件 包含多個子要求的批次更新要求

批次要求的格式

要求是單一 JSON 要求，其中包含多個 含有一個必要屬性的巢狀子要求：requests。 會由個別要求陣列構成。每個要求都會使用 JSON 代表要求物件，並包含其屬性。

批次回應的格式

批次要求的回應格式與 要求格式。伺服器的回應會包含 回應物件。

主要 JSON 物件的屬性名為 replies。回應 會以陣列的形式傳回，並對取用 1 的其中一個要求 採用與對應要求相同的索引順序。部分要求 回應和該陣列索引的回應為空。

範例

下列程式碼範例顯示如何使用 Docs API 進行批次處理。

要求

這項批次要求範例會說明如何執行下列操作：

  • 插入「Hello World」這段文字轉換為現有文件的開頭 第 location 個索引 (共 1 個)，使用 InsertTextRequest。

  • 更新「Hello」字詞方法是使用 UpdateTextStyleRequest。 startIndex 和 endIndex 會定義特定格式文字的 range 區隔。

  • 使用 textStyle 將字型樣式設為粗體，顏色則設為藍色 「Hello」。

  • 使用 WriteControl 欄位，即可控制寫入要求的執行方式。詳情請參閱「使用 WriteControl 建立狀態一致性」。

{
   "requests":[
      {
         "insertText":{
            "location":{
               "index":1,
               "tabId":TAB_ID
            },
            "text":"Hello World"
         }
      },
      {
         "updateTextStyle":{
            "range":{
               "startIndex":1,
               "endIndex":6
            },
            "textStyle":{
               "bold":true,
               "foregroundColor":{
                  "color":{
                     "rgbColor":{
                        "blue":1
                     }
                  }
               }
            },
            "fields":"bold,foreground_color"
         }
      }
   ],
   "writeControl": {
      "requiredRevisionId": "REQUIRED_REVISION_ID"
  }
}

將 TAB_ID 和 REQUIRED_REVISION_ID 分別替換為要套用寫入要求的文件的分頁 ID 和修訂 ID。

回應

這個範例批次回應會顯示批次要求中每個子要求的套用方式。InsertTextRequest 和 UpdateTextStyleRequest 都沒有包含回應，因此 [0] 和 [1] 陣列的索引值包含空白大括號。批次要求會顯示 WriteControl 物件 顯示要求的執行方式

{
   "replies":[
      {},
      {}
   ],
   "writeControl":{
      "requiredRevisionId":`REQUIRED_REVISION_ID`
   },
   "documentId":`DOCUMENT_ID`
}