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

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

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

主題的屬性

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

新增預設訂閱項目

Adds a default subscription to the Pub/Sub topic. 主題建立後，您可以為該主題建立其他訂閱項目。預設訂閱項目具有下列屬性：

「-sub」的訂閱 ID
提取傳送類型
訊息保留時間為 7 天
持續處於非活躍狀態達 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 bucket，請選取「將訊息資料備份至 Cloud Storage」，然後輸入 Cloud Storage bucket 的詳細資料。詳情請參閱「建立 Cloud Storage 訂閱項目」。
選用。在「轉換」下方，新增一或多個單一訊息轉換 (SMT)，即可操控及篩選訊息資料。詳情請參閱「使用 SMT 建立主題」。
選用。如要使用客戶自行管理的加密金鑰 (CMEK) 加密訊息，請選取「Cloud KMS key」(Cloud KMS 金鑰)。根據預設，Pub/Sub 會使用 Google 預設加密機制，不需要 CMEK。詳情請參閱「設定訊息加密」。
選用。如要管理與主題相關聯的鍵，請按一下「管理鍵」。詳情請參閱「標記總覽」。
按一下「建立主題」。

gcloud

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

啟用 Cloud Shell

Google Cloud 控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。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 用戶端程式庫第 3 版。如果您仍在使用第 2 版程式庫，請參閱第 3 版遷移指南。如要查看 Ruby 第 2 版程式碼範例清單，請參閱已淘汰的程式碼範例。

在試用這個範例之前，請先按照「快速入門導覽課程：使用用戶端程式庫」中的 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."

Rust

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

use google_cloud_pubsub::client::TopicAdmin;

pub async fn sample(client: &TopicAdmin, project_id: &str, topic_id: &str) -> anyhow::Result<()> {
    let topic = client
        .create_topic()
        .set_name(format!("projects/{project_id}/topics/{topic_id}"))
        .send()
        .await?;

    println!("successfully created topic {topic:?}");
    Ok(())
}

組織政策限制

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

如果專案是新建立的，請先等待幾分鐘，讓組織政策初始化，再建立主題。

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

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

後續步驟

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

Apache Kafka® 是 Apache 軟體基金會 (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

小茹

Rust

組織政策限制

後續步驟

建立主題