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) 必须具有对此订阅的 Acknowledge() 消息的权限。

dead_letter_topic

字符串

应将失效消息发布到的主题的名称。

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

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

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

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

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，则这也配置已确认消息的保留，从而配置 subscriptions.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 或确认截止日期超过事件时触发。

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”且值为资源名称的字典。或者，您可以将 `register: name-of-resource` 添加到 gcp_pubsub_topic 任务，然后将此主题字段设置为“{{ 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，则这也配置已确认消息的保留，从而配置 subscriptions.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 或确认截止日期超过事件时触发。

返回：成功

maximumBackoff

字符串

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

返回：成功

minimumBackoff

字符串

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

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

返回：成功

topic

字典

对主题资源的引用。

返回：成功

作者

  • Google Inc. (@googlecloudplatform)