创建推送订阅

本文档介绍如何创建推送订阅。您可以使用 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 服务会将 同一 Google Cloud 区域中的消息传送至 Pub/Sub 服务 存储消息所在的推送端点。Pub/Sub 服务会尽最大努力传送来自 同一 Google Cloud 区域的消息。

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

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

身份验证

启用身份验证 。启用后，Pub/Sub 传送给推送端点的消息会包含授权标头，以允许端点对请求进行身份验证。如果 App Engine 标准应用和 Cloud Run 函数端点托管在订阅所属的项目中，则可以使用自动身份验证和授权机制。

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

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

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

启用身份验证的前提条件

用户代管式服务账号是与推送订阅关联的服务帐号。 此账号用作生成的 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. 在端点网址 字段中，输入端点网址。

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

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

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

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

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

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

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

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

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

    1. 选中死信 复选框。

    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

   Google Cloud Cloud Shell 会话随即会在控制台的底部启动，并显示命令行提示符。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 库，请参阅 v2 迁移指南。 如需查看 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 库，请参阅 v3 迁移指南。 如需查看 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 的 Monitoring 文档。

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

后续步骤

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