建立 BigQuery 訂閱項目

本文說明如何建立 BigQuery 訂閱項目。您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API 建立 BigQuery 訂閱項目。

事前準備

閱讀本文前，請先熟悉下列概念：

• 訂閱的運作方式。

• BigQuery 訂閱項目的工作流程。

• 如何設定無效信件主題，處理訊息傳送失敗的問題。

除了熟悉 Pub/Sub 和 BigQuery 之外，請務必符合下列先決條件，再建立 BigQuery 訂閱項目：

• BigQuery 資料表存在。或者，您也可以在建立 BigQuery 訂閱項目時建立一個，詳情請參閱本文後續章節。

• Pub/Sub 主題結構定義與 BigQuery 資料表結構定義的相容性。如果新增不相容的 BigQuery 資料表，系統會顯示與相容性相關的錯誤訊息。詳情請參閱「結構定義相容性」。

必要角色和權限

以下是角色和權限相關的規範：

• 如要建立訂閱項目，您必須在專案層級設定存取權控管。

• 如果訂閱項目和主題位於不同專案，您也需要資源層級的權限，詳情請參閱本節稍後內容。

• 如要建立 BigQuery 訂閱項目，Pub/Sub 服務代理程式或自訂服務帳戶必須具備寫入特定 BigQuery 資料表的權限。如要進一步瞭解如何授予這些權限，請參閱本文的下一節。

• 您可以在專案中設定 BigQuery 訂閱項目，將資料寫入不同專案中的 BigQuery 資料表。

如要取得建立 BigQuery 訂閱項目所需的權限，請要求管理員授予您專案的 Pub/Sub 編輯者 (roles/pubsub.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備建立 BigQuery 訂閱項目所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立 BigQuery 訂閱項目，您必須具備下列權限：

• 從訂閱項目提取： pubsub.subscriptions.consume
• 建立訂閱項目： pubsub.subscriptions.create
• 刪除訂閱項目： pubsub.subscriptions.delete
• 取得訂閱方案： pubsub.subscriptions.get
• 列出訂閱項目： pubsub.subscriptions.list
• 更新訂閱項目： pubsub.subscriptions.update
• 將訂閱項目附加至主題： pubsub.topics.attachSubscription
• 取得訂閱項目的 IAM 政策： pubsub.subscriptions.getIamPolicy
• 為訂閱項目設定 IAM 政策： pubsub.subscriptions.setIamPolicy

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要允許某個專案中的主體在另一個專案中建立 BigQuery 訂閱項目，您必須在兩個專案中都授予該主體 Pub/Sub 編輯者 (roles/pubsub.editor) 角色。這項角色提供建立新 BigQuery 訂閱項目，並將其附加至原始主題的必要權限。主題的 Pub/Sub 編輯者 (roles/pubsub.editor) 角色也有助於將不同專案中的 BigQuery 訂閱項目附加至主題。

指派角色給服務帳戶

部分 Google Cloud 服務具有 Google Cloud代管的服務帳戶，可讓服務存取您的資源。這些服務帳戶稱為服務代理。Pub/Sub 會為每個專案建立並維護服務代理，格式為 [e-mail]。

您可以選擇讓 Pub/Sub 服務代理或自訂服務帳戶具備寫入 BigQuery 資料表的權限。

授予 Pub/Sub 服務代理權限後，專案中任何有權建立訂閱項目的使用者，都能寫入 BigQuery 資料表。如要提供更精細的 BigQuery 資料表寫入權限，請改為設定自訂服務帳戶。

如要進一步瞭解 BigQuery IAM，請參閱 BigQuery 角色和權限。

將 BigQuery 角色指派給 Pub/Sub 服務代理程式

如要使用 Pub/Sub 服務代理程式建立 BigQuery 訂閱項目，該代理程式必須有權寫入特定 BigQuery 資料表，並讀取資料表的中繼資料。

將 BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色授予 Pub/Sub 服務代理程式。您可以針對個別表格或整個專案授予權限。

資料表

1. 前往 Google Cloud 控制台的「BigQuery Studio」。

   前往 BigQuery Studio

2. 在標示為「依名稱和標籤篩選」的「Explorer」窗格搜尋方塊中，輸入資料表名稱並按下 Enter 鍵。

3. 按一下要授予權限的表格。

4. 依序選取表格的「更多動作」 >「共用」>「權限」。

   或者，按一下表格，然後在主頁面依序點選「共用」 >「權限」。

   「共用權限」視窗隨即開啟。

5. 按一下「Add principal」(新增主體)。

6. 在「新增主體」部分，輸入包含訂閱項目的專案的 Pub/Sub 服務代理名稱。服務代理的格式為 [e-mail]。舉例來說，如果專案為 project-number=112233445566，服務代理程式的格式為 [e-mail]。

7. 在「請選擇角色」下拉式選單中輸入 BigQuery，然後選取「BigQuery 資料編輯者」角色。

8. 按一下 [儲存]。

專案

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」(身分與存取權管理) 頁面

2. 按一下「授予存取權」。

3. 在「新增主體」部分，輸入 Pub/Sub 服務代理程式的名稱。服務代理的格式為 [e-mail]。舉例來說，如果專案為 project-number=112233445566，服務代理程式的格式為 [e-mail]。

4. 在「指派角色」部分中，按一下「新增其他角色」。

5. 在「請選擇角色」下拉式選單中輸入 BigQuery，然後選取「BigQuery 資料編輯者」角色。

6. 按一下 [儲存]。

將 BigQuery 角色指派給自訂服務帳戶

如要使用自訂服務帳戶寫入 BigQuery 資料表，請設定下列權限：

• 自訂服務帳戶必須具備寫入特定 BigQuery 資料表和讀取資料表的中繼資料權限。
• Pub/Sub 服務代理必須具備自訂服務帳戶的 iam.serviceAccounts.getAccessToken 權限。
• 建立訂閱項目的使用者必須擁有自訂服務帳戶的 iam.serviceAccounts.actAs 權限。

請按照下列步驟建立服務帳戶並授予權限：

1. 建立自訂服務帳戶。服務帳戶必須與訂閱項目位於相同專案。

2. 將「BigQuery 資料編輯者」(roles/bigquery.dataEditor) 角色授予自訂服務帳戶。

   您可以授予服務帳戶專案中單一資料表的權限，或是專案中所有資料表的權限。如要這麼做，請參閱「將 BigQuery 角色指派給 Pub/Sub 服務代理程式」一文中的適當章節。在程序中，將 Pub/Sub 服務代理人電子郵件地址替換為自訂服務帳戶電子郵件地址。

3. 授予 Pub/Sub 服務代理程式自訂服務帳戶或專案中所有服務帳戶的 iam.serviceAccounts.getAccessToken 權限。如要授予這項權限，請將 roles/iam.serviceAccountTokenCreator 角色授予 Pub/Sub 服務代理。

   請根據需求選擇合適的方法。

服務帳戶

1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

   前往「Service accounts」(服務帳戶)

2. 在「Filter」(篩選器) 中輸入自訂服務帳戶的名稱。

3. 從清單中選取服務帳戶。

4. 按一下「具備存取權的主體」。

5. 按一下「授予存取權」。

6. 在「新增主體」部分，輸入含有訂閱項目的專案的 Pub/Sub 服務代理程式名稱。服務代理程式的格式為 [e-mail]。舉例來說，如果專案為 project-number=112233445566，服務代理程式的格式為 [e-mail]。

7. 在「Select a role」(請選擇角色) 下拉式選單中輸入 Service Account，然後選取「Service Account Token Creator」(服務帳戶憑證建立者) 角色。

8. 按一下 [儲存]。

專案

1. 前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

   前往「IAM」(身分與存取權管理) 頁面

2. 按一下「授予存取權」。

3. 在「新增主體」部分，輸入自訂服務帳戶的名稱。

4. 在「指派角色」部分中，按一下「新增其他角色」。

5. 在「Select a role」(請選擇角色) 下拉式選單中輸入 Service Account，然後選取「Service Account Token Creator」(服務帳戶憑證建立者) 角色。

6. 按一下 [儲存]。

如果您建立了自訂服務帳戶，應該已具備必要的iam.serviceAccounts.actAs權限。如要將服務帳戶的權限授予他人：

1. 前往 Google Cloud 控制台的「Service accounts」(服務帳戶) 頁面。

   前往「Service accounts」(服務帳戶)

2. 在「Filter」(篩選器) 中輸入自訂服務帳戶的名稱。

3. 從清單中選取服務帳戶。

4. 按一下「具備存取權的主體」。

5. 按一下「授予存取權」。

6. 在「新增主體」部分，輸入要授予存取權的帳戶名稱。

7. 在「Select a role」(選取角色) 下拉式選單中輸入 Service Account，然後選取「Service Account User」(服務帳戶使用者) 角色。

8. 此外，如果 BigQuery 資料表是 Apache Iceberg 資料表，請授予 Pub/Sub 服務帳戶「Storage 管理員」角色 (roles/storage.admin)，以便存取 Cloud Storage bucket。

9. 按一下 [儲存]。

BigQuery 訂閱項目屬性

設定 BigQuery 訂閱項目時，您可以指定下列屬性。

常見屬性

瞭解可為所有訂閱項目設定的常見訂閱項目屬性。

使用主題結構定義

這個選項可讓 Pub/Sub 使用訂閱項目所連結的 Pub/Sub 主題結構定義。此外，Pub/Sub 會將訊息中的欄位寫入 BigQuery 資料表中的對應欄。

注意： 結構定義或結構定義修訂版本一經刪除即無法復原。如果訊息在發布時是根據已刪除的結構定義修訂版本驗證，則無法使用啟用「使用主題結構定義」的 BigQuery 訂閱項目寫入 BigQuery。建議您復原結構定義，而非刪除結構定義或修訂版本。

使用這個選項時，請務必確認是否符合下列額外規定：

• 主題結構定義和 BigQuery 結構定義中的欄位必須具有相同名稱，且類型必須彼此相容。

• 主題結構定義中的任何選填欄位，在 BigQuery 結構定義中也必須是選填欄位。

• 主題結構定義中的必填欄位不一定要是 BigQuery 結構定義中的必填欄位。

• 如果 BigQuery 欄位不在主題結構定義中，這些 BigQuery 欄位就必須處於 NULLABLE 模式。

• 如果主題結構定義有 BigQuery 結構定義中沒有的額外欄位，且這些欄位可以捨棄，請選取「捨棄不明欄位」選項。

• 您只能選取其中一個訂閱屬性：「使用主題結構定義」或「使用資料表結構定義」。

如未選取「使用主題結構定義」或「使用資料表結構定義」選項，請確認 BigQuery 資料表有名為「data」的資料欄，且類型為 BYTES、STRING 或 JSON。dataPub/Sub 會將訊息寫入這個 BigQuery 資料欄。

您可能不會立即看到 Pub/Sub 主題結構定義或 BigQuery 資料表結構定義的變更，對寫入 BigQuery 資料表的訊息生效。舉例來說，如果啟用「捨棄不明欄位」選項，且 Pub/Sub 結構定義中有某個欄位，但 BigQuery 結構定義中沒有，即使將該欄位新增至 BigQuery 結構定義，寫入 BigQuery 資料表的訊息可能仍不包含該欄位。最終結構定義會同步處理，後續訊息也會包含該欄位。

為 BigQuery 訂閱項目使用「使用主題結構定義」選項時，您也可以運用 BigQuery 變更資料擷取 (CDC) 功能。CDC 會處理現有資料列的變更並套用，藉此更新 BigQuery 資料表。

如要進一步瞭解這項功能，請參閱「使用變更資料擷取功能串流傳輸資料表更新」。

如要瞭解如何搭配 BigQuery 訂閱項目使用這項功能，請參閱「BigQuery 變更資料擷取」。

使用資料表結構定義

這個選項可讓 Pub/Sub 使用 BigQuery 資料表的結構定義，將 JSON 訊息的欄位寫入對應的資料欄。使用這個選項時，請記得檢查下列額外需求：

• BigQuery 資料表中每個資料欄的名稱只能包含英文字母 (a-z、A-Z)、數字 (0-9) 或底線 (_)。

• 發布的訊息必須採用 JSON 格式。

  如果 BigQuery 資料表欄位的資料類型為 JSON，Pub/Sub 訊息中的對應欄位必須是有效的逸出字串 JSON。舉例來說，如果資料欄名稱為 myData，訊息欄位就必須是 "myData": "{\"key\":\"value\"}"。BigQuery 會拒絕不含有效 JSON 的訊息。

• 系統支援下列 JSON 轉換：

  JSON 類型	BigQuery 資料類型
  string	NUMERIC、BIGNUMERIC、DATE、TIME、DATETIME 或 TIMESTAMP
  number	NUMERIC、BIGNUMERIC、DATE、TIME、DATETIME 或 TIMESTAMP

  • 使用 number 至 DATE、DATETIME、TIME 或 TIMESTAMP 轉換時，數字必須符合支援的表示法。
  • 使用 number 到 NUMERIC 或 BIGNUMERIC 轉換時，值的精確度和範圍會受限於 IEEE 754 浮點運算標準接受的範圍。如需高精確度或更廣泛的值範圍，請改用 string 轉換為 NUMERIC 或 BIGNUMERIC。
  • 使用 string 對 NUMERIC 或 BIGNUMERIC 轉換時，Pub/Sub 會假設字串是人類可讀的數字 (例如 "123.124")。如果處理字串時發生錯誤，Pub/Sub 會將字串視為以 BigDecimalByteStringEncoder 編碼的位元組。

• 如果訂閱項目的主題有相關聯的結構定義，則訊息編碼屬性必須設為 JSON。

• 如果訊息中沒有 BigQuery 欄位，這些 BigQuery 欄位就必須處於 NULLABLE 模式。

• 如果訊息含有 BigQuery 結構定義中沒有的額外欄位，且這些欄位可以捨棄，請選取「捨棄不明欄位」選項。

• 您只能選取其中一個訂閱屬性：「使用主題結構定義」或「使用資料表結構定義」。

如未選取「使用主題結構定義」或「使用資料表結構定義」選項，請確認 BigQuery 資料表有名為「data」的資料欄，且類型為 BYTES、STRING 或 JSON。dataPub/Sub 會將訊息寫入這個 BigQuery 資料欄。

您可能不會立即看到寫入 BigQuery 資料表的訊息生效，舉例來說，如果啟用「捨棄不明欄位」選項，且訊息中存在某個欄位，但 BigQuery 結構定義中沒有該欄位，即使將該欄位新增至 BigQuery 結構定義，寫入 BigQuery 資料表的訊息可能仍不包含該欄位。最終結構定義會同步處理，後續訊息也會包含該欄位。

為 BigQuery 訂閱項目使用「使用資料表結構定義」選項時，您也可以運用 BigQuery 變更資料擷取 (CDC) 功能。CDC 會處理現有資料列的變更，並套用至 BigQuery 資料表，藉此更新資料表。

如要進一步瞭解這項功能，請參閱「使用變更資料擷取功能串流傳輸資料表更新」。

如要瞭解如何搭配 BigQuery 訂閱項目使用這項功能，請參閱「BigQuery 變更資料擷取」。

捨棄不明欄位

這個選項會搭配「使用主題結構定義」或「使用資料表結構定義」選項使用。啟用這個選項後，Pub/Sub 會捨棄主題結構定義或訊息中現有但不在 BigQuery 結構定義中的任何欄位。將訊息寫入 BigQuery 資料表時，系統會捨棄不屬於 BigQuery 結構定義的欄位。

如未設定「捨棄不明欄位」，系統不會將含有額外欄位的訊息寫入 BigQuery，並會將該則訊息保留在訂閱項目的待處理工作中，除非您設定無效信件主題。

「捨棄不明欄位」設定不會影響 Pub/Sub 主題結構定義或 BigQuery 資料表結構定義中未定義的欄位。在這種情況下，系統會將有效的 Pub/Sub 訊息傳送至訂閱項目。不過，由於 BigQuery 沒有為這些額外欄位定義資料欄，因此在 BigQuery 寫入程序中，這些欄位會遭到捨棄。如要避免這種情況，請確保 Pub/Sub 訊息中包含的所有欄位，也包含在 BigQuery 資料表結構定義中。

額外欄位的行為也可能取決於使用的特定結構定義類型 (Avro、通訊協定緩衝區) 和編碼 (JSON、二進位)。如要瞭解這些因素如何影響額外欄位的處理方式，請參閱特定架構類型和編碼的說明文件。

寫入中繼資料

啟用這個選項後，Pub/Sub 會將每則訊息的中繼資料寫入 BigQuery 資料表中的其他資料欄。如未啟用，中繼資料就不會寫入 BigQuery 資料表。

如果選取「寫入中繼資料」選項，請確認 BigQuery 資料表具有下表所述的欄位。

如未選取「寫入中繼資料」選項，目的地 BigQuery 資料表就只需要 data 欄位，除非 use_topic_schema 為 true。如果同時選取「寫入中繼資料」和「使用主題結構定義」選項，主題的結構定義就不得包含任何名稱與中繼資料參數相符的欄位。這項限制包括這些蛇形命名法參數的駝峰式大小寫版本。

參數
subscription_name	STRING 訂閱項目名稱。
message_id	STRING 訊息 ID
publish_time	TIMESTAMP 發布訊息的時間。
data	BYTES、STRING 或 JSON 訊息內文。 如果目的地 BigQuery 資料表未選取「使用主題結構定義」或「使用資料表結構定義」，則必須提供 data 欄位。如果該欄位為 JSON 類型，則訊息內文必須是有效的 JSON。
attributes	STRING 或 JSON 內含所有訊息屬性的 JSON 物件。當中也包含 Pub/Sub 訊息的其他欄位，包括排序鍵 (如有)。

建立 BigQuery 訂閱項目

如要建立 BigQuery 傳送訂閱項目，請按照下列步驟操作。

控制台

1. 前往 Google Cloud 控制台的「建立訂閱項目」頁面。

   前往「訂閱項目」頁面

2. 在「Subscription ID」(訂閱項目 ID) 欄位中輸入名稱。如要瞭解如何命名訂閱項目，請參閱「主題或訂閱項目命名規範」。

3. 在「Select a Cloud Pub/Sub topic」(選取 Cloud Pub/Sub 主題) 方塊中，輸入或選取要接收訊息的主題。

4. 在「傳送類型」中，選取「寫入 BigQuery」。

5. 選取 BigQuery 資料表：

   1. 在「專案」中，選取包含 BigQuery 資料表的 Google Cloud 專案。

   2. 在「Dataset」(資料集) 部分，選取現有資料集或按一下「Create new dataset」(建立新的資料集) 建立新的資料集。如要瞭解如何建立資料集，請參閱「建立資料集」。

   3. 在「Table」(資料表) 欄位中，輸入資料表名稱。如要建立新資料表，請按一下連結，前往 BigQuery 的「建立新資料表」頁面。該頁面會在另一個分頁中開啟。如要瞭解如何建立資料表，請參閱「建立及使用資料表」。

6. 在「結構定義設定」中，選取下列任一選項：

   • 不使用結構定義。Pub/Sub 會將訊息位元組寫入名為「data」data的資料欄。

   • 使用主題結構定義。Pub/Sub 會使用與主題相關聯的結構定義。詳情請參閱「使用主題結構定義」。

   • 使用資料表結構定義。Pub/Sub 會使用 BigQuery 資料表的結構定義。詳情請參閱使用資料表結構定義。

7. 選用。如要將訊息中繼資料寫入 BigQuery 資料表，請選取「寫入中繼資料」。詳情請參閱「寫入中繼資料」。

8. 選用。如要捨棄 BigQuery 資料表結構定義中不存在的欄位，請選取「捨棄不明欄位」。詳情請參閱「捨棄不明欄位」一節。

9. 視需要設定一般訂閱屬性。強烈建議您啟用「Dead lettering」來處理訊息傳送失敗問題。詳情請參閱「無法傳送訊息的主題」。

10. 點選「建立」。

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. 如要建立 Pub/Sub 訂閱項目，請使用 gcloud pubsub subscriptions create 指令：

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID
   

   如要使用自訂服務帳戶，請以額外引數的形式提供該帳戶：

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
       --topic=TOPIC_ID \
       --bigquery-table=PROJECT_ID.DATASET_ID.TABLE_ID \
       --bigquery-service-account-email=SERVICE_ACCOUNT_NAME
   

   更改下列內容：

   • SUBSCRIPTION_ID：指定訂閱 ID。
   • TOPIC_ID：指定主題 ID。主題需要結構定義。
   • PROJECT_ID：指定專案 ID。
   • DATASET_ID：指定現有資料集的 ID。如要建立資料集，請參閱「 建立資料集」。
   • TABLE_ID：指定現有資料表的 ID。如果主題沒有結構定義，資料表就必須有 data 欄位。如要建立資料表，請參閱「使用結構定義建立空白資料表」。
   • SERVICE_ACCOUNT_NAME：指定用於寫入 BigQuery 的服務帳戶名稱。

C++

在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 C++ 設定操作說明進行操作。詳情請參閱 Pub/Sub C++ API 參考說明文件。

namespace pubsub = ::google::cloud::pubsub;
namespace pubsub_admin = ::google::cloud::pubsub_admin;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_id, std::string const& table_id) {
  google::pubsub::v1::Subscription request;
  request.set_name(
      pubsub::Subscription(project_id, subscription_id).FullName());
  request.set_topic(pubsub::Topic(project_id, topic_id).FullName());
  request.mutable_bigquery_config()->set_table(table_id);
  auto sub = client.CreateSubscription(request);
  if (!sub) {
    if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
      std::cout << "The subscription already exists\n";
      return;
    }
    throw std::move(sub).status();
  }

  std::cout << "The subscription was successfully created: "
            << sub->DebugString() << "\n";
}

C#

在嘗試這個範例之前，請先按照快速入門：使用用戶端程式庫中的 C# 設定操作說明進行操作。詳情請參閱 Pub/Sub C# API 參考說明文件。

using Google.Cloud.PubSub.V1;

public class CreateBigQuerySubscriptionSample
{
    public Subscription CreateBigQuerySubscription(string projectId, string topicId, string subscriptionId, string bigqueryTableId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        var subscriptionRequest = new Subscription
        {
            SubscriptionName = subscriptionName,
            TopicAsTopicName = topicName,
            BigqueryConfig = new BigQueryConfig
            {
                Table = bigqueryTableId
            }
        };
        var subscription = subscriber.CreateSubscription(subscriptionRequest);
        return subscription;
    }
}

Go

下列範例使用 Go Pub/Sub 用戶端程式庫的主要版本 (v2)。如果您仍在使用第 1 版程式庫，請參閱第 2 版遷移指南。如要查看第 1 版程式碼範例清單，請參閱 已淘汰的程式碼範例。

在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的操作說明設定 Go 環境。詳情請參閱 Pub/Sub Go API 參考說明文件。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

// createBigQuerySubscription creates a Pub/Sub subscription that exports messages to BigQuery.
func createBigQuerySubscription(w io.Writer, projectID, topic, subscription, table string) error {
	// projectID := "my-project"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// table := "my-project-id.dataset_id.table_id"
	ctx := context.Background()
	client, err := pubsub.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("pubsub.NewClient: %w", err)
	}
	defer client.Close()

	sub, err := client.SubscriptionAdminClient.CreateSubscription(ctx, &pubsubpb.Subscription{
		Name:  subscription,
		Topic: topic,
		BigqueryConfig: &pubsubpb.BigQueryConfig{
			Table:         table,
			WriteMetadata: true,
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create subscription: %w", err)
	}
	fmt.Fprintf(w, "Created BigQuery subscription: %v\n", sub)

	return nil
}

Java

在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Java 設定操作說明進行操作。詳情請參閱 Pub/Sub Java API 參考說明文件。

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.BigQueryConfig;
import com.google.pubsub.v1.ProjectSubscriptionName;
import com.google.pubsub.v1.ProjectTopicName;
import com.google.pubsub.v1.Subscription;
import java.io.IOException;

public class CreateBigQuerySubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String topicId = "your-topic-id";
    String subscriptionId = "your-subscription-id";
    String bigqueryTableId = "your-project.your-dataset.your-table";

    createBigQuerySubscription(projectId, topicId, subscriptionId, bigqueryTableId);
  }

  public static void createBigQuerySubscription(
      String projectId, String topicId, String subscriptionId, String bigqueryTableId)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {

      ProjectTopicName topicName = ProjectTopicName.of(projectId, topicId);
      ProjectSubscriptionName subscriptionName =
          ProjectSubscriptionName.of(projectId, subscriptionId);

      BigQueryConfig bigqueryConfig =
          BigQueryConfig.newBuilder().setTable(bigqueryTableId).setWriteMetadata(true).build();

      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              Subscription.newBuilder()
                  .setName(subscriptionName.toString())
                  .setTopic(topicName.toString())
                  .setBigqueryConfig(bigqueryConfig)
                  .build());

      System.out.println("Created a BigQuery subscription: " + subscription.getAllFields());
    }
  }
}

Node.js

在嘗試這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考說明文件。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
const {PubSub} = require('@google-cloud/pubsub');

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId,
  subscriptionNameOrId,
  bigqueryTableId,
) {
  const options = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

Node.ts

在嘗試這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Node.js 設定說明進行操作。詳情請參閱 Pub/Sub Node.js API 參考說明文件。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_ID';
// const bigqueryTableId = 'YOUR_TABLE_ID';

// Imports the Google Cloud client library
import {PubSub, CreateSubscriptionOptions} from '@google-cloud/pubsub';

// Creates a client; cache this for further use
const pubSubClient = new PubSub();

async function createBigQuerySubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
  bigqueryTableId: string,
) {
  const options: CreateSubscriptionOptions = {
    bigqueryConfig: {
      table: bigqueryTableId,
      writeMetadata: true,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);

  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 PHP 設定說明進行操作。 詳情請參閱 Pub/Sub PHP API 參考說明文件。

use Google\Cloud\PubSub\PubSubClient;
use Google\Cloud\PubSub\V1\BigQueryConfig;

/**
 * Creates a Pub/Sub BigQuery subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 * @param string $table      The BigQuery table to which to write.
 */
function create_bigquery_subscription($projectId, $topicName, $subscriptionName, $table)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $config = new BigQueryConfig(['table' => $table]);
    $subscription->create([
        'bigqueryConfig' => $config
    ]);

    printf('Subscription created: %s' . PHP_EOL, $subscription->name());
}

Python

在試用這個範例之前，請先按照快速入門：使用用戶端程式庫中的 Python 設定操作說明來進行。詳情請參閱 Pub/Sub Python API 參考說明文件。

from google.cloud import pubsub_v1

# TODO(developer)
# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "your-project.your-dataset.your-table"

publisher = pubsub_v1.PublisherClient()
subscriber = pubsub_v1.SubscriberClient()
topic_path = publisher.topic_path(project_id, topic_id)
subscription_path = subscriber.subscription_path(project_id, subscription_id)

bigquery_config = pubsub_v1.types.BigQueryConfig(
    table=bigquery_table_id, write_metadata=True
)

# Wrap the subscriber in a 'with' block to automatically call close() to
# close the underlying gRPC channel when done.
with subscriber:
    subscription = subscriber.create_subscription(
        request={
            "name": subscription_path,
            "topic": topic_path,
            "bigquery_config": bigquery_config,
        }
    )

print(f"BigQuery subscription created: {subscription}.")
print(f"Table for subscription is: {bigquery_table_id}")

Ruby

以下範例使用 Ruby Pub/Sub 用戶端程式庫 v3。如果您仍在使用第 2 版程式庫，請參閱 第 3 版遷移指南。如要查看 Ruby 第 2 版程式碼範例清單，請參閱 已淘汰的程式碼範例。

在試用這個範例之前，請先按照「快速入門：使用用戶端程式庫」的操作說明設定 Ruby 環境。詳情請參閱 Pub/Sub Ruby API 參考說明文件。

# project_id = "your-project-id"
# topic_id = "your-topic-id"
# subscription_id = "your-subscription-id"
# bigquery_table_id = "my-project:dataset-id.table-id"

pubsub = Google::Cloud::PubSub.new project_id: project_id
subscription_admin = pubsub.subscription_admin

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id),
  bigquery_config: {
    table: bigquery_table_id,
    write_metadata: true
  }

puts "BigQuery subscription created: #{subscription_id}."
puts "Table for subscription is: #{bigquery_table_id}"

監控 BigQuery 訂閱項目

Cloud Monitoring 提供多項指標，可監控訂閱項目。

如要查看所有可用的 Pub/Sub 相關指標及其說明，請參閱 Pub/Sub 的監控說明文件。

您也可以在 Pub/Sub 中監控訂閱項目。

後續步驟

• 使用 gcloud 指令建立或修改訂閱項目。
• 使用 REST API 建立或修改訂閱項目。
• 排解 BigQuery 訂閱項目問題。