建立主題

在 Pub/Sub 中,主題是代表訊息動態的具名資源。您必須先建立主題,才能發布或訂閱該主題。Pub/Sub 支援兩種主題:標準主題和匯入主題。

本文說明如何建立 Pub/Sub 標準主題。如要進一步瞭解匯入主題和建立方式,請參閱「關於匯入主題」。

如要建立主題,您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API。

事前準備

必要角色和權限

如要取得建立主題所需的權限,請要求管理員為您授予專案的 Pub/Sub 編輯者(roles/pubsub.editor) 身分與存取權管理角色。如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和機構的存取權」。

這個預先定義的角色具備建立主題所需的權限。如要查看確切的必要權限,請展開「必要權限」部分:

所需權限

您必須具備下列權限,才能建立主題:

  • 授予此權限,即可在專案中建立主題: pubsub.topics.create

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

您可以在專案層級和個別資源層級設定存取權控管。您可以在一個專案中建立訂閱項目,然後將其附加至位於其他專案的主題。請確認您具備每個專案的必要權限。

主題的屬性

建立或更新主題時,請務必指定其屬性。

新增預設訂閱項目

為 Pub/Sub 主題新增預設訂閱項目。主題建立後,您可以為該主題建立其他訂閱項目。預設訂閱項目具有下列屬性:

  • -sub 的訂閱項目 ID
  • 提取傳送類型
  • 訊息保留時間為七天
  • 持續處於非活躍狀態達 31 天即失效
  • 確認期限為 10 秒
  • 立即重試政策

使用結構定義

結構定義是訊息資料欄位必須遵循的格式。發布者和訂閱者之間的契約,由 Pub/Sub 強制執行。主題結構定義有助於將訊息類型和權限標準化,讓機構中的不同團隊都能使用這些訊息。Pub/Sub 會為訊息類型和權限建立中央授權機構。如要使用結構定義建立主題,請參閱「結構定義總覽」。

啟用擷取功能

啟用這項屬性後,您就能將來自外部來源的串流資料擷取至主題,以便使用 Google Cloud的功能。如要建立匯入主題以供攝取,請參閱以下說明:

啟用訊息保留功能

指定 Pub/Sub 主題在發布後保留訊息的時間長度。訊息保留期限結束後,Pub/Sub 可能會棄用訊息,不論其確認狀態為何。系統會儲存已發布至主題的所有訊息,因此會產生訊息儲存費用。

  • 預設值 = 未啟用
  • 最小值 = 10 分鐘
  • 最大值 = 31 天

將訊息資料匯出至 BigQuery

啟用這個屬性後,您就能建立 BigQuery 訂閱項目,在收到訊息時將訊息寫入現有的 BigQuery 資料表。您不需要設定單獨的訂閱者用戶端。如要進一步瞭解 BigQuery 訂閱項目,請參閱「BigQuery 訂閱項目」。

將訊息資料備份至 Cloud Storage

啟用此屬性後,您就能建立 Cloud Storage 訂閱項目,在收到訊息時將訊息寫入現有的 Cloud Storage 資料表。您不需要設定單獨的訂閱者用戶端。如要進一步瞭解 Cloud Storage 訂閱項目,請參閱「Cloud Storage 訂閱項目」。

轉換

主題 SMT 可讓您直接在 Pub/Sub 中輕鬆修改訊息資料和屬性。這項功能可在訊息發布至主題前,執行資料清理、篩選或格式轉換作業。

如要進一步瞭解 SMT,請參閱 SMT 總覽

Google-owned and Google-managed encryption key

指出主題是使用Google-owned and Google-managed encryption keys加密。根據預設,Pub/Sub 會使用 Google-owned and Google-managed encryption keys 加密訊息,因此選擇這個選項可維持預設行為。Google 會自動處理金鑰管理和輪替作業,確保您的訊息一律採用最強的加密機制。這個選項不需要進一步設定。如要進一步瞭解 Google-owned and Google-managed encryption keys,請參閱「使用 Google-owned and Google-managed encryption keys進行預設加密」一文。

Cloud KMS 金鑰

指定主題是否使用客戶管理式加密金鑰 (CMEK) 進行加密。根據預設,Pub/Sub 會使用 Google-owned and Google-managed encryption keys 加密訊息。如果您指定這個選項,Pub/Sub 會搭配 CMEK 使用信封加密模式。在這種做法中,Cloud KMS 不會加密訊息。而是由 Cloud KMS 加密 Pub/Sub 為每個主題建立的資料加密金鑰 (DEK)。Pub/Sub 會使用為主題產生的最新 DEK 加密訊息。Pub/Sub 會在將訊息傳送給訂閱者之前,先將訊息解密。如要進一步瞭解如何建立金鑰,請參閱「設定訊息加密功能」。

建立主題

您必須先建立主題,才能發布或訂閱該主題。

控制台

如要建立主題,請按照下列步驟操作:

  1. 在 Google Cloud 控制台中,前往 Pub/Sub 的「Create topic」(建立主題) 頁面。

    前往「建立主題」

  2. 在「主題 ID」欄位中輸入主題 ID,如要進一步瞭解主題命名方式,請參閱命名規範

  3. 保留「Add a default subscription」(新增預設訂閱) 選項。

  4. (非必要) 請勿選取其他選項。

  5. 按一下「建立主題」

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. 如要建立主題,請執行 gcloud pubsub topics create 指令:

    gcloud pubsub topics create TOPIC_ID

REST

如要建立主題,請使用 projects.topics.create 方法:

要求必須透過 Authorization 標頭中的存取權權杖進行驗證。如要取得目前應用程式預設憑證的存取權杖:gcloud auth application-default print-access-token

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/topics/TOPIC_ID
Authorization: Bearer ACCESS_TOKEN
    

其中:

  • PROJECT_ID 是您的專案 ID。
  • TOPIC_ID 是主題 ID。
  • 回應:

    {
     "name": "projects/PROJECT_ID/topics/TOPIC_ID"
    }

    C++

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 C++。詳情請參閱 Pub/Sub C++ API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    namespace pubsub = ::google::cloud::pubsub;
    namespace pubsub_admin = ::google::cloud::pubsub_admin;
    [](pubsub_admin::TopicAdminClient client, std::string project_id,
       std::string topic_id) {
      auto topic = client.CreateTopic(
          pubsub::Topic(std::move(project_id), std::move(topic_id)).FullName());
      // Note that kAlreadyExists is a possible error when the library retries.
      if (topic.status().code() == google::cloud::StatusCode::kAlreadyExists) {
        std::cout << "The topic already exists\n";
        return;
      }
      if (!topic) throw std::move(topic).status();
    
      std::cout << "The topic was successfully created: " << topic->DebugString()
                << "\n";
    }

    C#

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 C#。詳情請參閱 Pub/Sub C# API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    
    using Google.Cloud.PubSub.V1;
    using Grpc.Core;
    using System;
    
    public class CreateTopicSample
    {
        public Topic CreateTopic(string projectId, string topicId)
        {
            PublisherServiceApiClient publisher = PublisherServiceApiClient.Create();
            var topicName = TopicName.FromProjectTopic(projectId, topicId);
            Topic topic = null;
    
            try
            {
                topic = publisher.CreateTopic(topicName);
                Console.WriteLine($"Topic {topic.Name} created.");
            }
            catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
            {
                Console.WriteLine($"Topic {topicName} already exists.");
            }
            return topic;
        }
    }

    Go

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Go。詳情請參閱 Pub/Sub Go API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    import (
    	"context"
    	"fmt"
    	"io"
    
    	"cloud.google.com/go/pubsub"
    )
    
    func create(w io.Writer, projectID, topicID string) error {
    	// projectID := "my-project-id"
    	// topicID := "my-topic"
    	ctx := context.Background()
    	client, err := pubsub.NewClient(ctx, projectID)
    	if err != nil {
    		return fmt.Errorf("pubsub.NewClient: %w", err)
    	}
    	defer client.Close()
    
    	t, err := client.CreateTopic(ctx, topicID)
    	if err != nil {
    		return fmt.Errorf("CreateTopic: %w", err)
    	}
    	fmt.Fprintf(w, "Topic created: %v\n", t)
    	return nil
    }
    

    Java

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Java。詳情請參閱 Pub/Sub Java API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    
    import com.google.cloud.pubsub.v1.TopicAdminClient;
    import com.google.pubsub.v1.Topic;
    import com.google.pubsub.v1.TopicName;
    import java.io.IOException;
    
    public class CreateTopicExample {
      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";
    
        createTopicExample(projectId, topicId);
      }
    
      public static void createTopicExample(String projectId, String topicId) throws IOException {
        try (TopicAdminClient topicAdminClient = TopicAdminClient.create()) {
          TopicName topicName = TopicName.of(projectId, topicId);
          Topic topic = topicAdminClient.createTopic(topicName);
          System.out.println("Created topic: " + topic.getName());
        }
      }
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_NAME_OR_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 createTopic(topicNameOrId) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    Node.js

    /**
     * TODO(developer): Uncomment this variable before running the sample.
     */
    // const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
    
    // Imports the Google Cloud client library
    import {PubSub} from '@google-cloud/pubsub';
    
    // Creates a client; cache this for further use
    const pubSubClient = new PubSub();
    
    async function createTopic(topicNameOrId: string) {
      // Creates a new topic
      await pubSubClient.createTopic(topicNameOrId);
      console.log(`Topic ${topicNameOrId} created.`);
    }

    PHP

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 PHP。詳情請參閱 Pub/Sub PHP API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    use Google\Cloud\PubSub\PubSubClient;
    
    /**
     * Creates a Pub/Sub topic.
     *
     * @param string $projectId  The Google project ID.
     * @param string $topicName  The Pub/Sub topic name.
     */
    function create_topic($projectId, $topicName)
    {
        $pubsub = new PubSubClient([
            'projectId' => $projectId,
        ]);
        $topic = $pubsub->createTopic($topicName);
    
        printf('Topic created: %s' . PHP_EOL, $topic->name());
    }

    Python

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Python。詳情請參閱 Pub/Sub Python API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    from google.cloud import pubsub_v1
    
    # TODO(developer)
    # project_id = "your-project-id"
    # topic_id = "your-topic-id"
    
    publisher = pubsub_v1.PublisherClient()
    topic_path = publisher.topic_path(project_id, topic_id)
    
    topic = publisher.create_topic(request={"name": topic_path})
    
    print(f"Created topic: {topic.name}")

    Ruby

    在嘗試這個範例之前,請先按照 Pub/Sub 快速入門:使用用戶端程式庫中的操作說明設定 Ruby。詳情請參閱 Pub/Sub Ruby API 參考說明文件

    如要向 Pub/Sub 進行驗證,請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

    # topic_id = "your-topic-id"
    
    pubsub = Google::Cloud::Pubsub.new
    
    topic = pubsub.create_topic topic_id
    
    puts "Topic #{topic.name} created."

    機構政策限制

    機構政策可以限制主題建立作業,例如,政策可以限制 Compute Engine 區域中的訊息儲存空間。為避免建立主題時發生錯誤,請在建立主題前檢查並視需要更新組織政策。

    如果您是新建立專案,請稍候幾分鐘,等機構政策初始化後再建立主題。

    前往「Organization Policies」(機構政策)

    詳情請參閱「設定訊息儲存空間政策」。

    後續步驟

    Apache Kafka® 是 Apache 軟體基金會 (Apache Software Foundation) 或其關聯企業在美國與/或其他國家/地區的註冊商標。