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

字符串

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

ack_deadline_seconds

整数

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

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

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

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

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

auth_kind

字符串 / 必需

使用的凭据类型。

选项

  • "application"

  • "machineaccount"

  • "serviceaccount"

  • "accesstoken"

dead_letter_policy

字典

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

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

dead_letter_topic

字符串

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

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

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

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

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

max_delivery_attempts

整数

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

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

NACK 是任何具有 0 截止期限的 ModifyAckDeadline 调用。请注意，客户端库可能会自动延长 ack_deadlines。

此字段将尽力而为。

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

enable_message_ordering

布尔值

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

选项

  • false

  • true

env_type

字符串

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

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

这只会更改任何 API 请求的用户代理字符串。

expiration_policy

字典

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

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

ttl

字符串 / 必需

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

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

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

示例 - “3.5s”。

filter

字符串

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

labels

字典

一组键/值标签对，用于分配给此订阅。

message_retention_duration

字符串

从发布消息的那一刻起，保留订阅积压中未确认的消息的时间长度。如果 retainAckedMessages 为 true，则这也配置已确认消息的保留时间，从而配置订阅.seek 可以回溯的时间范围。默认为 7 天。不能超过 7 天（`"604800s"`）或少于 10 分钟（`"600s"`）。

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

默认值： "604800s"

name

字符串 / 必需

订阅的名称。

project

字符串

要使用的 Google Cloud Platform 项目。

push_config

字典

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

attributes

字典

端点配置属性。

每个端点都有一组 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

字典

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

audience

字符串

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

service_account_email

字符串 / 必需

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

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

push_endpoint

字符串 / 必需

一个 URL，用于定位应将消息推送到其中的端点。

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

retain_acked_messages

布尔值

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

选项

  • false

  • true

retry_policy

字典

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

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

maximum_backoff

字符串

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

minimum_backoff

字符串

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

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

scopes

列表 / 元素=字符串

要使用的作用域数组

service_account_contents

jsonarg

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

service_account_email

字符串

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

service_account_file

路径

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

state

字符串

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

选项

  • "present" ← (默认)

  • "absent"

topic

字典 / 必需

对主题资源的引用。

此字段表示指向 GCP 中主题资源的链接。可以通过两种方式指定。首先，您可以放置一个字典，其中键为“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

整数

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

对于拉取订阅，此值用作确认截止期限的初始值。如果使用拉取，要覆盖给定消息的此值，请使用相应的 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）必须有权在此订阅上确认() 消息。

返回：成功

deadLetterTopic

字符串

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

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

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

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

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

返回：成功

maxDeliveryAttempts

整数

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

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

NACK 是任何具有 0 截止期限的 ModifyAckDeadline 调用。请注意，客户端库可能会自动延长 ack_deadlines。

此字段将尽力而为。

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

返回：成功

enableMessageOrdering

布尔值

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

返回：成功

expirationPolicy

复杂

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

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

返回：成功

ttl

字符串

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

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

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

示例 - “3.5s”。

返回：成功

filter

字符串

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

返回：成功

labels

字典

一组键/值标签对，用于分配给此订阅。

返回：成功

messageRetentionDuration

字符串

从发布消息的那一刻起，保留订阅积压中未确认的消息的时间长度。如果 retainAckedMessages 为 true，则这也配置已确认消息的保留时间，从而配置订阅.seek 可以回溯的时间范围。默认为 7 天。不能超过 7 天（`"604800s"`）或少于 10 分钟（`"600s"`）。

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

返回：成功

name

字符串

订阅的名称。

返回：成功

pushConfig

复杂

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

返回：成功

attributes

字典

端点配置属性。

每个端点都有一组 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 令牌作为每个推送消息的 HTTP 请求中的授权标头。

返回：成功

audience

字符串

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

返回：成功

serviceAccountEmail

字符串

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

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

返回：成功

pushEndpoint

字符串

一个 URL，用于定位应将消息推送到其中的端点。

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

返回：成功

retainAckedMessages

布尔值

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

返回：成功

retryPolicy

复杂

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

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

返回：成功

maximumBackoff

字符串

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

返回：成功

minimumBackoff

字符串

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

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

返回：成功

topic

字典

对主题资源的引用。

返回：成功

作者

  • Google Inc. (@googlecloudplatform)