Storage Write API (gRPC) 簡介

BigQuery Storage Write API (gRPC) 可讓您透過雙向 gRPC 連線，將記錄串流及批次載入 BigQuery。

如果是新專案，建議使用 Storage Write API (gRPC)，而非 Storage Write API (REST)。Storage Write API (gRPC) 的擷取定價較低，且功能更強大，包括串流層級交易和單次傳送語意。

所需權限

如要使用 Storage Write API (gRPC)，您必須具備 bigquery.tables.updateData 權限。

下列預先定義的 Identity and Access Management (IAM) 角色包含 bigquery.tables.updateData 權限：

  • bigquery.dataEditor
  • bigquery.dataOwner
  • bigquery.admin

如要進一步瞭解 BigQuery 的 IAM 角色和權限，請參閱「預先定義的角色和權限」。

驗證範圍

如要使用 Storage Write API (gRPC)，必須具備下列其中一個 OAuth 範圍：

  • https://www.googleapis.com/auth/bigquery
  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/bigquery.insertdata

詳情請參閱驗證總覽一文。

Storage Write API (gRPC) 總覽

Storage Write API (gRPC) 的核心抽象概念是「串流」。串流會將資料寫入 BigQuery 資料表。多個串流可以同時寫入同一個資料表。

預設串流

Storage Write API (gRPC) 提供預設串流，適用於資料持續傳入的串流情境。這類環境具有下列特性：

  • 寫入預設串流的資料可立即用於查詢。
  • 預設串流支援至少一次語意。
  • 您不需要明確建立預設串流。

如果您是從 Storage Write API (REST) 遷移，建議使用預設串流。兩者的寫入語意相似，但 Storage Write API 的資料復原能力更強，擴充限制也較少。

API 流程：

  1. AppendRows (迴圈)

如需更多資訊和程式碼範例，請參閱「使用預設串流，確保至少一次語意」。

應用程式建立的串流

如果您需要下列任一行為，可以明確建立串流：

  • 透過串流偏移，使用僅一次寫入語意。
  • 支援其他 ACID 屬性。

一般來說，應用程式建立的串流可進一步控管功能，但會增加複雜度。

建立串流時，您需要指定類型。類型會控管寫入串流的資料何時可在 BigQuery 中讀取。

待處理類型

在待處理類型中，記錄會緩衝處理並處於待處理狀態，直到您提交串流為止。提交串流後，所有待處理資料都可供讀取。修訂版本是一項不可分割的作業。這種類型適用於批次工作負載，可做為 BigQuery 載入工作的替代方案。詳情請參閱「使用 Storage Write API (gRPC) 批次載入資料」。

API 流程：

  1. CreateWriteStream
  2. AppendRows (迴圈)
  3. FinalizeWriteStream
  4. BatchCommitWriteStreams

承諾使用合約類型

在「committed」類型中，記錄寫入串流後即可立即讀取。如果串流工作負載需要極低的讀取延遲時間，請使用這種類型。預設串流會使用已提交類型的至少一次形式。詳情請參閱「使用已提交類型，確保語意僅執行一次」。

API 流程：

  1. CreateWriteStream
  2. AppendRows (迴圈)
  3. FinalizeWriteStream (選用)

緩衝類型

緩衝類型是進階類型，一般不應使用，除非搭配 Apache Beam BigQuery I/O 連接器。如果您有少量批次，且希望確保這些批次同時顯示，請使用已修訂類型，並在一個要求中傳送每個批次。這種類型會提供資料列層級修訂，並緩衝處理記錄，直到透過清除串流修訂資料列為止。

API 流程：

  1. CreateWriteStream
  2. AppendRows ⇒ FlushRows (迴圈)
  3. FinalizeWriteStream (選用)

選取類型

請參考下列流程圖，判斷哪種類型最適合您的工作負載：

圖片

API 詳細資料

使用 Storage Write API 時，請注意下列事項：

AppendRows

AppendRows 方法會將一或多筆記錄附加至串流。第一次呼叫 AppendRows 時，必須包含串流名稱和資料結構定義，並指定為 DescriptorProto。或者，如果您是以 Apache Arrow 格式擷取資料，可以在第一次呼叫 AppendRows 時，新增序列化的 Arrow 結構定義。最佳做法是在每次 AppendRows 呼叫中傳送一批資料列。請勿一次只傳送一列。

Proto 緩衝區處理

通訊協定緩衝區提供語言中立、平台中立、可擴充的機制，能以向前相容和回溯相容的方式序列化結構化資料。優點是能提供精簡的資料儲存空間，並快速有效率地剖析資料。如要進一步瞭解通訊協定緩衝區，請參閱「通訊協定緩衝區總覽」。

如果您要直接使用預先定義的通訊協定緩衝區訊息來取用 API，通訊協定緩衝區訊息不得使用 package 指定碼，且所有巢狀或列舉類型都必須在頂層根訊息中定義。不得參照外部訊息。如需範例，請參閱 sample_data.proto。

Java 和 Go 用戶端支援任意通訊協定緩衝區，因為用戶端程式庫會正規化通訊協定緩衝區結構定義。

Apache Arrow 處理

Apache Arrow 是通用的資料欄格式和多語言工具箱，用於資料處理。Apache Arrow 提供與語言無關、以資料欄為導向的記憶體格式，適用於平面和階層式資料，可有效率地在現代硬體上執行分析作業。Storage Write API (gRPC) 支援使用 AppendRowsRequest 類別中的序列化 Arrow 結構定義和資料，擷取 Arrow。Python、Java 和 Rust 用戶端程式庫內建 Apache Arrow 擷取支援。

FinalizeWriteStream

FinalizeWriteStream 方法會完成串流，因此無法在串流中附加新資料。Pending 類型必須使用這個方法，Committed 和 Buffered 類型則可選擇是否使用。預設串流不支援這個方法。

錯誤處理

如果發生錯誤，傳回的 google.rpc.Status 可能會在錯誤詳細資料中包含 StorageError。請查看 StorageErrorCode，找出特定錯誤類型。如要進一步瞭解 Google API 錯誤模型，請參閱「錯誤」。

連線

Storage Write API (gRPC) 是使用雙向連線的 gRPC API。AppendRows 方法會建立串流連線。您可以在預設串流上開啟多個連線。這些附加作業是非同步的，可讓您同時傳送一系列寫入作業。每個雙向連線的回應訊息都會按照要求傳送的順序抵達。

應用程式建立的串流只能有一個有效連線。最佳做法是限制有效連線數量，並盡可能使用單一連線寫入多筆資料。在 Java、Go 或 Rust 中使用預設串流時，您可以透過 Storage Write API (gRPC) 多工處理，使用共用連線寫入多個目的地資料表。

一般來說，單一連線至少支援 1 MBps 的處理量。上限取決於多項因素，例如網路頻寬、資料結構定義和伺服器負載。連線達到處理量上限時，系統可能會拒絕傳入的要求，或將要求排入佇列，直到傳輸中的要求數量減少為止。如需更多處理量，請建立更多連線。

如果連線閒置過久，BigQuery 會關閉 gRPC 連線。如果發生這種情況，回應代碼會是 HTTP 409。如果伺服器重新啟動或因其他原因，gRPC 連線也可能關閉。如果發生連線錯誤，請建立新的連線。如果連線關閉，Java、Go 和 Rust 用戶端程式庫會自動重新連線。

用戶端程式庫支援

Storage Write API (gRPC) 的用戶端程式庫支援多種程式設計語言，並提供基礎的 gRPC API 建構。這個 API 採用雙向串流等進階功能，可能需要額外的開發工作才能支援。為此，這個 API 提供多種高階抽象概念，可簡化這些互動，並減少開發人員的疑慮。建議您盡可能使用這些其他程式庫抽象化。

本節將進一步說明語言和程式庫，其中提供開發人員在產生的 API 之外的其他功能。

如要查看與 Storage Write API (gRPC) 相關的程式碼範例，請參閱「所有 BigQuery 程式碼範例」。

Java 用戶端

Java 用戶端程式庫提供兩個寫入器物件：

  • StreamWriter：接受通訊協定緩衝區格式的資料。

  • JsonStreamWriter：接受 JSON 格式的資料，並在透過網路傳送前，將資料轉換為通訊協定緩衝區。JsonStreamWriter 也支援自動更新結構定義。如果資料表結構定義變更，寫入器會自動重新連線至新的結構定義，讓用戶端使用新的結構定義傳送資料。

這兩種寫入器的程式設計模型類似。主要差異在於酬載的格式。

寫入器物件會管理 Storage Write API (gRPC) 連線。寫入器物件會自動清除要求、在要求中加入區域轉送標頭，並在連線錯誤後重新連線。如果直接使用 gRPC API，則必須處理這些細節。

您也可以使用 Apache Arrow 擷取格式，做為透過 Storage Write API (gRPC) 擷取資料的替代通訊協定。詳情請參閱「使用 Apache Arrow 格式擷取資料」。

Go 用戶端

Go 用戶端採用用戶端伺服器架構，使用 proto2 以通訊協定緩衝區格式編碼訊息。如要進一步瞭解如何使用 Go 用戶端，並查看程式碼範例，請參閱 Go 說明文件。

Python 用戶端

Python 用戶端是包裝 gRPC API 的低階用戶端。如要使用這個用戶端，您必須按照指定類型的 API 流程，以通訊協定緩衝區的形式傳送資料。

請避免在 Python 中使用動態 proto 訊息產生，因為該程式庫的效能不佳。

如要進一步瞭解如何搭配使用通訊協定緩衝區和 Python，請參閱通訊協定緩衝區基本概念 Python 教學課程。

您也可以使用 Apache Arrow 擷取格式做為替代通訊協定，透過 Storage Write API 擷取資料。詳情請參閱「使用 Apache Arrow 格式擷取資料」。

NodeJS 用戶端

NodeJS 用戶端程式庫接受 JSON 輸入，並提供自動重新連線支援。如要瞭解如何使用用戶端，請參閱說明文件。

Rust 用戶端

Rust 用戶端程式庫提供 Write 用戶端，以及各串流類型 (DefaultWriter、CommittedWriter、PendingWriter 和 BufferedWriter) 的類型化寫入器物件。寫入器接受 Apache Arrow 格式的資料，並自動管理 Storage Write API (gRPC) 連線、轉送標頭、重試，以及連線錯誤後的重新連線。如要擷取 JSON 資料，您可以使用 arrow-json crate，將 JSON 記錄轉換為 Apache Arrow 記錄批次。

如要進一步瞭解如何使用 Rust 用戶端，請參閱 Rust 說明文件；如需範例程式碼，請參閱「使用 Apache Arrow 格式擷取資料」。

處理無法使用的情況

使用指數輪詢重試可減輕隨機錯誤和短暫服務中斷的影響，但如要避免在長時間服務中斷期間捨棄資料列，則需要更周全的考量。特別是，如果用戶端持續無法插入資料列，該怎麼辦？

這取決於您的需求。舉例來說，如果 BigQuery 用於營運分析，且可接受遺漏部分資料列，則用戶端可在重試幾次後放棄並捨棄資料。相反地，如果每一列都對業務至關重要 (例如財務資料)，則需要制定策略來保留資料，直到稍後可以插入為止。

處理持續性錯誤的常見方法之一，是將資料列發布至 Pub/Sub 主題，以便日後評估及插入。另一種常見方法是將資料暫時保存在用戶端。這兩種方法都能讓用戶端保持暢通，同時確保在可用性恢復後，所有資料列都能插入。

串流至分區資料表

Storage Write API (gRPC) 支援將資料串流至分區資料表。

串流資料時，資料一開始會放在 __UNPARTITIONED__ 分區。收集到足夠的未分區資料後，BigQuery 會重新分區資料，並將資料放入適當的分區。不過，服務水準協議 (SLA) 並未定義資料從 __UNPARTITIONED__ 分區移出的時間。

如果是擷取時間分區和時間單位資料欄分區資料表，您可以使用其中一個偽列 (_PARTITIONTIME 或 _PARTITIONDATE，視您偏好的資料類型而定)，篩除 __UNPARTITIONED__ 分區中的 NULL 值，將未分區的資料排除在查詢之外。

擷取時間分區

串流至擷取時間分區資料表時，Storage Write API (gRPC) 會根據目前的系統世界標準時間推論目的地分區。

如果您將資料串流至每日分區資料表，則可在要求中提供分區修飾符，覆寫日期推論。在 tableID 參數中加入裝飾器。舉例來說，您可以使用 table1$20250601 分區修飾符，將資料串流至資料表 table1 中對應 2025-06-01 的分區。

使用分區裝飾器串流時，您可以串流至過去 31 天到未來 16 天的分區。如要寫入這些範圍以外日期的分區，請改用載入或查詢工作，詳情請參閱「將資料寫入特定分區」。

使用分區裝飾器串流時，僅支援每日分區資料表，不支援每小時、每月或每年分區資料表。

按時間單位資料欄分區

串流至時間單位分區資料表時，BigQuery 會根據資料表預先定義的 DATE、DATETIME 或 TIMESTAMP 分區資料欄值，自動將資料放入正確的分區。如果分區資料欄參照的資料介於過去 10 年和未來 1 年之間，您就可以將資料串流至時間單位資料欄分區資料表。

整數範圍分區

串流至整數範圍分區資料表時，BigQuery 會根據資料表預先定義的 INTEGER 分區欄值，自動將資料放入正確的分區。

Fluent Bit Storage Write API (gRPC) 輸出外掛程式

Fluent Bit Storage Write API (gRPC) 輸出外掛程式會自動將 JSON 記錄擷取至 BigQuery，您不必編寫程式碼。有了這個外掛程式，您只需要設定相容的輸入外掛程式和設定檔，即可開始串流資料。Fluent Bit 是開放原始碼跨平台記錄處理器和轉送器，使用輸入和輸出外掛程式處理不同類型的資料來源和接收器。

此外掛程式支援下列項目：

  • 使用預設類型的至少一次語意。
  • 使用已提交類型的僅一次語意。
  • 在出現背壓時，動態調整預設串流。

支援 Apache Iceberg

您可以使用 Storage Write API (gRPC)，將資料串流至 Iceberg 資料表。詳情請參閱「Apache Iceberg 代管資料表」。

Storage Write API (gRPC) 專案指標

如要使用 Storage Write API (gRPC) 監控資料擷取作業，請使用 INFORMATION_SCHEMA.WRITE_API_TIMELINE 檢視畫面，或查看 Google Cloud 指標。

對最近串流的資料使用 data manipulation language (DML)

您可以使用 data manipulation language (DML)，例如 UPDATE、DELETE 或 MERGE 陳述式，修改 BigQuery Storage Write API (gRPC) 最近寫入 BigQuery 資料表的資料列。最近的寫入是指過去 30 分鐘內發生的寫入。

如要進一步瞭解如何使用 DML 修改串流資料，請參閱「使用資料操縱語言」。

限制

  • 針對最近串流的資料執行變更 DML 陳述式的支援，不適用於使用 Storage Write API (REST) 串流的資料。
  • 不支援在多陳述式交易中，對最近串流的資料執行變動 DML 陳述式。

使用 max_staleness 查詢串流資料

根據預設，每次對含有串流資料的資料表執行查詢時，BigQuery 都會納入查詢執行時間前串流的資料列，傳回最新結果。

如果您的用途不需要即時資料更新間隔 (例如資訊主頁或報表查詢)，可以設定資料過時程度，藉此縮短查詢延遲時間並降低成本。如要設定資料過時，請使用下列其中一種方法：

  • 在資料表層級設定過時程度 (CDC 或 materialized view)：在目的地資料表上設定 max_staleness 選項，允許查詢根據過時程度間隔內的近期資料快照傳回結果。詳情請參閱「變更資料擷取 max_staleness」和「使用 max_staleness 的 materialized view」。
  • 覆寫查詢或工作階段的過時程度：在多重陳述式查詢或工作階段中設定 @@max_staleness_override 系統變數，即可動態覆寫過時程度，不必變更資料表層級設定，例如 SET @@max_staleness_override = INTERVAL 10 MINUTE;。

Storage Write API (gRPC) 配額

如要瞭解 Storage Write API (gRPC) 的配額和限制，請參閱「BigQuery Storage Write API (gRPC) 配額和限制」。

您可以在Google Cloud 控制台的「配額」頁面，監控並行連線和處理量配額用量。

計算處理量

假設您的目標是從 1 億個端點收集記錄，每分鐘建立 1,500 筆記錄。接著，您可以將處理量估算為 100 million * 1,500 / 60 seconds = 2.5 GB per second。請務必事先確認您有足夠的配額，可提供這項處理量。

Storage Write API (gRPC) 定價

如要瞭解定價，請參閱「資料擷取定價」。

用途範例

假設有一個管道會處理端點記錄中的事件資料。事件會持續產生，且必須盡快在 BigQuery 中開放查詢。由於資料更新間隔對這個用途至關重要，因此 Storage Write API (gRPC) 是將資料擷取至 BigQuery 的最佳選擇。建議架構是將事件傳送至 Pub/Sub，再由串流 Dataflow 管道直接串流至 BigQuery，讓這些端點保持精簡。

這個架構的主要可靠性問題，是如何處理無法將記錄插入 BigQuery 的情況。如果每筆記錄都很重要且不能遺失，則必須先緩衝資料，再嘗試插入。在上述建議架構中，Pub/Sub 可透過訊息保留功能扮演緩衝區的角色。Dataflow 管道應設為使用截斷指數輪詢重試 BigQuery 串流資料即時插入。當 Pub/Sub 做為緩衝區的容量用盡時 (例如 BigQuery 長時間無法使用或網路故障)，資料必須保留在用戶端，且用戶端需要一種機制，在可用性恢復後繼續插入保留的記錄。如要進一步瞭解如何處理這種情況，請參閱 Google Pub/Sub 可靠性指南網誌文章。

另一種需要處理的失敗情況是「有害記錄」。有害記錄是指因無法插入而遭 BigQuery 拒絕的記錄 (發生不可重試的錯誤)，或是在達到重試次數上限後仍未成功插入的記錄。這兩種類型的記錄都應由 Dataflow 管道儲存在「無效信件佇列」中，以便進一步調查。

如需「僅限一次」語意，請以已提交類型建立寫入串流，並由用戶端提供記錄偏移。只有在偏移值與下一個附加偏移值相符時，系統才會執行寫入作業，因此可避免重複。如未提供偏移值，系統會將記錄附加至串流目前的結尾，而重試失敗的附加作業可能會導致記錄在串流中出現多次。

如果不需要「僅限一次」保證，寫入預設串流可提高處理量，且不會計入建立寫入串流的配額限制。

預估網路的處理量，並事先確保有足夠的配額來處理。

如果工作負載產生或處理資料的速率非常不平均，請嘗試在用戶端上平滑處理任何負載高峰，並以穩定的處理量串流至 BigQuery。這可簡化容量規劃。如果無法這樣做，請確保您已準備好在短暫高峰期間，處理吞吐量超過配額時發生的 429 (資源耗盡) 錯誤。

如需使用 Storage Write API (gRPC) 的詳細範例，請參閱「使用 Storage Write API (gRPC) 串流資料」。

後續步驟