创建推送订阅

本文档介绍了如何创建推送订阅。您可以使用Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 创建推送订阅。

准备工作

• 了解订阅。
• 了解推送订阅的工作原理。

所需的角色和权限

如需获得创建推送订阅所需的权限，请让您的管理员为您授予项目的 Pub/Sub Editor (roles/pubsub.editor) IAM 角色。 如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

此预定义角色包含创建推送订阅所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

创建推送订阅需要以下权限：

• 针对项目的 pubsub.subscriptions.create 权限
• pubsub.topics.attachSubscription 主题

您也可以使用自定义角色或其他预定义角色来获取这些权限。

跨项目订阅

如果您在一个项目中为另一个项目中的主题创建订阅，则必须对创建订阅的项目拥有 pubsub.subscriptions.create 权限，并且对相应主题拥有 pubsub.topics.attachSubscription 权限。

推送订阅属性

推送订阅支持所有通用订阅属性。以下各部分介绍了推送订阅特有的属性。

端点

端点网址（必需）。可公开访问的 HTTPS 地址。推送端点的服务器必须具有由证书授权机构签名的有效 SSL 证书。Pub/Sub 服务会将消息传送到 Pub/Sub 服务存储消息的同一 Google Cloud 区域中的推送端点。Pub/Sub 服务会尽最大努力传送来自同一 Google Cloud 区域的消息。

• 如果订阅者使用防火墙，则无法接收推送请求。如需接收推送请求，您必须关闭防火墙并验证请求中使用的 JSON Web 令牌 (JWT)。如果订阅者有防火墙，您可能会收到 403 permission denied 错误。

• Pub/Sub 不再要求证明对推送订阅网址网域的所有权。如果您的网域收到来自 Pub/Sub 的意外 POST 请求，您可以举报疑似滥用行为。

身份验证

启用身份验证。启用后，Pub/Sub 传递到推送端点的消息会包含授权标头，以允许端点对请求进行身份验证。自动身份验证和授权机制可用于托管在与订阅相同的项目中的 App Engine 标准和 Cloud Run functions 端点。

经过身份验证的推送订阅的身份验证配置包含用户代管式服务账号，以及在 create、patch 或 ModifyPushConfig 调用中指定的目标受众参数。您还必须向服务账号授予特定角色，详情请参见下一部分。

• 观众。一个不区分大小写的字符串，供 Webhook 用于验证此特定令牌的目标受众群体。

• 服务账号。Pub/Sub 会自动为您创建一个格式为 service-{PROJECT_NUMBER}@gcp-sa-pubsub. 的服务账号。

启用身份验证的前提条件

用户代管式服务账号是与推送订阅关联的服务账号。此账号用作生成的 JSON Web 令牌 (JWT) 的 email 声明。服务账号需满足以下要求：

• 此用户代管式服务必须与推送订阅位于同一项目中。

• 创建或修改推送订阅的主账号必须拥有用户管理的服务账号的 iam.serviceAccounts.actAs 权限，才能将该服务账号附加到推送订阅。如需了解详情，请参阅将服务账号关联到资源。

• 所需权限：必须向此服务账号授予 iam.serviceAccounts.getOpenIdToken 权限（包含在 roles/iam.serviceAccountTokenCreator 角色中），以允许 Pub/Sub 为指定服务账号创建 JWT 令牌，从而对推送请求进行身份验证。

载荷解封

启用载荷解封选项会从 Pub/Sub 消息中剥离除消息数据之外的所有消息元数据。通过载荷解封装，消息数据会直接作为 HTTP 正文传送。

您还可以启用写入元数据选项。写入元数据选项会将之前移除的消息元数据重新添加到请求标头中。

向专用 VPC 地址传送

Pub/Sub 在 VPC 网络外部运行，无法直接将消息推送到专用 VPC 地址。不过，您可以使用 Eventarc 将消息路由到 VPC 内的服务。Pub/Sub 可以将消息推送到 Eventarc 触发器，然后由该触发器将消息转发到 VPC 内的服务，例如 Cloud Run 服务或 Workflows 执行。如需了解详情，请参阅 Eventarc 文档。

VPC Service Controls

对于受 VPC Service Controls 保护的项目，请注意推送订阅的以下限制：

• 您只能创建推送端点设置为使用默认 run.app 网址的 Cloud Run 服务或 Workflows 执行的新推送订阅。自定义网域无法正常运作。

• 通过 Eventarc 将事件路由到推送端点设置为 Workflows 执行的 Workflows 目标时，您只能通过 Eventarc 创建新的推送订阅。

• 您无法更新现有的推送订阅。这些推送订阅会继续正常运行，但不受 VPC Service Controls 保护。

创建推送订阅

以下示例演示了如何使用提供的默认设置创建推送传送型订阅。

默认情况下，订阅使用拉取传送，除非您明确设置推送配置，如以下示例所示。

控制台

如需创建推送订阅，请按以下步骤操作：

1. 在 Google Cloud 控制台中，前往订阅页面。

   前往订阅页面

2. 点击创建订阅。

3. 在订阅 ID 字段中，输入一个名称。

   如需了解如何命名订阅，请参阅主题或订阅命名指南。

4. 在 Pub/Sub 主题列表中，选择订阅要从中读取的主题。

5. 对于传送类型，选择推送。

6. 在 Endpoint URL（端点网址）字段中，输入端点网址。

7. 可选：如需启用身份验证，请按以下步骤操作：

   1. 选择启用身份验证。
   2. 在服务账号列表中，选择要执行身份验证的服务账号。
   3. 可选：在受众字段中，输入受众群体。

   如需了解详情，请参阅推送订阅身份验证。

8. 可选：如需启用载荷解封，请选择启用载荷解封。

   如需在请求标头中保留消息元数据，请同时选择写入元数据。此选项还会为您的消息设置 Content-Type 标头。

9. 可选：在转换部分中，添加一个或多个单消息转换 (SMT)。如需了解详情，请参阅创建具有 SMT 的订阅。

10. 可选：在过滤表达式字段中，输入过滤表达式以过滤订阅中的消息。如需了解详情，请参阅过滤来自订阅的消息。

11. 在重试政策部分，选择一个选项。如需了解详情，请参阅订阅重试政策。

12. 可选：启用死信主题以接收无法传送的消息。

    1. 选中 Dead lettering 复选框。

    2. 在死信主题列表中，选择或创建死信主题。

    3. 在传送尝试次数上限字段中，输入传送尝试次数上限。

13. 可选：在投放属性部分，启用或停用以下投放选项：

    • “正好一次”传送

    • 消息排序

14. 可选：在确认截止时间部分，设置订阅者处理和确认消息的截止时间。如需了解详情，请参阅通过租约管理延长确认时间。

15. 可选：在生命周期选项部分，配置订阅保留消息的时长。

    1. 在消息保留时长部分中，指定未确认消息的保留时长。

    2. 如需保留已确认的消息以及未确认的消息，请选中保留已确认的消息复选框。

    如需了解详情，请参阅为订阅配置消息保留。

16. 可选：在过期期限部分，选择一个选项：

    1. 如需设置订阅到期时间，请选中在处于非活跃状态一定天数后过期复选框。输入订阅在被 Pub/Sub 删除之前可以保持非活跃状态的天数。

    2. 如需停用订阅到期，请选中永不过期复选框。

    如需了解详情，请参阅订阅过期。

17. 点击创建。

您还可以通过主题部分创建订阅。 此快捷方式可帮助您将主题与订阅关联。

1. 在 Google Cloud 控制台中，前往主题页面。

   打开“主题”。

2. 点击要创建订阅的主题旁边的 。

3. 从上下文菜单中，选择创建订阅。

4. 在为主题添加订阅页面中，完成上一个流程中所述的步骤。系统会自动填充主题 ID。

gcloud

1. 在 Google Cloud 控制台中，激活 Cloud Shell。

   激活 Cloud Shell

   Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动，并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。

2. 如需创建推送订阅，请运行 gcloud pubsub subscriptions create 命令。

   gcloud pubsub subscriptions create SUBSCRIPTION_ID \
   --topic=TOPIC_ID \
   --push-endpoint=PUSH_ENDPOINT

   替换以下内容：

   • SUBSCRIPTION_ID：新推送订阅的名称或 ID。
   • TOPIC_ID：主题的名称或 ID。
   • PUSH_ENDPOINT：用作相应订阅的端点的网址。 例如 https://myproject.appspot.com/myhandler。

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",
// Only needed if you are using push delivery
"pushConfig": {
"pushEndpoint": "PUSH_ENDPOINT"
}
}

其中：

PROJECT_ID 是项目 ID。

SUBSCRIPTION_ID 是您的订阅 ID。

TOPIC_ID 是主题 ID。

PUSH_ENDPOINT 是用作端点的网址。例如 https://myproject.appspot.com/myhandler。

回答：

{
"name": "projects/PROJECT_ID/subscriptions/SUBSCRIPTION_ID",
"topic": "projects/PROJECT_ID/topics/TOPIC_ID",
"pushConfig": {
"pushEndpoint": "https://PROJECT_ID.appspot.com/myhandler",
"attributes": {
  "x-goog-version": "v1"
}
},
"ackDeadlineSeconds": 10,
"messageRetentionDuration": "604800s",
"expirationPolicy": {
"ttl": "2678400s"
}
}

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& endpoint) {
  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_push_config()->set_push_endpoint(endpoint);
  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;

public class CreatePushSubscriptionSample
{
    public Subscription CreatePushSubscription(string projectId, string topicId, string subscriptionId, string pushEndpoint)
    {
        SubscriberServiceApiClient subscriber = SubscriberServiceApiClient.Create();
        TopicName topicName = TopicName.FromProjectTopic(projectId, topicId);
        SubscriptionName subscriptionName = SubscriptionName.FromProjectSubscription(projectId, subscriptionId);

        PushConfig pushConfig = new PushConfig { PushEndpoint = pushEndpoint };

        // The approximate amount of time in seconds (on a best-effort basis) Pub/Sub waits for the
        // subscriber to acknowledge receipt before resending the message.
        var ackDeadlineSeconds = 60;
        var subscription = subscriber.CreateSubscription(subscriptionName, topicName, pushConfig, ackDeadlineSeconds);
        return subscription;
    }
}

Go

以下示例使用 Go Pub/Sub 客户端库的主要版本 (v2)。如果您仍在使用 v1 库，请参阅迁移指南。如需查看 v1 代码示例列表，请参阅 已弃用的代码示例。

在尝试此示例之前，请按照快速入门：使用客户端库中的 Go 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Go API 参考文档。

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/pubsub/v2"
	"cloud.google.com/go/pubsub/v2/apiv1/pubsubpb"
)

func createWithEndpoint(w io.Writer, projectID, topic, subscription, endpoint string) error {
	// projectID := "my-project-id"
	// topic := "projects/my-project-id/topics/my-topic"
	// subscription := "projects/my-project/subscriptions/my-sub"
	// endpoint := "https://my-test-project.appspot.com/push"
	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,
		AckDeadlineSeconds: 10,
		PushConfig:         &pubsubpb.PushConfig{PushEndpoint: endpoint},
	})
	if err != nil {
		return fmt.Errorf("failed to create push sub: %w", err)
	}
	fmt.Fprintf(w, "Created push 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 CreatePushSubscriptionExample {
  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";
    String pushEndpoint = "https://my-test-project.appspot.com/push";

    createPushSubscriptionExample(projectId, subscriptionId, topicId, pushEndpoint);
  }

  public static void createPushSubscriptionExample(
      String projectId, String subscriptionId, String topicId, String pushEndpoint)
      throws IOException {
    try (SubscriptionAdminClient subscriptionAdminClient = SubscriptionAdminClient.create()) {
      TopicName topicName = TopicName.of(projectId, topicId);
      SubscriptionName subscriptionName = SubscriptionName.of(projectId, subscriptionId);
      PushConfig pushConfig = PushConfig.newBuilder().setPushEndpoint(pushEndpoint).build();

      // Create a push 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, 10);
      System.out.println("Created push subscription: " + subscription.getName());
    }
  }
}

Node.js

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 Node.js 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Node.js API 参考文档。

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const pushEndpoint = 'YOUR_ENDPOINT_URL';
// 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 createPushSubscription(
  pushEndpoint,
  topicNameOrId,
  subscriptionNameOrId,
) {
  const options = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  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 pushEndpoint = 'YOUR_ENDPOINT_URL';
// const topicNameOrId = 'YOUR_TOPIC_NAME_OR_ID';
// const subscriptionNameOrId = 'YOUR_SUBSCRIPTION_NAME_OR_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 createPushSubscription(
  pushEndpoint: string,
  topicNameOrId: string,
  subscriptionNameOrId: string,
) {
  const options: CreateSubscriptionOptions = {
    pushConfig: {
      // Set to an HTTPS endpoint of your choice. If necessary, register
      // (authorize) the domain on which the server is hosted.
      pushEndpoint,
    },
  };

  await pubSubClient
    .topic(topicNameOrId)
    .createSubscription(subscriptionNameOrId, options);
  console.log(`Subscription ${subscriptionNameOrId} created.`);
}

PHP

在尝试此示例之前，请按照《快速入门：使用客户端库》中的 PHP 设置说明进行操作。如需了解详情，请参阅 Pub/Sub PHP API 参考文档。

use Google\Cloud\PubSub\PubSubClient;

/**
 * Creates a Pub/Sub push 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 $endpoint  The endpoint for the push subscription.
 */
function create_push_subscription($projectId, $topicName, $subscriptionName, $endpoint)
{
    $pubsub = new PubSubClient([
        'projectId' => $projectId,
    ]);
    $topic = $pubsub->topic($topicName);
    $subscription = $topic->subscription($subscriptionName);
    $subscription->create([
        'pushConfig' => ['pushEndpoint' => $endpoint]
    ]);

    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"
# endpoint = "https://my-test-project.appspot.com/push"

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)

push_config = pubsub_v1.types.PushConfig(push_endpoint=endpoint)

# 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,
            "push_config": push_config,
        }
    )

print(f"Push subscription created: {subscription}.")
print(f"Endpoint for subscription is: {endpoint}")

Ruby

以下示例使用 Ruby Pub/Sub 客户端库 v3。如果您仍在使用 v2 库，请参阅 迁移指南。如需查看 Ruby v2 代码示例列表，请参阅 已弃用的代码示例。

试用此示例之前，请按照快速入门：使用客户端库中的 Ruby 设置说明进行操作。如需了解详情，请参阅 Pub/Sub Ruby API 参考文档。

# topic_id          = "your-topic-id"
# subscription_id   = "your-subscription-id"
# endpoint          = "https://your-test-project.appspot.com/push"

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),
  push_config: {
    push_endpoint: endpoint
  }

puts "Push subscription #{subscription_id} created."

监控推送订阅

Cloud Monitoring 提供了许多指标来监控订阅。

如需查看与 Pub/Sub 相关的所有可用指标及其说明的列表，请参阅 Pub/Sub 监控文档。

您还可以在 Pub/Sub 中监控订阅。

后续步骤

• 使用 gcloud 命令创建或修改订阅。
• 使用 REST API 创建或修改订阅。