批次處理要求

本文說明如何批次處理 API 呼叫，以減少用戶端必須建立的連線數量。批次處理可以減少網路來回行程、增加處理量，進而提升應用程式效率。

總覽

用戶端的每個連線都會造成一定程度的負擔。Google 簡報 API 支援批次處理功能，可讓您的用戶端放置多個要求物件，每個物件會指定執行單一類型的要求。批次要求可將多個子要求合併成對伺服器發出的單一呼叫，然後擷取單一回應，藉此提升效能。

我們建議使用者一律批次處理多個要求。以下列舉幾個您可使用批次處理的情況：

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

限制、授權和依附元件注意事項

採用批次更新時，建議參考的項目如下：

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

批次詳細資料

批次要求包含一個 batchUpdate 方法呼叫，以用於多項子要求，例如新增簡報並設定格式。

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

某些要求會在回應中提供有關已套用要求的資訊。舉例來說，所有批次更新要求新增物件都會傳回回應，方便您存取新新增物件的中繼資料 (例如 ID 或標題)。

透過這個方法，您可以使用含有多個子要求的單一 API 批次更新要求，建構整份 Google 文件。

批次要求的格式

「要求」是單一 JSON 要求，內含多個巢狀子要求，其中包含一個必要屬性：requests。這些要求會以個別要求的陣列建構而成。每個要求都會使用 JSON 來代表要求物件，並包含其屬性。

批次回應格式

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

主要 JSON 物件的屬性命名為 replies。系統會以陣列形式傳回回應，其中任一要求的回應都會佔用與對應要求相同的索引順序。某些要求沒有回應，且該陣列索引的回應沒有任何內容。

範例

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

要求

這個範例批次要求示範如何：

{
   "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
   }
}