本文將概述 BigQuery 訂閱項目、工作流程和相關屬性。
BigQuery 訂閱項目是一種匯出訂閱項目，會在收到訊息時，將訊息寫入現有 BigQuery 資料表。您不必設定個別的訂閱端。 使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API，建立、更新、列出、分離或刪除 BigQuery 訂閱項目。
如果沒有 BigQuery 訂閱類型，您需要提取或推送訂閱項目和訂閱者 (例如 Dataflow)，才能讀取訊息並將其寫入 BigQuery 資料表。如果訊息不需要額外處理，即可儲存在 BigQuery 資料表中，就不必執行 Dataflow 工作，改用 BigQuery 訂閱即可。
不過，如果 Pub/Sub 系統需要在資料儲存至 BigQuery 資料表前進行轉換，建議使用 Dataflow 管道。如要瞭解如何使用 Dataflow，以串流方式將 Pub/Sub 中的資料傳輸至 BigQuery 並進行轉換，請參閱「將 Pub/Sub 中的資料串流至 BigQuery」一文。
Dataflow 的「Pub/Sub 訂閱項目到 BigQuery」範本預設會強制執行「只傳送一次」的傳送作業。這通常是透過 Dataflow 管道內的重複資料刪除機制達成。不過，BigQuery 訂閱項目僅支援「至少一次」傳送。如果您的用途需要精確去重，請考慮在 BigQuery 中使用下游程序，處理潛在的重複資料。
事前準備
閱讀本文之前，請務必熟悉下列項目：
Pub/Sub 的運作方式和不同的 Pub/Sub 術語。
Pub/Sub 支援的不同類型訂閱項目，以及您可能想使用 BigQuery 訂閱項目的原因。
BigQuery 的運作方式，以及如何設定和管理 BigQuery 資料表。
BigQuery 訂閱工作流程
下圖顯示 BigQuery 訂閱項目與 BigQuery 之間的流程。
以下簡要說明圖 1 所示的工作流程：
- Pub/Sub 會使用 BigQuery 儲存空間寫入 API，將資料傳送至 BigQuery 資料表。
- 訊息會分批傳送至 BigQuery 資料表。
- 寫入作業成功完成後，API 會傳回「OK」回應。
- 如果寫入作業發生任何失敗，系統會對 Pub/Sub 訊息本身發出否定確認。然後重新傳送訊息。如果訊息傳送失敗次數過多，且訂閱項目已設定無效信件主題，系統就會將訊息移至無效信件主題。
BigQuery 訂閱項目的屬性
您為 BigQuery 訂閱項目設定的屬性，會決定 Pub/Sub 要將訊息寫入哪個 BigQuery 資料表，以及該資料表的結構定義類型。
詳情請參閱 BigQuery 屬性。
結構定義相容性
只有在建立 BigQuery 訂閱項目時選取「使用主題結構定義」選項，才適用本節內容。
Pub/Sub 和 BigQuery 定義結構定義的方式不同。Pub/Sub 結構定義採用 Apache Avro 或 Protocol Buffers 格式，而 BigQuery 結構定義則使用多種格式。
以下列出 Pub/Sub 主題與 BigQuery 資料表之間的結構定義相容性相關重要資訊。
如果訊息含有格式不正確的欄位，系統就不會將該訊息寫入 BigQuery。
在 BigQuery 結構定義中，
INT、SMALLINT、INTEGER、BIGINT、TINYINT和BYTEINT是INTEGER的別名；DECIMAL是NUMERIC的別名；BIGDECIMAL是BIGNUMERIC的別名。如果主題結構定義中的類型為
string，而 BigQuery 表格中的類型為JSON、TIMESTAMP、DATETIME、DATE、TIME、NUMERIC或BIGNUMERIC，則 Pub/Sub 訊息中這個欄位的任何值都必須符合BigQuery 資料類型指定的格式。支援部分 Avro 邏輯類型，詳見下表。如未列出任何邏輯類型，則只會比對註解中等效的 Avro 類型，詳情請參閱 Avro 規格。
以下是不同結構定義格式對應至 BigQuery 資料類型的集合。
Avro 類型
| Avro 類型 | BigQuery 資料類型 |
null |
Any NULLABLE |
boolean |
BOOLEAN |
int |
INTEGER、NUMERIC 或 BIGNUMERIC |
long |
INTEGER、NUMERIC 或 BIGNUMERIC |
float |
FLOAT64、NUMERIC 或 BIGNUMERIC |
double |
FLOAT64、NUMERIC 或 BIGNUMERIC |
bytes |
BYTES、NUMERIC 或 BIGNUMERIC |
string |
STRING、JSON、
TIMESTAMP、DATETIME、
DATE、TIME、
NUMERIC 或 BIGNUMERIC |
record |
RECORD/STRUCT |
array (共 Type) |
REPEATED Type |
map，值類型為 ValueType
|
REPEATED STRUCT <key STRING, value
ValueType> |
union，其中一個類型為 null，另一個為 Type |
NULLABLE Type |
其他 union |
無法對應 |
fixed |
BYTES、NUMERIC 或 BIGNUMERIC |
enum |
INTEGER |
Avro 邏輯類型
| Avro 邏輯類型 | BigQuery 資料類型 |
timestamp-micros |
TIMESTAMP |
date |
DATE |
time-micros |
TIME |
duration |
INTERVAL |
decimal |
NUMERIC 或 BIGNUMERIC |
通訊協定緩衝區型別
| 通訊協定緩衝區類型 | BigQuery 資料類型 |
double |
FLOAT64、NUMERIC 或 BIGNUMERIC |
float |
FLOAT64、NUMERIC 或 BIGNUMERIC |
int32 |
INTEGER、NUMERIC、BIGNUMERIC 或 DATE |
int64 |
INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME 或 TIMESTAMP |
uint32 |
INTEGER、NUMERIC、BIGNUMERIC 或 DATE |
uint64 |
NUMERIC 或 BIGNUMERIC |
sint32 |
INTEGER、NUMERIC 或 BIGNUMERIC |
sint64 |
INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME 或 TIMESTAMP |
fixed32 |
INTEGER、NUMERIC、BIGNUMERIC 或 DATE |
fixed64 |
NUMERIC 或 BIGNUMERIC |
sfixed32 |
INTEGER、NUMERIC、BIGNUMERIC 或 DATE |
sfixed64 |
INTEGER、NUMERIC、BIGNUMERIC、DATE、DATETIME 或 TIMESTAMP |
bool |
BOOLEAN |
string |
STRING、JSON、
TIMESTAMP、DATETIME、
DATE、TIME、
NUMERIC 或 BIGNUMERIC |
bytes |
BYTES、NUMERIC 或 BIGNUMERIC |
enum |
INTEGER |
message |
RECORD/STRUCT |
oneof |
無法對應 |
map<KeyType, ValueType> |
REPEATED RECORD<key KeyType, value
ValueType> |
enum |
INTEGER |
repeated/array of Type |
REPEATED Type |
日期和時間的整數表示法
從整數對應至其中一種日期或時間類型時，該數字必須代表正確的值。下表列出 BigQuery 資料類型與代表這些類型的整數之間的對應關係。
| BigQuery 資料類型 | 整數表示法 |
DATE |
自 Unix 紀元 (1970 年 1 月 1 日) 起算的天數 |
DATETIME |
以微秒為單位的日期和時間，使用 CivilTimeEncoder 表示民用時間 |
TIME |
以微秒為單位的時間，使用 CivilTimeEncoder 表示為民用時間 |
TIMESTAMP |
自 Unix 紀元 (世界標準時間 1970 年 1 月 1 日 00:00:00) 起算的微秒數 |
BigQuery 變更資料擷取
如果訂閱項目屬性中的 use_topic_schema 或 use_table_schema 設為 true，BigQuery 訂閱項目就會支援變更資料擷取 (CDC) 更新。如要搭配 use_topic_schema 使用這項功能，請使用下列欄位設定主題的結構定義：
_CHANGE_TYPE(必要)：設為UPSERT或DELETE的string欄位。如果寫入 BigQuery 資料表的 Pub/Sub 訊息將
_CHANGE_TYPE設為UPSERT，則 BigQuery 會更新具有相同鍵的資料列 (如果存在)，或插入新的資料列 (如果不存在)。如果寫入 BigQuery 資料表的 Pub/Sub 訊息將
_CHANGE_TYPE設為DELETE，BigQuery 會刪除資料表中具有相同鍵的資料列 (如有)。
_CHANGE_SEQUENCE_NUMBER(選用)：設為string的欄位，可確保系統依序處理對 BigQuery 資料表進行的更新和刪除作業。同一資料列鍵的訊息必須包含_CHANGE_SEQUENCE_NUMBER的單調遞增值。如果訊息的序號小於資料列處理的最高序號，就不會對 BigQuery 資料表中的資料列造成任何影響。序號必須符合_CHANGE_SEQUENCE_NUMBER格式。
如要搭配 use_table_schema 使用這項功能，請在 JSON 訊息中加入上述欄位。
如要瞭解 CDC 定價，請參閱「CDC 定價」。
BigQuery 中的 Apache Iceberg 專用 BigLake 資料表
BigQuery 訂閱項目可搭配 BigQuery 中的 Apache Iceberg 專用 BigLake 資料表使用，不需進行額外變更。
BigQuery 中的 Apache Iceberg 專用 BigLake 資料表，是您在 Google Cloud上建構開放格式 lakehouse 的基礎。這些資料表與標準 (內建) BigQuery 資料表一樣，提供全代管體驗，但會使用 Parquet 將資料儲存在客戶擁有的儲存空間 bucket 中，以便與 Iceberg 開放式資料表格式互通。
如要瞭解如何在 BigQuery 中建立 Apache Iceberg 專用的 BigLake 資料表，請參閱「建立 Iceberg 資料表」。
處理傳送失敗的訊息
如果 Pub/Sub 訊息無法寫入 BigQuery，就無法確認訊息。如要轉寄這類無法傳送的訊息，請在 BigQuery 訂閱項目中設定無法傳送的訊息主題。轉送至無效信件主題的 Pub/Sub 訊息包含 CloudPubSubDeadLetterSourceDeliveryErrorMessage 屬性，其中說明 Pub/Sub 訊息無法寫入 BigQuery 的原因。
如果 Pub/Sub 無法將訊息寫入 BigQuery，Pub/Sub 會延後傳送訊息，方式與推送延後行為類似。不過，如果訂閱項目附加了無法傳送的郵件主題，當訊息傳送失敗是因結構定義相容性錯誤所致時，Pub/Sub 不會延後傳送。
配額與限制
每個區域的 BigQuery 訂閱者輸送量都有配額限制。詳情請參閱 Pub/Sub 配額與限制。
BigQuery 訂閱項目會使用 BigQuery Storage Write API 寫入資料。如要瞭解 Storage Write API 的配額和限制，請參閱 BigQuery Storage Write API 要求。BigQuery 訂閱項目只會耗用 Storage Write API 的輸送量配額。在此情況下，您可以忽略其他 Storage Write API 配額考量事項。
定價
如要瞭解 BigQuery 訂閱項目的價格，請參閱 Pub/Sub 定價頁面。
後續步驟
建立訂閱項目，例如 BigQuery 訂閱項目。
排解 BigQuery 訂閱項目問題。
閱讀 BigQuery 相關資訊。
查看 Pub/Sub 的定價，包括 BigQuery 訂閱項目。
使用
gcloudCLI 指令建立或修改訂閱項目。使用 REST API 建立或修改訂閱項目。