建立 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 編輯者 (roles/pubsub.editor) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

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

所需權限

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

• pubsub.subscriptions.create 專案
• pubsub.topics.attachSubscription 這個主題

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

跨專案訂閱

如果您在一個專案中為另一個專案的主題建立訂閱項目，您必須對建立訂閱項目的專案具備 pubsub.subscriptions.create 權限，並對主題具備 pubsub.topics.attachSubscription 權限。

將 IAM 角色授予服務帳戶

Pub/Sub 會使用 Identity and Access Management (IAM) 服務帳戶存取 Google Cloud 資源。根據預設，這項作業會使用 Pub/Sub 服務代理 ([e-mail])。

如要讓 Pub/Sub 寫入 BigQuery 資料表，服務帳戶需要 BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色。您可以為專案或資料表授予服務帳戶權限，方法如下：

專案

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

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

2. 選取「包含 Google 提供的角色授予項目」。

3. 找到「Cloud Pub/Sub」服務帳戶所在的資料列，然後按一下 「Edit principal」(編輯主體)。

4. 點選「新增其他角色」，然後選取「BigQuery 資料編輯者」角色。

詳情請參閱「使用控制台授予 IAM 角色」一文。

資料表

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

   前往 BigQuery Studio

2. 在「Explorer」窗格的「Filter by name and labels」(依名稱和標籤篩選) 搜尋框中，輸入資料表名稱，然後按下 Enter 鍵。

3. 在搜尋結果中，按一下要授予權限的表格名稱。

4. 在「詳細資料」分頁中，依序點選 「共用」>「管理權限」。

5. 按一下「新增主體」，然後輸入服務帳戶 ID，格式如下：

   [e-mail]。

6. 在「指派角色」清單中，選取「BigQuery 資料編輯者」。

7. 按一下 [儲存]。主體就會取得指定資源的角色。

使用自訂服務帳戶

將 BigQuery 資料編輯者角色授予 Cloud Pub/Sub 服務帳戶後，凡是有權在專案中建立訂閱項目的使用者，都能寫入 BigQuery 資料表。如要提供更精細的權限，請改為設定使用者自行管理的服務帳戶。

如要設定使用者管理的服務帳戶，以便寫入 BigQuery，必須具備下列權限：

• 使用者自行管理的服務帳戶必須具備 BigQuery 資料編輯者角色。

• Cloud Pub/Sub 服務帳戶必須具備使用者自行管理的服務帳戶的 iam.serviceAccounts.getAccessToken 權限。

• 建立訂閱項目時，使用者必須擁有使用者自行管理的服務帳戶的 iam.serviceAccounts.actAs 權限。

建立訂閱項目時，請將使用者自行管理的服務帳戶指定為訂閱項目服務帳戶。

BigQuery 訂閱項目屬性

BigQuery 訂閱項目支援所有常見的訂閱項目屬性。以下各節說明 BigQuery 訂閱項目專屬的屬性。

使用主題結構定義

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

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

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

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

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

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

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

• 如果主題結構定義有 BigQuery 結構定義中沒有的其他欄位，且這些欄位可以捨棄，請選取「Drop unknown fields」(捨棄不明欄位) 選項。

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

如未選取「使用主題結構定義」或「使用資料表結構定義」選項，請確認 BigQuery 資料表有名為「data」的資料欄，且類型為 data、BYTES、STRING 或 JSON。Pub/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\"}"。如果訊息不含有效的 JSON，BigQuery 會拒絕接收。

• 系統支援下列 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。
  • 使用 string 轉換為 NUMERIC 或 BIGNUMERIC 時，Pub/Sub 會假設字串是使用者可讀取的數字 (例如 "123.124")。如果無法將字串處理為使用者可讀取的數字，Pub/Sub 會將字串視為以 BigDecimalByteStringEncoder 編碼的位元組。

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

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

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

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

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

寫入 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 資料表具有下表所述的欄位。

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

參數
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 資料表：

• 設定自訂服務帳戶，只有具備服務帳戶 iam.serviceAccounts.actAs 權限的使用者，才能建立可寫入資料表的訂閱項目。包含 iam.serviceAccounts.actAs 權限的角色範例為「服務帳戶使用者」 (roles/iam.serviceAccountUser) 角色。

• 使用預設的 Pub/Sub 服務代理，讓專案中任何有權建立訂閱項目的使用者，都能建立寫入資料表的訂閱項目。如未指定自訂服務帳戶，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 的資料欄。

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

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

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

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

9. 視需要設定常見的訂閱屬性。強烈建議您啟用無效信件功能，以便處理訊息失敗問題。詳情請參閱「無法傳送的訊息主題」。

10. 點選「建立」。

gcloud

1. 在 Google Cloud 控制台中啟用 Cloud Shell。

   啟用 Cloud Shell

   Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已設定適用於您目前專案的值。工作階段可能要幾秒鐘的時間才能初始化。

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 用戶端程式庫第 3 版。如果您仍在使用第 2 版程式庫，請參閱 第 3 版遷移指南。如要查看 Ruby v2 程式碼範例清單，請參閱 已淘汰的程式碼範例。

在試用這個範例之前，請先按照「快速入門導覽課程：使用用戶端程式庫」中的 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 訂閱項目問題。