google.cloud.gcp_pubsub_subscription 模块 – 创建 GCP 订阅

注意

此模块是 google.cloud 集合（版本 1.4.1）的一部分。

如果您正在使用 ansible 包，您可能已经安装了这个集合。 它不包含在 ansible-core 中。 要检查是否已安装，请运行 ansible-galaxy collection list。

要安装它，请使用：ansible-galaxy collection install google.cloud。您需要进一步的要求才能使用此模块，有关详细信息，请参阅 要求。

要在 playbook 中使用它，请指定：google.cloud.gcp_pubsub_subscription。

注意

由于违反了 Ansible 包含要求，google.cloud 集合将从 Ansible 12 中删除。 该集合有 未解决的健全性测试失败。 有关更多信息，请参阅 讨论主题。

概要

  • 一个命名资源，表示来自单个特定主题的消息流，该流将传递到订阅应用程序。

要求

执行此模块的主机需要以下要求。

  • python >= 2.6

  • requests >= 2.18.4

  • google-auth >= 1.3.0

参数

参数

注释

access_token

string

如果凭据类型为 accesstoken，则为 OAuth2 访问令牌。

ack_deadline_seconds

integer

此值是订阅者收到消息后，订阅者应确认消息的最长时间。消息传递后但在 ack 截止时间到期之前以及消息被确认之前，它是一个未完成的消息，并且在该时间内（尽力而为）不会再次传递。

对于拉取订阅，此值用作 ack 截止时间的初始值。要为给定消息覆盖此值，如果使用拉取，请使用相应的 ackId 调用 subscriptions.modifyAckDeadline。您可以指定的最小自定义截止时间为 10 秒。您可以指定的最大自定义截止时间为 600 秒（10 分钟）。

如果此参数为 0，则使用默认值 10 秒。

对于推送传递，此值还用于设置对推送端点的调用的请求超时。

如果订阅者从不确认消息，则 Pub/Sub 系统最终将重新传递该消息。

auth_kind

string / 必填

使用的凭据类型。

选项

  • "application"

  • "machineaccount"

  • "serviceaccount"

  • "accesstoken"

dead_letter_policy

dictionary

指定此订阅中死信消息条件的策略。如果未设置 dead_letter_policy，则禁用死信。

与此订阅父项目关联的 Cloud Pub/Sub 服务帐户（即 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com）必须具有在此订阅上 Acknowledge() 消息的权限。

dead_letter_topic

string

死信消息应发布到的主题名称。

格式为 `projects/{project}/topics/{topic}`。

与封闭订阅的父项目关联的 Cloud Pub/Sub 服务帐户（即 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com）必须具有向此主题 Publish() 的权限。

如果该主题不存在，则操作将失败。

用户应确保有一个订阅附加到该主题，因为发布到没有订阅的主题的消息会丢失。

max_delivery_attempts

integer

任何消息的最大传递尝试次数。该值必须介于 5 和 100 之间。

传递尝试次数定义为 1 +（NACK 的数量和消息超过确认截止时间的次数之和）。

NACK 是对 ModifyAckDeadline 的任何调用，截止时间为 0。请注意，客户端库可能会自动延长 ack_deadlines。

此字段将在尽力而为的基础上得到遵守。

如果此参数为 0，则使用默认值 5。

enable_message_ordering

boolean

如果为 `true`，则在 PubsubMessage 中使用相同 orderingKey 发布的消息将按照它们被 Pub/Sub 系统接收的顺序传递给订阅者。否则，它们可以按任何顺序传递。

选项

  • false

  • true

env_type

string

指定您正在其中运行此模块的 Ansible 环境。

除非您知道自己在做什么，否则不应设置此项。

这只会更改任何 API 请求的 User Agent 字符串。

expiration_policy

dictionary

一个策略，指定此订阅过期的条件。

只要有任何连接的订阅者正在成功地从订阅中使用消息或正在对订阅发出操作，则该订阅就被认为是活动的。如果未设置 expirationPolicy，则将使用 ttl 为 31 天的默认策略。如果设置了，但 ttl 为“”，则资源永远不会过期。expirationPolicy.ttl 允许的最小值为 1 天。

ttl

string / 必填

指定关联资源的“生存时间”持续时间。如果资源在 ttl 期间未处于活动状态，则该资源将过期。

如果未设置 ttl，则关联的资源永远不会过期。

一个以秒为单位的持续时间，最多包含九个小数位，并以“s”结尾。

示例 - “3.5s”。

filter

string

订阅仅传递与过滤器匹配的消息。 Pub/Sub 会自动确认与过滤器不匹配的消息。 您可以按消息的属性筛选消息。 筛选器的最大长度为 256 个字节。 创建订阅后，您无法修改过滤器。

labels

dictionary

一组要分配给此订阅的键/值标签对。

message_retention_duration

string

从发布消息的那一刻起，在订阅的积压中保留未确认消息的时间。如果 retainAckedMessages 为 true，则这还会配置已确认消息的保留，从而配置 subscription.seek 可以追溯到的时间。默认为 7 天。不能超过 7 天 (`“604800s”`) 或少于 10 分钟 (`“600s”`)。

一个以秒为单位的持续时间，最多包含九个小数位，并以“s”结尾。示例：`“600.5s”`。

默认值： "604800s"

名称

string / 必填

订阅的名称。

项目

string

要使用的 Google Cloud Platform 项目。

push_config

dictionary

如果此订阅使用推送传递，则此字段用于配置它。空的 pushConfig 表示订阅者将使用 API 方法拉取和确认消息。

属性

dictionary

端点配置属性。

每个端点都有一组 API 支持的属性，可用于控制消息传递的不同方面。

当前支持的属性是 x-goog-version，您可以使用它来更改推送消息的格式。此属性指示端点期望的数据版本。这控制推送消息的形状（即其字段和元数据）。端点版本基于 Pub/Sub API 的版本。

如果在 subscriptions.create 调用期间不存在，则它将默认为用于进行此类调用的 API 版本。如果在 subscriptions.modifyPushConfig 调用期间不存在，则其值不会更改。subscriptions.get 调用将始终返回有效版本，即使订阅是在没有此属性的情况下创建的。

此属性的可能值为：- v1beta1：使用 v1beta1 Pub/Sub API 中定义的推送格式。

  • v1 或 v1beta2：使用 v1 Pub/Sub API 中定义的推送格式。

oidc_token

dictionary

如果指定，Pub/Sub 将生成一个 OIDC JWT 令牌，并将其作为 Authorization 标头附加到每个推送消息的 HTTP 请求中。

audience

string

生成 OIDC 令牌时要使用的受众。受众声明标识 JWT 预期的接收者。受众值是一个区分大小写的字符串。不支持受众字段的多个值（数组）。有关 OIDC JWT 令牌受众的更多信息，请参阅此处：https://tools.ietf.org/html/rfc7519#section-4.1.3 注意：如果未指定，将使用推送端点 URL。

service_account_email

string / 必填

用于生成 OIDC 令牌的服务帐户电子邮件。

调用者（对于 subscriptions.create、subscriptions.patch 和 subscriptions.modifyPushConfig RPC）必须具有该服务帐户的 iam.serviceAccounts.actAs 权限。

push_endpoint

string / 必填

定位应将消息推送到的端点的 URL。

例如，Webhook 端点可能使用“https://example.com/push”。

retain_acked_messages

boolean

指示是否保留已确认的消息。如果为 `true`，则即使消息被确认，也不会从订阅的积压中清除消息，直到它们超出 messageRetentionDuration 窗口。

选项

  • false

  • true

retry_policy

dictionary

一个策略，用于指定 Pub/Sub 如何为此订阅重试消息传递。

如果未设置，则应用默认重试策略。这通常意味着对于运行状况良好的订阅者，消息将尽快重试。RetryPolicy 将在给定消息的 NACK 或确认截止时间超出事件时触发。

maximum_backoff

string

给定消息的连续传递之间的最大延迟。值应介于 0 和 600 秒之间。默认为 600 秒。以秒为单位的持续时间，最多可达九位小数，以“s”结尾。示例：“3.5s”。

minimum_backoff

string

给定消息的连续传递之间的最小延迟。值应介于 0 和 600 秒之间。默认为 10 秒。

以秒为单位的持续时间，最多可达九位小数，以“s”结尾。示例：“3.5s”。

scopes

列表 / 元素=字符串

要使用的范围数组

service_account_contents

jsonarg

服务帐户 JSON 文件的内容，可以是字典或表示它的 JSON 字符串。

service_account_email

string

如果选择了 machineaccount 且用户不希望使用默认电子邮件，则可选择服务帐户电子邮件地址。

service_account_file

路径

如果选择 serviceaccount 作为类型，则为服务帐户 JSON 文件的路径。

state

string

给定对象是否应存在于 GCP 中

选项

  • "present" ← (默认)

  • "absent"

topic

字典 / 必需

对 Topic 资源的引用。

此字段表示指向 GCP 中 Topic 资源的链接。它可以通过两种方式指定。首先，您可以放置一个字典，其中包含键“name”和资源名称的值。或者，您可以向 gcp_pubsub_topic 任务添加 `register: name-of-resource`，然后将此主题字段设置为“{{ name-of-resource }}”

注释

注意

  • API 参考：https://cloud.google.com/pubsub/docs/reference/rest/v1/projects.subscriptions

  • 管理订阅：https://cloud.google.com/pubsub/docs/admin#managing_subscriptions

  • 对于身份验证，您可以使用 GCP_SERVICE_ACCOUNT_FILE 环境变量设置 service_account_file。

  • 对于身份验证，您可以使用 GCP_SERVICE_ACCOUNT_CONTENTS 环境变量设置 service_account_contents。

  • 对于身份验证，您可以使用 GCP_SERVICE_ACCOUNT_EMAIL 环境变量设置 service_account_email。

  • 对于身份验证，您可以使用 GCP_ACCESS_TOKEN 环境变量设置 access_token。

  • 对于身份验证，您可以使用 GCP_AUTH_KIND 环境变量设置 auth_kind。

  • 对于身份验证，您可以使用 GCP_SCOPES 环境变量设置 scopes。

  • 仅当未设置 playbook 值时，才会使用环境变量值。

  • service_account_email 和 service_account_file 选项是互斥的。

示例

- name: create a topic
  google.cloud.gcp_pubsub_topic:
    name: topic-subscription
    project: "{{ gcp_project }}"
    auth_kind: "{{ gcp_cred_kind }}"
    service_account_file: "{{ gcp_cred_file }}"
    state: present
  register: topic

- name: create a subscription
  google.cloud.gcp_pubsub_subscription:
    name: test_object
    topic: "{{ topic }}"
    ack_deadline_seconds: 300
    project: test_project
    auth_kind: serviceaccount
    service_account_file: "/tmp/auth.pem"
    state: present

返回值

通用返回值已记录在此处，以下是此模块特有的字段

键

描述

ackDeadlineSeconds

integer

此值是订阅者收到消息后，订阅者应确认消息的最长时间。消息传递后但在 ack 截止时间到期之前以及消息被确认之前，它是一个未完成的消息，并且在该时间内（尽力而为）不会再次传递。

对于拉取订阅，此值用作 ack 截止时间的初始值。要为给定消息覆盖此值，如果使用拉取，请使用相应的 ackId 调用 subscriptions.modifyAckDeadline。您可以指定的最小自定义截止时间为 10 秒。您可以指定的最大自定义截止时间为 600 秒（10 分钟）。

如果此参数为 0，则使用默认值 10 秒。

对于推送传递，此值还用于设置对推送端点的调用的请求超时。

如果订阅者从不确认消息，则 Pub/Sub 系统最终将重新传递该消息。

返回：成功

deadLetterPolicy

复杂

指定此订阅中死信消息条件的策略。如果未设置 dead_letter_policy，则禁用死信。

与此订阅父项目关联的 Cloud Pub/Sub 服务帐户（即 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com）必须具有在此订阅上 Acknowledge() 消息的权限。

返回：成功

deadLetterTopic

string

死信消息应发布到的主题名称。

格式为 `projects/{project}/topics/{topic}`。

与封闭订阅的父项目关联的 Cloud Pub/Sub 服务帐户（即 service-{project_number}@gcp-sa-pubsub.iam.gserviceaccount.com）必须具有向此主题 Publish() 的权限。

如果该主题不存在，则操作将失败。

用户应确保有一个订阅附加到该主题，因为发布到没有订阅的主题的消息会丢失。

返回：成功

maxDeliveryAttempts

integer

任何消息的最大传递尝试次数。该值必须介于 5 和 100 之间。

传递尝试次数定义为 1 +（NACK 的数量和消息超过确认截止时间的次数之和）。

NACK 是对 ModifyAckDeadline 的任何调用，截止时间为 0。请注意，客户端库可能会自动延长 ack_deadlines。

此字段将在尽力而为的基础上得到遵守。

如果此参数为 0，则使用默认值 5。

返回：成功

enableMessageOrdering

boolean

如果为 `true`，则在 PubsubMessage 中使用相同 orderingKey 发布的消息将按照它们被 Pub/Sub 系统接收的顺序传递给订阅者。否则，它们可以按任何顺序传递。

返回：成功

expirationPolicy

复杂

一个策略，指定此订阅过期的条件。

只要有任何连接的订阅者正在成功地从订阅中使用消息或正在对订阅发出操作，则该订阅就被认为是活动的。如果未设置 expirationPolicy，则将使用 ttl 为 31 天的默认策略。如果设置了，但 ttl 为“”，则资源永远不会过期。expirationPolicy.ttl 允许的最小值为 1 天。

返回：成功

ttl

string

指定关联资源的“生存时间”持续时间。如果资源在 ttl 期间未处于活动状态，则该资源将过期。

如果未设置 ttl，则关联的资源永远不会过期。

一个以秒为单位的持续时间，最多包含九个小数位，并以“s”结尾。

示例 - “3.5s”。

返回：成功

filter

string

订阅仅传递与过滤器匹配的消息。 Pub/Sub 会自动确认与过滤器不匹配的消息。 您可以按消息的属性筛选消息。 筛选器的最大长度为 256 个字节。 创建订阅后，您无法修改过滤器。

返回：成功

labels

dictionary

一组要分配给此订阅的键/值标签对。

返回：成功

messageRetentionDuration

string

从发布消息的那一刻起，在订阅的积压中保留未确认消息的时间。如果 retainAckedMessages 为 true，则这还会配置已确认消息的保留，从而配置 subscription.seek 可以追溯到的时间。默认为 7 天。不能超过 7 天 (`“604800s”`) 或少于 10 分钟 (`“600s”`)。

一个以秒为单位的持续时间，最多包含九个小数位，并以“s”结尾。示例：`“600.5s”`。

返回：成功

名称

string

订阅的名称。

返回：成功

pushConfig

复杂

如果此订阅使用推送传递，则此字段用于配置它。空的 pushConfig 表示订阅者将使用 API 方法拉取和确认消息。

返回：成功

属性

dictionary

端点配置属性。

每个端点都有一组 API 支持的属性，可用于控制消息传递的不同方面。

当前支持的属性是 x-goog-version，您可以使用它来更改推送消息的格式。此属性指示端点期望的数据版本。这控制推送消息的形状（即其字段和元数据）。端点版本基于 Pub/Sub API 的版本。

如果在 subscriptions.create 调用期间不存在，则它将默认为用于进行此类调用的 API 版本。如果在 subscriptions.modifyPushConfig 调用期间不存在，则其值不会更改。subscriptions.get 调用将始终返回有效版本，即使订阅是在没有此属性的情况下创建的。

此属性的可能值为：- v1beta1：使用 v1beta1 Pub/Sub API 中定义的推送格式。

  • v1 或 v1beta2：使用 v1 Pub/Sub API 中定义的推送格式。

返回：成功

oidcToken

复杂

如果指定，Pub/Sub 将生成一个 OIDC JWT 令牌，并将其作为 Authorization 标头附加到每个推送消息的 HTTP 请求中。

返回：成功

audience

string

生成 OIDC 令牌时要使用的受众。受众声明标识 JWT 预期的接收者。受众值是一个区分大小写的字符串。不支持受众字段的多个值（数组）。有关 OIDC JWT 令牌受众的更多信息，请参阅此处：https://tools.ietf.org/html/rfc7519#section-4.1.3 注意：如果未指定，将使用推送端点 URL。

返回：成功

serviceAccountEmail

string

用于生成 OIDC 令牌的服务帐户电子邮件。

调用者（对于 subscriptions.create、subscriptions.patch 和 subscriptions.modifyPushConfig RPC）必须具有该服务帐户的 iam.serviceAccounts.actAs 权限。

返回：成功

pushEndpoint

string

定位应将消息推送到的端点的 URL。

例如，Webhook 端点可能使用“https://example.com/push”。

返回：成功

retainAckedMessages

boolean

指示是否保留已确认的消息。如果为 `true`，则即使消息被确认，也不会从订阅的积压中清除消息，直到它们超出 messageRetentionDuration 窗口。

返回：成功

retryPolicy

复杂

一个策略，用于指定 Pub/Sub 如何为此订阅重试消息传递。

如果未设置，则应用默认重试策略。这通常意味着对于运行状况良好的订阅者，消息将尽快重试。RetryPolicy 将在给定消息的 NACK 或确认截止时间超出事件时触发。

返回：成功

maximumBackoff

string

给定消息的连续传递之间的最大延迟。值应介于 0 和 600 秒之间。默认为 600 秒。以秒为单位的持续时间，最多可达九位小数，以“s”结尾。示例：“3.5s”。

返回：成功

minimumBackoff

string

给定消息的连续传递之间的最小延迟。值应介于 0 和 600 秒之间。默认为 10 秒。

以秒为单位的持续时间，最多可达九位小数，以“s”结尾。示例：“3.5s”。

返回：成功

topic

dictionary

对 Topic 资源的引用。

返回：成功

作者

  • Google Inc. (@googlecloudplatform)