Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

建立主題

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

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

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

事前準備

瞭解 Pub/Sub 服務及其術語。
瞭解發布程序。

必要角色和權限

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

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

所需權限

如要建立主題，您必須具備下列權限：

授予這項權限，即可在專案中建立主題： pubsub.topics.create

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

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

主題的屬性

建立或更新主題時，必須指定主題的屬性。

新增預設訂閱項目

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

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

使用結構定義

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

啟用擷取功能

啟用這項屬性後，您就能將外部來源的串流資料擷取至主題，以便使用 Google Cloud的功能。如要建立匯入主題以供擷取，請參閱下列內容：

啟用主題訊息保留功能

根據預設，Pub/Sub 主題會在訊息獲得主題所連結的所有訂閱項目確認後，立即捨棄訊息。您也可以選擇設定主題，將訊息保留最多 31 天，最短保留期限為 10 分鐘。

訊息保留功能可讓訂閱項目重播先前確認的訊息，或重播您建立訂閱項目之前發布的訊息。詳情請參閱「使用搜尋功能重播及清除訊息」。

系統會將主題保留訊息的儲存費用計入主題的專案。訊息保留期限過後，Pub/Sub 可能會捨棄訊息，不論訊息的確認狀態為何。

如要查看保留訊息的指標，請使用下列 Cloud Monitoring 指標：

topic/num_retained_messages：保留的訊息數量
topic/oldest_retained_message_age：保留最久的訊息存在時間
topic/retained_bytes：保留訊息的總大小 (以位元組為單位)

將訊息資料匯出至 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 會在訊息傳送給訂閱端不久前解密訊息。如要進一步瞭解如何建立金鑰，請參閱「設定訊息加密」。

建立主題

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

控制台

如要建立主題，請按照下列步驟操作：

前往 Google Cloud 控制台的 Pub/Sub「建立主題」頁面。

前往「建立主題」
在「主題 ID」欄位中，輸入主題 ID。如要進一步瞭解如何命名主題，請參閱命名規範。
如要為主題建立預設訂閱，請選取「新增預設訂閱」。這個選項預設為啟用。
選用。如要搭配主題使用結構定義，請按一下「使用結構定義」並提供結構定義。詳情請參閱「建立主題時建立及關聯結構定義」。
如果是標準主題，請取消選取「啟用擷取」。
選用。如要在發布訊息後保留訊息，請選取「啟用訊息保留功能」。以天、小時和分鐘為單位選取保留期限。詳情請參閱「啟用訊息保留功能」。
選用。如要將已發布的訊息匯出至 BigQuery 資料表，請選取「將資料匯出至 BigQuery」，然後輸入資料表的詳細資料。詳情請參閱「建立 BigQuery 訂閱項目」。
選用。如要將已發布的訊息備份至 Cloud Storage 值區，請選取「將訊息資料備份至 Cloud Storage」，然後輸入 Cloud Storage 值區的詳細資料。詳情請參閱「建立 Cloud Storage 訂閱方案」。
選用。在「轉換」下方，新增一或多個單一訊息轉換 (SMT)，即可操控及篩選訊息資料。詳情請參閱「建立含有 SMT 的主題」。
選用。如要使用客戶自行管理的加密金鑰 (CMEK) 加密訊息，請選取「Cloud KMS key」。根據預設，Pub/Sub 會使用 Google 預設加密機制，因此不需要 CMEK。詳情請參閱「設定訊息加密」。
選用。如要管理與主題相關聯的金鑰，請按一下「管理金鑰」。詳情請參閱「標記總覽」。
按一下「建立主題」。

gcloud

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

啟用 Cloud Shell

控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。 Google Cloud Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。
如要建立主題，請執行 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++

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

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#

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


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

以下範例使用 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"
)

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()

	topic := &pubsubpb.Topic{
		Name: fmt.Sprintf("projects/%s/topics/%s", projectID, topicID),
	}
	t, err := client.TopicAdminClient.CreateTopic(ctx, topic)
	if err != nil {
		return fmt.Errorf("CreateTopic: %w", err)
	}
	fmt.Fprintf(w, "Topic created: %v\n", t)
	return nil
}

Java

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


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

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

/**
 * 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.ts

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

/**
 * 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

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

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

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

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

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

# topic_id = "your-topic-id"

pubsub = Google::Cloud::PubSub.new
topic_admin = pubsub.topic_admin

topic = topic_admin.create_topic name: pubsub.topic_path(topic_id)

puts "Topic #{topic.name} created."

組織政策限制

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

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

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

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

後續步驟

為主題選擇訂閱類型。
瞭解如何將訊息發布至主題。
排解主題問題。
使用 gcloud CLI、REST API 或用戶端程式庫建立或修改主題。

Apache Kafka® 是 The Apache Software Foundation 或其關聯企業在美國與/或其他國家/地區的註冊商標。

建立主題 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要角色和權限

所需權限

主題的屬性

新增預設訂閱項目

使用結構定義

啟用擷取功能

啟用主題訊息保留功能

將訊息資料匯出至 BigQuery

將訊息資料備份至 Cloud Storage

轉換作業

Google-owned and Google-managed encryption key

Cloud KMS 金鑰

建立主題

控制台

gcloud

REST

C++

C#

Go

Java

Node.js

Node.ts

PHP

Python

小茹

組織政策限制

後續步驟

建立主題