建立提取訂閱項目

本文說明如何建立提取訂閱項目。您可以使用 Google Cloud 控制台、Google Cloud CLI、用戶端程式庫或 Pub/Sub API 建立提取訂閱項目。

事前準備

• 瞭解訂閱項目。
• 評估貴商家是否需要提取訂閱項目。
• 瞭解提取訂閱項目的運作方式。

必要角色和權限

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

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

所需權限

如要建立提取訂閱項目，必須具備下列權限：

• pubsub.subscriptions.create 專案
• pubsub.topics.attachSubscription 這個主題

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

跨專案訂閱

如果您在一個專案中建立訂閱項目，訂閱另一個專案中的主題，則必須在建立訂閱項目的專案中具備 pubsub.subscriptions.create 權限，並在主題中具備 pubsub.topics.attachSubscription 權限。

建立提取訂閱項目

控制台

如要建立提取訂閱項目，請按照下列步驟操作：

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

   前往「訂閱項目」頁面

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

3. 在「Subscription ID」(訂閱 ID) 欄位中輸入名稱。

   如要瞭解如何命名訂閱項目，請參閱「主題或訂閱項目命名規範」。

4. 在「Pub/Sub topic」(Pub/Sub 主題) 清單中，選取訂閱項目要讀取的主題。

5. 在「傳送類型」中，選取「提取」。

6. 選用：在「轉換」部分，新增一或多個單一訊息轉換 (SMT)。詳情請參閱「使用 SMT 建立訂閱項目」。

7. 選用：在「篩選器」欄位中輸入篩選運算式，篩選訂閱項目中的訊息。詳情請參閱「篩選訂閱項目中的訊息」。

8. 在「重試政策」部分，選取所需選項。詳情請參閱「訂閱重試政策」。

9. 選用：啟用dead-letter 主題，接收無法傳送的訊息。

   1. 勾選「無效信件」核取方塊。

   2. 在「無效信件主題」清單中，選取或建立無效信件主題。

   3. 在「傳送嘗試次數上限」欄位中，輸入傳送嘗試次數上限。

10. 選用：在「傳送屬性」部分，啟用或停用下列傳送選項：

    • 僅傳送一次

    • 訊息排序

11. 選用步驟：在「Acknowledgement deadline」(確認期限) 部分，設定訂閱者處理及確認訊息的期限。詳情請參閱「使用租約管理功能延長確認時間」。

12. 選用步驟：在「Lifetime options」(保留期限選項) 部分，設定訂閱方案保留訊息的時間長度。

    1. 在「訊息保留時間」部分，指定未確認訊息的保留時間。

    2. 如要保留已確認和未確認訊息，請選取「保留已確認訊息」核取方塊。

    詳情請參閱「設定訂閱項目的訊息保留時間」。

13. 選用：在「到期時間」部分，選取下列任一選項：

    1. 如要設定訂閱到期日，請勾選「持續閒置達到指定天數即過期」核取方塊。輸入訂閱項目可保持閒置的天數，之後 Pub/Sub 會刪除訂閱項目。

    2. 如要停用訂閱到期功能，請選取「永不過期」核取方塊。

    詳情請參閱「訂閱到期」。

14. 點選「建立」。

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

1. 前往 Google Cloud 控制台的「Topics」(主題) 頁面。

   前往「主題」

2. 按一下要建立訂閱項目的主題旁邊的 。

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

4. 在「將訂閱項目新增至主題」頁面中，完成上一個程序說明的步驟。系統會自動填入主題 ID。

gcloud

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

   啟用 Cloud Shell

   控制台底部會開啟 Cloud Shell 工作階段，並顯示指令列提示。 Google Cloud Cloud Shell 是已安裝 Google Cloud CLI 的殼層環境，並已針對您目前的專案設定好相關值。工作階段可能要幾秒鐘的時間才能初始化。

2. 如要建立提取訂閱項目，請執行 gcloud pubsub subscriptions create 指令。

   gcloud pubsub subscriptions create SUBSCRIPTION_ID --topic=TOPIC_ID

   更改下列內容：

   • SUBSCRIPTION_ID：新提取訂閱項目的名稱或 ID。
   • TOPIC_ID：主題的名稱或 ID。

REST

如要建立提取訂閱項目，請使用 projects.subscriptions.create 方法：

要求：

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

PUT https://pubsub.googleapis.com/v1/projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID
Authorization: Bearer ACCESS_TOKEN

要求主體：

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

其中：

• PROJECT_ID 是您的專案 ID。
• SUBSCRIPTION_ID 是您的訂閱 ID。
• TOPIC_ID 是主題 ID。

回應：

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

C++

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

namespace pubsub_admin = ::google::cloud::pubsub_admin;
namespace pubsub = ::google::cloud::pubsub;
[](pubsub_admin::SubscriptionAdminClient client,
   std::string const& project_id, std::string const& topic_id,
   std::string const& subscription_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());
  auto sub = client.CreateSubscription(request);
  if (sub.status().code() == google::cloud::StatusCode::kAlreadyExists) {
    std::cout << "The subscription already exists\n";
    return;
  }
  if (!sub) 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;
using Grpc.Core;

public class CreateSubscriptionSample
{
    public Subscription CreateSubscription(string projectId, string topicId, string subscriptionId)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);

        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);
        Subscription subscription = null;

        try
        {
            subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig: null, ackDeadlineSeconds: 60);
        }
        catch (RpcException e) when (e.Status.StatusCode == StatusCode.AlreadyExists)
        {
            // Already exists.  That's fine.
        }
        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"
)

func create(w io.Writer, projectID, topic, subscription string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	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,
	})
	if err != nil {
		return fmt.Errorf("CreateSubscription: %w", err)
	}
	fmt.Fprintf(w, "Created subscription: %v\n", sub)
	return nil
}

Java

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

import com.google.cloud.pubsub.v1.SubscriptionAdminClient;
import com.google.pubsub.v1.PushConfig;
import com.google.pubsub.v1.Subscription;
import com.google.pubsub.v1.SubscriptionName;
import com.google.pubsub.v1.TopicName;
import java.io.IOException;

public class CreatePullSubscriptionExample {
  public static void main(String... args) throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String subscriptionId = "your-subscription-id";
    String topicId = "your-topic-id";

    createPullSubscriptionExample(projectId, subscriptionId, topicId);
  }

  public static void createPullSubscriptionExample(
      String projectId, String subscriptionId, String topicId) throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      // Create a pull subscription with default acknowledgement deadline of 10 seconds.
      // Messages not successfully acknowledged within 10 seconds will get resent by the server.
      Subscription subscription =
          subscriptionAdminClient.createSubscription(
              subscriptionName, topicName, PushConfig.getDefaultInstance(), 10);
      System.out.println("Created pull subscription: " + subscription.getName());
    }
  }
}

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';

// 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 createSubscription(topicNameOrId, subscriptionNameOrId) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  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';

// 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 createSubscription(
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  // Creates a new subscription
  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

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

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub subscription.
 *
 * @param string $projectId  The Google project ID.
 * @param string $topicName  The Pub/Sub topic name.
 * @param string $subscriptionName  The Pub/Sub subscription name.
 */
function create_subscription($projectId, $topicName, $subscriptionName)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create();

    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"

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)

# 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}
    )

print(f"Subscription created: {subscription}")

小茹

以下範例使用 Ruby Pub/Sub 用戶端程式庫 v3。如果您仍在使用 v2 程式庫，請參閱 v3 遷移指南。如要查看 Ruby v2 程式碼範例清單，請參閱 已淘汰的程式碼範例。

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

# topic_id        = "your-topic-id"
# subscription_id = "your-subscription-id"

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

subscription = subscription_admin.create_subscription \
  name: pubsub.subscription_path(subscription_id),
  topic: pubsub.topic_path(topic_id)

puts "Pull subscription #{subscription_id} created."

監控提取訂閱項目

Cloud Monitoring 提供多項指標，可監控訂閱項目。

如要查看所有可用的 Pub/Sub 相關指標及其說明，請參閱 Pub/Sub 的監控說明文件。

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

後續步驟

• 從提取訂閱項目接收訊息。
• 使用 gcloud 指令建立或修改訂閱項目。
• 使用 REST API 建立或修改訂閱項目。