本文說明如何批次處理 API 呼叫,以減少用戶端必須建立的連線數量。批次處理能夠減少網路來回行程次數並提高處理量,進而提升應用程式效率。
總覽
用戶端每次建立連線都會產生一定程度的負擔。Google Docs API 支援批次處理功能,可讓用戶端在單一批次要求中放置多個要求物件,每個物件分別指定要執行的單一類型要求。批次要求可將多個子要求合併為對伺服器的單一呼叫,從而擷取單一回應,藉此提升效能。
我們建議使用者一律一次批次處理多個要求。以下列舉幾個可以使用批次處理的情況:
- 您剛開始使用 API,有許多資料需要上傳。
- 您必須更新多個物件的中繼資料或屬性,例如格式。
- 您需要刪除多個物件。
限制、授權和依附元件考量
以下列出使用批次更新時,需要考量的其他事項:
- 每個批次要求 (包括所有子要求) 都會計為一項 API 要求,計入用量限制。
- 批次要求會經過驗證一次。這項單一驗證會套用至要求中的所有批次更新物件。
- 伺服器會按照子要求在批次要求中的顯示順序處理。較晚的子要求則取決於先前子要求期間採取的動作。舉例來說,在相同的批次要求中,使用者可以將文字插入現有的文件中,然後設定樣式。
批次詳細資料
批次要求包含一個 batchUpdate
方法呼叫,其中包含多項子要求,例如新增文件並設定格式。
每個要求在套用前都會經過驗證。批次更新中的所有子要求都會自動套用。也就是說,如果任何要求無效,整個更新就會失敗,且不會套用任何 (可能相依) 的變更。
有些要求會提供回應,內含已套用要求的相關資訊。 舉例來說,所有新增物件的批次更新要求都會傳回回應,方便您存取新新增物件的中繼資料,例如 ID 或標題。
透過這種做法,您可以使用含有多個子要求的單一 API 批次更新要求,建構整份 Google 文件。
批次要求的格式
要求是單一 JSON 要求,內含多個巢狀子要求,其中包含一個必要屬性:requests
。這些要求會用個別要求的陣列建立。每項要求都會使用 JSON 來代表要求物件,並包含其屬性。
批次回應的格式
批次要求的 response 格式與要求格式類似。伺服器的回應包含單一回應物件的完整回覆。
主要 JSON 物件的屬性名為 replies
。回應會以陣列傳回,且對於其中一個要求的回應都會採用與對應要求相同的索引順序。部分要求沒有回應,且該陣列索引的回應為空白。
範例
下列程式碼範例顯示如何使用 Docs API 進行批次處理。
要求
這項批次要求範例會說明如何執行下列操作:
使用
InsertTextRequest
,將「Hello World」文字插入現有文件的開頭,索引location
為1
。使用
UpdateTextStyleRequest
更新「Hello」字詞。startIndex
和endIndex
會定義片段中格式化文字的range
。使用
textStyle
將字型樣式設為粗體,並將「Hello」文字的顏色設為藍色。您可以使用
WriteControl
欄位控管寫入要求的執行方式。詳情請參閱「使用 WriteControl 建立狀態一致性」。
{ "requests":[ { "insertText":{ "location":{ "index":1 }, "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" } }
將 REQUIRED_REVISION_ID 替換為要套用寫入要求的文件修訂版本 ID。
回覆
這個批次回應範例會顯示批次要求中各項子要求的套用方式資訊。InsertTextRequest
或 UpdateTextStyleRequest
都未包含回應,因此 [0] 和 [1] 的陣列索引值均由空白大括號組成。批次要求會顯示 WriteControl
物件,說明要求的執行方式。
{ "replies":[ {}, {} ], "writeControl":{ "requiredRevisionId":`REQUIRED_REVISION_ID` }, "documentId":`DOCUMENT_ID` }