本文档介绍了如何创建推送订阅。您可以使用 Google Cloud 控制台、Google Cloud CLI、客户端库或 Pub/Sub API 来创建推送订阅。
准备工作
所需的角色和权限
如需创建订阅,您必须在项目级别配置访问权限控制。如果您的订阅和主题位于不同的项目中,则还需要资源级权限,如本部分稍后所述。
如需获取创建推送订阅所需的权限,请让管理员向您授予项目的 Pub/Sub Editor (roles/pubsub.editor
) IAM 角色。如需详细了解如何授予角色,请参阅管理访问权限。
此预定义角色包含创建推送订阅所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
创建推送订阅需要以下权限:
-
创建订阅:
pubsub.subscriptions.create
-
删除订阅:
pubsub.subscriptions.delete
-
获取订阅:
pubsub.subscriptions.get
-
列出订阅:
pubsub.subscriptions.list
-
更新订阅:
pubsub.subscriptions.update
-
为主题附加订阅:
pubsub.topics.attachSubscription
-
获取订阅的 IAM 政策:
pubsub.subscriptions.getIamPolicy
-
为订阅配置 IAM 政策:
pubsub.subscriptions.setIamPolicy
如果您需要在一个项目中创建与另一个项目中的主题关联的推送订阅,请让您的主题管理员还针对该主题授予您 Pub/Sub Editor (roles/pubsub.editor)
IAM 角色。
推送订阅属性
配置推送订阅时,您可以指定以下属性。
通用属性
了解可在所有订阅中设置的常见订阅属性。
端点
端点网址(必填)。可公开访问的 HTTPS 地址。推送端点的服务器必须具有由证书授权机构签名的有效 SSL 证书。Pub/Sub 服务会将同一 Google Cloud 地区中的消息传送至 Pub/Sub 服务存储消息所在的推送端点。Pub/Sub 服务会尽最大努力传送来自同一 Google Cloud 地区的消息。
Pub/Sub 不再要求为推送订阅网址网域提供所有权证明。如果您的网域收到来自 Pub/Sub 的意外 POST 请求,您可以举报疑似滥用行为。
身份验证
启用身份验证。启用后,Pub/Sub 传送到推送端点的消息会包含授权标头,以允许端点对请求进行身份验证。自动身份验证和授权机制适用于托管在订阅所属项目中的 App Engine 标准环境和 Cloud Functions 端点。
经过身份验证的推送订阅的身份验证配置由用户代管式服务帐号以及在 create、patch 或 ModifyPushConfig 调用中指定的目标设备参数组成。您还必须向服务代理授予特定角色,如下一部分所述。
代管式服务帐号(必需)。与推送订阅关联的服务帐号。此帐号将用作生成的 JSON Web 令牌 (JWT) 的
email
声明。下面列出了服务帐号的要求:此服务帐号必须与推送订阅位于同一项目中。
创建或修改推送订阅的主账号必须具有该服务帐号的
iam.serviceAccounts.actAs
权限。您可以针对项目、文件夹或组织授予具有此权限的角色,以允许调用方模拟多个服务帐号,或授予针对服务帐号具有此权限的角色,以允许调用方仅模拟此服务帐号。
受众群体:一个不区分大小写的字符串,网络钩子用于验证此特定令牌的目标受众群体。
服务代理(必需)。
Pub/Sub 会自动为您创建
service-{PROJECT_NUMBER}@gcp-sa-pubsub.iam.gserviceaccount.com
格式的服务帐号。必须为此服务代理授予
iam.serviceAccounts.getOpenIdToken
权限(包含在roles/iam.serviceAccountTokenCreator
角色中),以允许 Pub/Sub 为经过身份验证的推送请求创建 JWT 令牌。
载荷解封
启用载荷解封选项会剥离除消息数据之外的所有消息元数据的 Pub/Sub 消息。使用载荷解封功能时,消息数据将作为 HTTP 正文直接传送。
- 写入元数据。将之前移除的消息元数据添加回请求标头。
VPC Service Controls
对于受 VPC Service Controls 保护的项目,请注意推送订阅存在以下限制:
您只能创建新的推送订阅,其推送端点设置为具有默认
run.app
网址或 Workflows 执行的 Cloud Run 服务。自定义网域不起作用。通过 Eventarc 将事件路由到推送端点设置为 Workflows 执行的 Workflows 目的地时,您只能通过 Eventarc 创建新的推送订阅。
您无法更新现有推送订阅。尽管这些推送订阅不受 VPC Service Controls 保护,但仍将继续运行。
创建推送订阅
以下示例演示了如何使用提供的默认设置创建采用推送传送的订阅。
默认情况下,订阅使用拉取传送,除非您明确设置了推送配置,如以下示例所示。
控制台
如需创建推送订阅,请完成以下步骤:
- 在 Google Cloud 控制台中,前往订阅页面。
- 点击创建订阅。
- 对于订阅 ID 字段,输入名称。
如需了解如何命名订阅,请参阅主题或订阅命名准则。
- 从下拉菜单中选择或创建一个主题。订阅将接收来自该主题的消息。
- 选择传送类型作为推送。
- 指定端点网址。
- 保留所有其他默认值。
- 点击创建。
您还可以通过主题部分创建订阅。此快捷方式可帮助您将主题与订阅关联。
gcloud
-
在 Google Cloud 控制台中,激活 Cloud Shell。
Cloud Shell 会话随即会在 Google Cloud 控制台的底部启动,并显示命令行提示符。Cloud Shell 是一个已安装 Google Cloud CLI 且已为当前项目设置值的 Shell 环境。该会话可能需要几秒钟时间来完成初始化。
-
如需创建推送订阅,请运行
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" } }
其中:
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 参考文档。
C#
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 C# 设置说明进行操作。如需了解详情,请参阅 Pub/Sub C# API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。
Go
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 Go 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Go API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。
Java
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 Java 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Java API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。
Node.js
Node.js
PHP
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 PHP 设置说明进行操作。如需了解详情,请参阅 Pub/Sub PHP API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。
Python
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 Python 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Python API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。
Ruby
在试用此示例之前,请按照“Pub/Sub 快速入门:使用客户端库”中的 Ruby 设置说明进行操作。如需了解详情,请参阅 Pub/Sub Ruby API 参考文档。
如需向 Pub/Sub 进行身份验证,请设置应用默认凭据。如需了解详情,请参阅为客户端库设置身份验证。