本文說明如何批次處理 API 呼叫,以減少 用戶端連線批次處理可提高應用程式的 減少網路來回行程並提高處理量,提升效率。
總覽
用戶端每次建立連線都會帶來一定程度的負擔。 Google Slides API 支援批次作業,可讓您的用戶端一次放置多個 分別指定要執行的單一類型要求 並轉換為單一批次要求批次要求可提高效能 將多個子要求合併為對伺服器的單一呼叫, 使用者只會收到一項回應
我們建議使用者一律一次批次處理多個要求。以下是一些 以下舉例說明可使用批次處理的情況:
- 您剛開始使用 API,有許多資料需要上傳。
- 你需要更新多個項目的中繼資料或屬性,例如格式 如需儲存大量結構化物件 建議使用 Cloud Bigtable
- 您需要刪除多個物件。
限制、授權與依附元件考量
以下列出使用批次更新時,需要考量的其他事項:
- 每個批次要求 (包括所有子要求) 都會計為一個 API 要求改用用量限制。
- 批次要求會經過驗證一次。單一驗證 要求中的所有批次更新物件
- 伺服器會按照子要求出現在子要求中的順序 批次要求。較晚的子要求取決於 先前的子要求舉例來說,在同一個批次要求中,使用者可以 將文字插入現有文件中,然後設定樣式。
批次詳細資料
批次要求包含一個 batchUpdate
方法呼叫
包含多個子要求,例如新增簡報並設定格式。
每個要求在套用前都會經過驗證。批次中的所有子要求 系統會以不可分割的形式套用更新也就是說,如果任何要求無效, 整個更新失敗,且不具備任何 (可能相依) 系統就會套用變更
部分要求會提供回應,內含已套用要求的相關資訊。 例如,所有新增物件的批次更新要求都會傳回回應, 可以存取新加入物件的中繼資料 (例如 ID 或 標題。
透過此做法,您可以使用單一 API 建立完整的 Google 文件 包含多個子要求的批次更新要求
批次要求的格式
要求是單一 JSON 要求,其中包含多個
含有一個必要屬性的巢狀子要求:requests
。
會由個別要求陣列構成。每個要求都使用
代表要求物件並包含其屬性的 JSON。
批次回應的格式
批次要求的回應格式與 要求格式。伺服器的回應會包含 回應物件。
主要 JSON 物件的屬性名為 replies
。回應
會以陣列的形式傳回,並對取用 1 的其中一個要求
採用與對應要求相同的索引順序。部分要求
回應和該陣列索引的回應為空。
範例
下列程式碼範例顯示了 Slides API:
要求
這項批次要求範例會說明如何執行下列操作:
新增
presentations.pages
敬上 將資源新增至現有簡報 (insertionIndex
為1
),並使用 這個CreateSlideRequest
方法。使用下列指令,將
TEXT_BOX
類型的shapeType
新增至新投影片CreateShapeRequest
敬上 方法。插入「Hello World」輸入文字並貼到新欄位中
InsertTextRequest
敬上 方法。
{ "requests":[ { "createSlide":{ "insertionIndex":1, "objectId":"newSlide" } }, { "createShape":{ "elementProperties":{ "pageObjectId":"newSlide", "size":{ "height":{ "magnitude":50, "unit":"PT" }, "width":{ "magnitude":200, "unit":"PT" } } }, "shapeType":"TEXT_BOX", "objectId":"newTextBox" } }, { "insertText":{ "objectId":"newTextBox", "text":"Hello World" } } ] }
回應
這個批次回應範例會顯示當中各項子要求的相關資訊
套用批次要求請注意,
InsertTextRequest
敬上
方法未包含回應,因此位於 [2] 的陣列索引值
由空大括號組成。批次要求會顯示
WriteControl
敬上
屬性來顯示寫入要求的方式。
{ "requiredRevisionId": ID "presentationId": "", "replies":[ { "createSlide":{ "objectId":"newSlide" } }, { "createShape":{ "objectId":"newTextBox" } }, { } ], "writeControl":{ "requiredRevisionId": REVISION_ID } }