建立 BigQuery 訂閱項目

資料表

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

   前往 BigQuery Studio

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

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

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

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

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

5. 按一下「新增主體」。

6. 在「新增主體」部分，輸入包含訂閱項目的專案的 Pub/Sub 服務代理名稱。服務代理的格式為 service-project-number@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。舉例來說，如果專案 ID 為 project-number=112233445566，服務代理人的格式為 service-112233445566@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。

7. 在「Select a role」(選取角色) 下拉式選單中輸入 BigQuery，然後選取「BigQuery Data Editor」(BigQuery 資料編輯者) 角色。

8. 按一下 [儲存]。

專案

1. 前往 Trusted Cloud 控制台的「IAM」頁面。

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

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

3. 在「新增主體」部分，輸入 Pub/Sub 服務代理程式的名稱。服務代理的格式為 service-project-number@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。舉例來說，如果專案 ID 為 project-number=112233445566，服務代理人的格式為 service-112233445566@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。

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

5. 在「Select a role」(選取角色) 下拉式選單中輸入 BigQuery，然後選取「BigQuery Data Editor」(BigQuery 資料編輯者) 角色。

6. 按一下 [儲存]。

服務帳戶

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

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

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

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

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

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

6. 在「新增主體」部分，輸入包含訂閱項目的專案的 Pub/Sub 服務代理程式名稱。服務專員的格式為 service-project-number@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。舉例來說，如果專案 ID 為 project-number=112233445566，服務代理人的格式為 service-112233445566@gcp-sa-pubsub.s3ns-system.iam.gserviceaccount.com。

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

8. 按一下 [儲存]。

專案

1. 前往 Trusted Cloud 控制台的「IAM」頁面。

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

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

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

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

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

6. 按一下 [儲存]。

主控台

1. 前往 Trusted Cloud 控制台的「Subscriptions」(訂閱項目) 頁面。

   前往「訂閱項目」頁面

2. 按一下「Create Subscription」 (建立訂閱項目)。

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

4. 從下拉式選單中選擇或建立主題。訂閱項目會接收來自主題的訊息。

5. 選取「Delivery type」(傳送類型)，然後選擇「Write to BigQuery」(寫入 BigQuery)。

6. 選取 BigQuery 資料表的專案。

7. 選取現有資料集或建立新資料集。 如要瞭解如何建立資料集，請參閱建立資料集。

8. 選取現有表格或建立新表格。 如要瞭解如何建立資料表，請參閱「建立資料表」。

9. 強烈建議您啟用「Dead lettering」來處理訊息傳送失敗的問題。詳情請參閱「無法傳送訊息的主題」。

10. 點選「建立」。

你也可以在「主題」頁面建立訂閱項目。 這個捷徑可將主題與訂閱項目建立關聯。

1. 前往 Trusted Cloud 控制台的「主題」頁面。

   前往「主題」

2. 在要建立訂閱的主題旁邊，按一下 more_vert。

3. 在內容選單中，選取「建立訂閱項目」。

4. 選取「Delivery type」(傳送類型)，然後選擇「Write to BigQuery」(寫入 BigQuery)。

5. 選取 BigQuery 資料表的專案。

6. 選取現有資料集或建立新資料集。 如要瞭解如何建立資料集，請參閱建立資料集。

7. 選取現有表格或建立新表格。 如要瞭解如何建立資料集，請參閱「建立資料表」。

8. 強烈建議您啟用「Dead lettering」來處理訊息傳送失敗的問題。詳情請參閱「無法傳送訊息的主題」。

9. 點選「建立」。

gcloud

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

   Activate Cloud Shell

   1. 如要建立 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}"