建立 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. 視需要設定一般訂閱屬性。強烈建議您啟用「無法投遞郵件」，以處理訊息傳送失敗的問題。詳情請參閱「無法傳送訊息的主題」。

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 訂閱項目問題。