建立 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 服務帳戶的資料列，然後按一下 「編輯主體」。

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

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

資料表

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

   前往 BigQuery Studio

2. 在標示為「依名稱和標籤篩選」的「Explorer」窗格搜尋方塊中，輸入資料表名稱並按下 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 結構定義中沒有的額外欄位，且這些欄位可以捨棄，請選取「捨棄不明欄位」選項。

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

如未選取「使用主題結構定義」或「使用資料表結構定義」選項，請確認 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 資料表：

• 設定自訂服務帳戶，只有具備服務帳戶 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」data的資料欄。

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

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

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

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

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

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 用戶端程式庫 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 訂閱項目問題。