排解 BigQuery Storage API 錯誤

本文說明如何排解使用 BigQuery Storage Read API、BigQuery Storage Write API (gRPC)，或使用 BigQuery Storage Write API (REST) 進行串流插入 (tabledata.insertAll 方法) 時，在 BigQuery 中讀取或串流資料時發生的問題。

使用 INFORMATION_SCHEMA 檢視表分析串流遙測資料

您可以查詢 INFORMATION_SCHEMA 檢視畫面，監控串流擷取狀況、找出處理量瓶頸，以及檢查一分鐘間隔內的錯誤代碼：

下列範例查詢會擷取過去 24 小時內，Storage Write API (gRPC) 的錯誤計數和擷取的位元組：INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT 

SELECT
  start_timestamp,
  error_code,
  SUM(total_requests) AS request_count,
  SUM(total_input_bytes) AS input_bytes
FROM
  `region-REGION`.INFORMATION_SCHEMA.WRITE_API_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 DAY)
  AND error_code IS NOT NULL
GROUP BY
  start_timestamp,
  error_code
ORDER BY
  start_timestamp DESC;

將 REGION 替換為資料集區域名稱，例如 us 或 europe-west1。

排解 Storage Read API 錯誤

以下是使用 Storage Read API 時常見的錯誤：

發生錯誤：Stream removed
解決方法：重新嘗試 Storage Read API 要求。這可能是暫時性錯誤，重試要求即可解決。如果問題持續發生，請與 Cloud Customer Care 團隊聯絡。
發生錯誤：Stream expired

原因：Storage Read API 工作階段達到 6 小時的逾時時間時，就會發生這個錯誤。

解決方法：

  1. 提高工作的平行處理數量。
  2. 如果工作站節點的 CPU 使用率相對穩定，且未超過 85%，請考慮在較大的機型上執行作業。
  3. 將工作拆分為多個工作或較小的查詢。

如要進一步瞭解工作階段管理和讀取資料，請參閱「Storage Read API 總覽」。

排解串流插入問題

以下各節將說明如何排解使用 Storage Write API (REST) 將資料串流至 BigQuery 時發生的錯誤。如要進一步瞭解如何解決串流資料即時插入的配額錯誤，請參閱「串流資料即時插入配額錯誤」。

失敗的 HTTP 回應代碼

如果收到失敗的 HTTP 回應代碼 (例如網路錯誤)，就無法判斷串流資料即時插入作業是否成功。如果嘗試重新傳送要求，資料表中可能會出現重複的資料列。為避免表格重複，請在傳送要求時設定 insertId 屬性。BigQuery 會使用 insertId 屬性進行重複資料刪除作業。

如果收到權限錯誤、無效的表格名稱錯誤或超出配額錯誤，系統就不會插入任何資料列，且整個要求都會失敗。

成功的 HTTP 回應代碼

即使收到成功 HTTP 回應代碼，您仍須檢查回應的 insertErrors 屬性，判斷資料列插入作業是否成功，因為 BigQuery 可能只會部分成功插入資料列。您可能會遇到下列其中一種情況：

  • 所有資料列都已成功插入：如果 insertErrors 屬性是空白清單，表示所有資料列都已成功插入。
  • 部分資料列插入成功：除非任何資料列發生結構定義不符的情況，否則系統不會插入 insertErrors 屬性中指出的資料列，但會成功插入所有其他資料列。errors 屬性包含每個失敗資料列的詳細資訊。index 屬性會針對發生該錯誤的要求，提供從 0 開始的資料列索引。
  • 未成功插入任何資料列：如果 BigQuery 在要求中發現個別資料列的結構定義不符，系統不會插入任何資料列，且每個資料列都會傳回 insertErrors 項目，即使資料列的結構定義相符也一樣。如果資料列沒有結構定義不符的問題，reason 屬性會設為 stopped，您可以直接重新傳送這些資料列。如果資料列失敗，則會包含結構定義不符的詳細資訊。如要瞭解各 BigQuery 資料類型支援的通訊協定緩衝區類型，請參閱「支援的通訊協定緩衝區和 Arrow 資料類型」。

串流資料插入的中繼資料錯誤

由於 BigQuery 串流 API 的設計目的是為了提高插入率，因此與串流系統互動時，基礎資料表的中繼資料修改作業最終會保持一致。通常中繼資料變更會在幾分鐘內傳播，但在此期間，API 回應可能會反映資料表的不一致狀態。

這類情況包括：

  • 結構定義變更：如果資料表最近收到串流插入內容，修改該資料表的結構定義可能會導致回應出現結構定義不符錯誤，因為串流系統可能不會立即偵測到結構定義變更。
  • 建立或刪除資料表：串流至不存在的資料表會傳回 notFound 回應的變體。後續串流插入內容可能無法立即辨識回覆中建立的表格。同樣地，刪除或重新建立資料表可能會導致串流插入作業在一段時間內傳送至舊資料表。新表格中可能不會顯示串流插入內容。
  • 資料表截斷：截斷資料表資料 (使用 writeDisposition 值為 WRITE_TRUNCATE 的查詢工作) 也可能導致在一致性期間內插入的後續資料遭到捨棄。

資料遺失或無法使用

串流插入作業會暫時存放在寫入最佳化儲存空間中，這類儲存空間的可用性特徵與代管儲存空間不同。BigQuery 中的某些作業不會與寫入最佳化儲存空間互動，例如表格複製作業和 tabledata.list 等 API 方法。目的地資料表或輸出內容中沒有最近的串流資料。

串流資料即時插入配額錯誤

本節提供相關提示，協助排解將資料串流至 BigQuery 時發生的配額錯誤。

在特定區域中，如果您並未在每個資料列的 insertId 欄位中填入資料，則串流資料插入會含有較高的配額。如要進一步瞭解串流資料插入的配額，請參閱串流資料插入。BigQuery 串流的配額相關錯誤取決於 insertId 是否存在。

錯誤訊息

如果 insertId 欄位為空白，則可能會發生下列配額錯誤：

配額限制 錯誤訊息
每項專案每秒位元組數 在區域 REGION 中專案 PROJECT_ID gaia_id 為 GAIA_ID 的實體超過每秒插入位元組數的配額。

如果在 insertId 欄位填入資料，則可能會發生下列配額錯誤：

配額限制 錯誤訊息
每項專案每秒資料列數量 您在 REGION 的專案 PROJECT_ID 超過每秒串流資料插入資料列的配額。
每個資料表每秒資料列數量 您的資料表：TABLE_ID超出每秒串流資料即時插入列的配額。
每個資料表每秒位元組數 您的資料表：TABLE_ID 超出每秒串流資料即時插入位元組的配額。

insertId 欄位的用途是簡化插入的資料列。如果同一個 insertId 的多個插入項目均於幾分鐘之內抵達，則 BigQuery 會寫入單一版本的記錄。但是，我們無法保證系統會自動刪除重複的內容。為了達到最大的串流總處理量，建議您不要加入 insertId，改成手動刪除重複內容。詳情請參閱確保資料一致性一文。

如果遇到這個錯誤，請診斷問題，然後按照建議步驟解決問題。

診斷

使用 STREAMING_TIMELINE_BY_* 檢視表來分析串流流量。這些檢視畫面會彙整以一分鐘為間隔的串流統計資料，並依error_code分組。配額錯誤會顯示在 error_code 等於 RATE_LIMIT_EXCEEDED 或 QUOTA_EXCEEDED 的結果中。

根據已達到的特定配額上限查看 total_rows 或 total_input_bytes。如果錯誤是表格層級配額，請依 table_id 篩選。

舉例來說，下列查詢會顯示每分鐘擷取的位元組總數，以及配額錯誤總數：

SELECT
 start_timestamp,
 error_code,
 SUM(total_input_bytes) as sum_input_bytes,
 SUM(IF(error_code IN ('QUOTA_EXCEEDED', 'RATE_LIMIT_EXCEEDED'),
     total_requests, 0)) AS quota_error
FROM
 `region-REGION_NAME`.INFORMATION_SCHEMA.STREAMING_TIMELINE_BY_PROJECT
WHERE
  start_timestamp > TIMESTAMP_SUB(CURRENT_TIMESTAMP, INTERVAL 1 DAY)
GROUP BY
 start_timestamp,
 error_code
ORDER BY 1 DESC

解析度

如要解決這項配額錯誤，請按照下列步驟操作：

  • 如果您使用 insertId 欄位進行重複資料刪除，且專案位於支援較高串流配額的區域，建議您移除 insertId 欄位。這個解決方案可能需要額外步驟，才能手動移除重複資料。詳情請參閱手動移除重複內容。

  • 如果您並非使用 insertId，或是無法加以移除，請監控 24 小時內的串流流量，並分析配額錯誤：

    • 如果大部分是 RATE_LIMIT_EXCEEDED 錯誤，而非 QUOTA_EXCEEDED 錯誤，且整體流量低於配額的 80%，這些錯誤可能表示流量暫時暴增。您可以在每次重試之間使用指數輪詢重試作業，以處理這些錯誤。

    • 如果您使用 Dataflow 工作插入資料，請考慮使用載入工作，而非串流插入。詳情請參閱「設定插入方法」。如果您使用 Dataflow 和自訂 I/O 連接器，建議改用內建的 I/O 連接器。詳情請參閱「自訂 I/O 模式」。

    • 如果看到 QUOTA_EXCEEDED 錯誤，或整體流量持續超過配額的 80%，請提交配額增加要求。詳情請參閱「要求調整配額」。

    • 您也可以考慮使用較新的 Storage Write API 取代串流插入，這項 API 的輸送量較高、價格較低，而且提供許多實用功能。