本文將概略說明 BigQuery 訂閱、工作流程和相關屬性。
BigQuery 訂閱項目是一種匯出訂閱項目，會在收到訊息時，將訊息寫入現有的 BigQuery 資料表。您不需要設定單獨的訂閱端。使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API 建立、更新、列出、分離或刪除 BigQuery 訂閱項目。
如果沒有 BigQuery 訂閱類型，您需要使用拉取或推送訂閱，以及讀取訊息並將其寫入 BigQuery 資料表的訂閱者 (例如 Dataflow)。如果訊息不需要在儲存至 BigQuery 資料表前進行額外處理，就不需要執行 Dataflow 工作，您可以改用 BigQuery 訂閱。
不過，如果 Pub/Sub 系統需要先進行一些資料轉換，才能將資料儲存在 BigQuery 資料表中，則仍建議使用 Dataflow 管道。如要瞭解如何使用 Dataflow 將資料從 Pub/Sub 串流至 BigQuery，並進行轉換，請參閱「從 Pub/Sub 串流至 BigQuery」一文。
從 Dataflow 到 BigQuery 的 Pub/Sub 訂閱項目範本，預設會強制執行一次傳送作業。這通常是透過 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(必要)：string欄位設為UPSERT或DELETE。如果寫入 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 定價」。
Apache Iceberg 專用 BigQuery 資料表
BigQuery 訂閱項目可搭配 Apache Iceberg 專用 BigQuery 資料表 (以下簡稱「Iceberg 資料表」) 使用，無須進行其他變更。
Iceberg 資料表可讓您在 Google Cloud上建構開放格式 lakehouse。Iceberg 資料表提供與 BigQuery 資料表相同的全代管體驗，但會使用 Parquet 將資料儲存在客戶擁有的儲存空間中，以便與 Iceberg 開放資料表格式互通。
如要瞭解如何建立 Iceberg 資料表，請參閱「建立 Iceberg 資料表」。
處理傳送失敗的訊息
如果 Pub/Sub 訊息無法寫入 BigQuery，就無法確認訊息。如要轉寄這類無法送達的訊息，請在 BigQuery 訂閱項目上設定死信主題。轉送至 dead-letter 主題的 Pub/Sub 訊息包含屬性 CloudPubSubDeadLetterSourceDeliveryErrorMessage，其中包含 Pub/Sub 訊息無法寫入 BigQuery 的原因。
如果 Pub/Sub 無法將訊息寫入 BigQuery，則會以類似於推送回退行為的方式，停止傳送訊息。不過，如果訂閱項目附加死信主題，當訊息因結構定義相容性錯誤而傳送失敗時，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 建立或修改訂閱項目。