批次處理要求

本文說明如何批次處理 API 呼叫，以減少用戶端必須建立的連線數量。批次處理可減少網路往返次數並提高總處理量，進而提升應用程式效率。

總覽

用戶端建立的每個連線都會造成一定程度的負擔。 Google 文件 API 支援批次處理，可讓用戶端將多個要求物件放入單一批次要求，每個物件都指定要執行的單一要求類型。批次要求可將多個子要求合併為單一伺服器呼叫，並擷取單一回應，藉此提升效能。

建議使用者一律批次處理多個要求。以下列舉幾個可使用批次作業的狀況範例：

  • 您剛開始使用 API，且有大量資料要上傳。
  • 您需要更新多個物件的中繼資料或屬性，例如格式。
  • 您需要刪除大量物件。

限制、授權和依附關係考量

以下是採用批次更新時應考量的其他項目：

  • 每個批次要求 (包括所有子要求) 都會計為一次 API 要求，並計入用量限制。
  • 批次要求只需驗證一次。這項單一驗證會套用至要求中的所有批次更新物件。
  • 伺服器會按照子要求在批次要求中的順序處理這些要求。後續子要求可能會視先前子要求期間採取的動作而定。舉例來說，使用者可以在同一個批次要求中，將文字插入現有文件，然後設定樣式。

批次詳細資料

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

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

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

採用這種做法時，您可以使用一個 API 批次更新要求，搭配多個子要求，建構完整的 Google 文件。

批次要求的格式

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

批次回應的格式

批次要求的回應格式與要求格式類似。伺服器的回應包含單一回應物件的完整回覆。

主要 JSON 物件的屬性名為 replies。回應會以陣列形式傳回，每個要求的回應會佔用與對應要求相同的索引順序。部分要求沒有回應，且該陣列索引處的回應為空白。

範例

下列程式碼範例說明如何搭配使用批次處理與 Docs API。

要求

這個批次要求範例說明如何：

  • 使用 InsertTextRequest，將「Hello World」文字插入現有文件的開頭，索引 location 為 1。

  • 使用 UpdateTextStyleRequest 更新「Hello」一詞。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`
}