批次處理要求

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

總覽

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

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

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

限制、授權和相依性考量

以下列出採用批次更新時應考量的其他事項：

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

批次詳細資料

批次要求包含一個 batchUpdate 方法呼叫，以及多個子要求，例如新增試算表並設定格式。

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

部分要求會在回應中提供已提出要求的相關資訊。舉例來說，所有新增物件的批次更新要求都會傳回回應，讓您存取新新增物件的中繼資料，例如 ID 或標題。

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

批次要求的格式

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

批次回應的格式

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

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

範例

以下範例說明如何使用 Sheets API 進行批次作業。

要求

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

在要求中加入工作表 ID 後，使用者就能在同一個 API 呼叫中，為其他子要求使用工作表 ID。這麼做可避免寫入-讀取-寫入循環，進而提升效能。

如需批次更新要求類型的清單 (分為不同類別)，請參閱「批次更新作業」下方的表格。

{
   "requests":[
      {
         "addSheet":{
            "properties":{
               "sheetId":123456
            }
         }
      },
      {
         "updateCells":{
            "start":{
               "sheetId":123456
            },
            "rows":[
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"hello"
                        }
                     }
                  ]
               },
               {
                  "values":[
                     {
                        "userEnteredValue":{
                           "stringValue":"world"
                        }
                     }
                  ]
               }
            ],
            "fields":"userEnteredValue"
         }
      },
      {
         "addNamedRange":{
            "namedRange":{
               "name":"newRange",
               "range":{
                  "sheetId":123456,
                  "endRowIndex":2
               }
            }
         }
      }
   ]
}

回應

這個批次回應範例會顯示批次要求中每個子要求的套用方式。請注意，UpdateCellsRequest 不含回應，因此 [1] 陣列的索引值由空白的尖括號組成。

"replies":[
   {
      "addSheet":{
         "properties":{
            "sheetId":123456,
            "title":"Sheet3",
            "index":2,
            "sheetType":"GRID",
            "gridProperties":{
               "rowCount":1000,
               "columnCount":26
            }
         }
      }
   },
   {
      
   },
   {
      "addNamedRange":{
         "namedRange":{
            "namedRangeId":"2104325079",
            "name":"newRange",
            "range":{
               "sheetId":123456,
               "startRowIndex":0,
               "endRowIndex":2,
               "startColumnIndex":0,
               "endColumnIndex":26
            }
         }
      }
   }
]