建立 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 服務代理 (service-PROJECT_NUMBER@gcp-sa-pubsub.)。

如要啟用 Pub/Sub 寫入 BigQuery 資料表的功能，服務帳戶必須具備 BigQuery 資料編輯者 (roles/bigquery.dataEditor) 角色。您可以授予服務帳戶專案或資料表的權限，如下所示：

專案

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

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

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

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

4. 按一下「Add another role」(新增其他角色)，然後選取「BigQuery Data Editor」(BigQuery 資料編輯者) 角色。

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

資料表

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

   前往 BigQuery Studio

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

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

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

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

   service-PROJECT_NUMBER@gcp-sa-pubsub.。

6. 在「Assign roles」(指派角色) 清單中，選取「BigQuery Data Editor」(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 資料表的對應資料欄。

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

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

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

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

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

• 如果 BigQuery 欄位未出現在主題結構定義中，這些 BigQuery 欄位必須採用 NULLABLE 模式。

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

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

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

Pub/Sub 主題結構定義或 BigQuery 資料表結構定義的變更，可能不會立即反映在寫入 BigQuery 資料表的訊息中。舉例來說，如果啟用「Drop unknown fields」(捨棄不明欄位) 選項，且 Pub/Sub 結構定義中有某個欄位，但 BigQuery 結構定義中沒有，則將該欄位新增至 BigQuery 結構定義後，寫入 BigQuery 資料表的訊息可能仍不含該欄位。最終，結構定義會同步，後續訊息也會包含該欄位。

如果對 BigQuery 訂閱項目使用「Use topic schema」(使用主題結構定義) 選項，您也可以使用 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 結構定義中不存在的額外欄位，且這些欄位可以捨棄，請選取「Drop unknown fields」(捨棄不明欄位) 選項。

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

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

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

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

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

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

捨棄不明欄位

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

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

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

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

寫入中繼資料

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

如果選取「Write metadata」(寫入中繼資料) 選項，請確認 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 資料表未選取「Use topic schema」(使用主題結構定義) 或「Use table schema」(使用資料表結構定義)，則必須提供 data 欄位。如果欄位類型為 JSON，則訊息內文必須是有效的 JSON。
attributes	STRING 或 JSON 包含所有訊息屬性的 JSON 物件。此外，其中也包含 Pub/Sub 訊息的其他欄位，包括排序鍵 (如有)。

服務帳戶

您可以透過下列選項，將訊息寫入 BigQuery 資料表：

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

• 使用預設的 Pub/Sub 服務代理，讓任何有權在專案中建立訂閱項目的使用者，都能建立寫入資料表的訂閱項目。如未指定自訂服務帳戶，Pub/Sub 服務代理會是預設設定。

建立 BigQuery 訂閱項目

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

控制台

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

   前往「訂閱項目」頁面

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

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

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

5. 選取 BigQuery 資料表：

   1. 在「Project」(專案) 部分，選取包含 BigQuery 資料表的 Google Cloud 專案。

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

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

6. 在「Schema Configuration」(結構定義設定) 中，選取下列其中一個選項：

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

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

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

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

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

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 的 Monitoring 說明文件。

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

後續步驟

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