google.cloud.gcp_pubsub_subscription – Создаёт подписку GCP
Примечание
Этот плагин входит в коллекцию google.cloud (версия 1.0.1).
Для его установки используйте: ansible-galaxy collection install google.cloud.
Для использования в плейбуке укажите: google.cloud.gcp_pubsub_subscription.
Краткое описание
- Именованный ресурс, представляющий собой поток сообщений с одного конкретного топика, который должен быть доставлен подписывающемуся приложению.
Требования
Ниже перечислены требования к хосту, на котором будет выполняться этот модуль.
- python >= 2.6
- requests >= 2.18.4
- google-auth >= 1.3.0
Параметры
| Параметр | Варианты/Значения по умолчанию | Комментарии | ||
|---|---|---|---|---|
| ack_deadline_seconds целое число | Это максимальное время после получения сообщения подписчиком, в течение которого подписчик должен подтвердить сообщение. После доставки сообщения, но до истечения срока подтверждения и до подтверждения сообщения, оно считается ожидающим и не будет повторно доставлено в течение этого времени (по принципу наилучших усилий). Для подписок на основе запросов это значение используется как начальное значение срока подтверждения. Чтобы переопределить это значение для данного сообщения, вызовите subscriptions.modifyAckDeadline с соответствующим ackId, если используете запросы. Минимальный настраиваемый срок составляет 10 секунд. Максимальный настраиваемый срок составляет 600 секунд (10 минут). Если этот параметр равен 0, используется значение по умолчанию 10 секунд. Для доставки по методу push это значение также используется для установки таймаута запроса для вызова конечной точки push. Если подписчик никогда не подтверждает сообщение, система Pub/Sub в конечном итоге повторно доставит сообщение. | |||
| auth_kind строка / обязательно |
| Тип используемых учетных данных. | ||
| dead_letter_policy словарь | Политика, определяющая условия для отправки сообщений в мертвую почту в этой подписке. Если dead_letter_policy не задан, отправка в мертвую почту отключена. Учетная запись службы Google Cloud Pub/Sub, связанная с родительским проектом этой подписки (т. е., service-{номер_проекта}@gcp-sa-pubsub.iam.gserviceaccount.com), должна иметь разрешение на подтверждение (Acknowledge()) сообщений в этой подписке. | |||
| dead_letter_topic строка | Имя темы, в которую должны публиковаться сообщения мертвой почты. Формат: `projects/{project}/topics/{topic}`. Учетная запись службы Google Cloud Pub/Sub, связанная с родительским проектом подписки (т. е., service-{номер_проекта}@gcp-sa-pubsub.iam.gserviceaccount.com), должна иметь разрешение на публикацию (Publish()) в эту тему. Операция завершится ошибкой, если тема не существует. Пользователи должны убедиться, что к этой теме прикреплена подписка, так как сообщения, опубликованные в тему без подписок, теряются. | |||
| max_delivery_attempts целое число | Максимальное количество попыток доставки сообщения. Значение должно быть между 5 и 100. Количество попыток доставки определяется как 1 + (сумма количества NACK и количества раз, когда срок подтверждения был превышен для сообщения). NACK — это любой вызов ModifyAckDeadline с сроком 0. Обратите внимание, что клиентские библиотеки могут автоматически продлевать ack_deadlines. Этот параметр будет обрабатываться по принципу наилучших усилий. Если этот параметр равен 0, используется значение по умолчанию 5. | |||
| enable_message_ordering логическое значение |
| Если `true`, сообщения, опубликованные с одинаковым orderingKey в PubsubMessage, будут доставлены подписчикам в том порядке, в котором они получены системой Pub/Sub. В противном случае они могут быть доставлены в любом порядке. | ||
| env_type строка | Указывает, в какой среде Ansible выполняется данный модуль. Это не нужно устанавливать, если вы не знаете, что делаете. Это влияет только на строку User Agent для любых запросов к API. | |||
| expiration_policy словарь | Политика, определяющая условия истечения срока действия этой подписки. Подписка считается активной, пока подключенный подписчик успешно потребляет сообщения из подписки или выполняет операции с подпиской. Если expirationPolicy не задан, будет использоваться политика по умолчанию со сроком жизни 31 день. Если она задана, но ttl пустая, ресурс никогда не истекает. Минимальное допустимое значение для expirationPolicy.ttl — 1 день. | |||
| ttl строка / обязательно | Определяет срок действия (time-to-live) для связанного ресурса. Ресурс истекает, если он не активен в течение периода ttl. Если ttl не задан, связанный ресурс никогда не истекает. Длительность в секундах с до девятью десятичными знаками, заканчивающимися на 's'. Пример - "3.5s". | |||
| filter строка | Подписка доставляет только сообщения, соответствующие фильтру. Pub/Sub автоматически подтверждает сообщения, которые не соответствуют фильтру. Вы можете фильтровать сообщения по их атрибутам. Максимальная длина фильтра составляет 256 байт. После создания подписки вы не можете изменить фильтр. | |||
| labels словарь | Набор пар ключ/значение меток, которые нужно назначить этой подписке. | |||
| message_retention_duration строка | По умолчанию: "604800s" | Сколько времени хранить неопознанные сообщения в очереди подписки с момента публикации сообщения. Если retainAckedMessages равно true, это также настраивает сохранение подтверждённых сообщений и, таким образом, настраивает, как далеко в прошлом можно выполнить subscriptions.seek. По умолчанию 7 дней. Не может быть более 7 дней ("604800s") или менее 10 минут ("600s"). Длительность в секундах с до девятью десятичными знаками, заканчивающимися на 's'. Пример: `"600.5s"`. | ||
| name строка / обязательно | Имя подписки. | |||
| project строка | Проект Google Cloud Platform для использования. | |||
| push_config словарь | Если используется доставка по методу push с этой подпиской, этот параметр используется для ее настройки. Пустой pushConfig означает, что подписчик будет получать и подтверждать сообщения с помощью методов API. | |||
| attributes словарь | Атрибуты конфигурации конечной точки. Каждая конечная точка имеет набор поддерживаемых API атрибутов, которые могут быть использованы для управления различными аспектами доставки сообщений. В настоящее время поддерживаемый атрибут — x-goog-version, который можно использовать для изменения формата сообщения, отправленного по методу push. Этот атрибут указывает ожидаемую версию данных конечной точкой. Это определяет структуру отправленного сообщения (т. е. его поля и метаданные). Версия конечной точки основана на версии API Pub/Sub. Если он отсутствует при вызове subscriptions.create, он будет по умолчанию иметь версию API, использованную для этого вызова. Если он отсутствует при вызове subscriptions.modifyPushConfig, его значение не будет изменено. Вызовы subscriptions.get всегда будут возвращать действительную версию, даже если подписка была создана без этого атрибута. Возможные значения этого атрибута: - v1beta1: использует формат push, определенный в API Pub/Sub версии v1beta1. - v1 или v1beta2: использует формат push, определенный в API Pub/Sub версии v1. | |||
| oidc_token словарь | Если указано, Pub/Sub сгенерирует и прикрепит токен OIDC JWT в качестве заголовка Authorization к каждому отправленному по методу push сообщению. | |||
| audience строка | Аудитория, которая будет использоваться при генерации токена OIDC. Поле аудитории JWT идентифицирует получателей, для которых предназначен JWT. Значение аудитории — одна строка, чувствительная к регистру. Не поддерживается несколько значений (массив) для поля аудитории. Дополнительную информацию об аудитории токена OIDC JWT можно найти здесь: https://tools.ietf.org/html/rfc7519#section-4.1.3 Примечание: если не указано, будет использоваться URL конечной точки Push. | |||
| service_account_email строка / обязательно | Электронная почта учетной записи службы, которая будет использоваться для генерации токена OIDC. Вызывающая сторона (для RPC subscriptions.create, subscriptions.patch и subscriptions.modifyPushConfig) должна иметь разрешение iam.serviceAccounts.actAs для учетной записи службы. | |||
| push_endpoint строка / обязательно | URL, указывающий конечную точку, в которую должны быть отправлены сообщения. Например, конечная точка веб-хука может использовать "https://example.com/push". | |||
| retain_acked_messages логическое значение |
| Указывает, нужно ли сохранять подтверждённые сообщения. Если `true`, сообщения не удаляются из очереди подписки, даже если они подтверждены, до тех пор, пока они не выйдут из окна messageRetentionDuration. | ||
| retry_policy словарь | Политика, определяющая, как Pub/Sub повторно пытается доставить сообщения для этой подписки. Если не задано, применяется политика повторных попыток по умолчанию. В общем случае это означает, что сообщения будут повторно отправляться как можно быстрее для здоровых подписчиков. RetryPolicy будет срабатывать при событиях 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 string | Необязательный адрес электронной почты учетной записи службы, если выбран machineaccount и пользователь не хочет использовать адрес по умолчанию. | |||
| service_account_file path | Путь к файлу JSON учетной записи службы, если тип serviceaccount выбран как тип. | |||
| state string |
| Указывает, должно ли данное object существовать в GCP | ||
| topic dictionary / required | Ссылка на ресурс Topic. Это поле представляет ссылку на ресурс Topic в GCP. Его можно указать двумя способами. Во-первых, вы можете поместить словарь с ключом 'name' и значением имени вашего ресурса. Во-вторых, вы можете добавить `register: name-of-resource` к задаче gcp_pubsub_topic, а затем установить это поле 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
- для аутентификации можно установить service_account_file, используя переменную среды
gcp_service_account_file. - для аутентификации можно установить service_account_contents, используя переменную среды
GCP_SERVICE_ACCOUNT_CONTENTS. - для аутентификации можно установить service_account_email, используя переменную среды
GCP_SERVICE_ACCOUNT_EMAIL. - для аутентификации можно установить auth_kind, используя переменную среды
GCP_AUTH_KIND. - для аутентификации можно установить scopes, используя переменную среды
GCP_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 целое число | успех | Это максимальное время после получения сообщения подписчиком, прежде чем подписчик должен подтвердить сообщение. После доставки сообщения, но до истечения срока подтверждения и до подтверждения сообщения, это незавершенное сообщение и оно не будет повторно доставлено в течение этого времени (на основе наилучшего усилия). Для подписок на основе получения это значение используется в качестве начального значения для срока подтверждения. Чтобы переопределить это значение для данного сообщения, вызовите subscriptions.modifyAckDeadline с соответствующим идентификатором подтверждения, если используется получение. Минимальный настраиваемый срок составляет 10 секунд. Максимальный настраиваемый срок составляет 600 секунд (10 минут). Если этот параметр равен 0, используется значение по умолчанию 10 секунд. Для доставки через push это значение также используется для установки таймаута запроса для вызова push-точке. Если подписчик никогда не подтверждает сообщение, система Pub/Sub в конечном итоге повторно доставит сообщение. | ||
| deadLetterPolicy сложный | успех | Политика, которая определяет условия для отправки сообщений в мертвую почту в этом подписке. Если dead_letter_policy не задано, отправка в мертвую почту отключена. Учетная запись сервиса Google Cloud Pub/Sub, связанная с родительским проектом этой подписки (т. е., service-{номер_проекта}@gcp-sa-pubsub.iam.gserviceaccount.com), должна иметь разрешение Acknowledge() сообщений в этой подписке. | ||
| deadLetterTopic строка | успех | Имя темы, в которую должны публиковаться сообщения мертвой почты. Формат: `projects/{project}/topics/{topic}`. Учетная запись сервиса Google Cloud Pub/Sub, связанная с родительским проектом окружающего подписки (т. е., service-{номер_проекта}@gcp-sa-pubsub.iam.gserviceaccount.com), должна иметь разрешение Publish() в эту тему. Операция завершится неудачей, если тема не существует. Пользователи должны убедиться, что к этой теме прикреплена подписка, так как сообщения, опубликованные в теме без подписок, теряются. | ||
| maxDeliveryAttempts целое число | успех | Максимальное количество попыток доставки любого сообщения. Значение должно быть между 5 и 100. Количество попыток доставки определяется как 1 + (сумма числа NACK и числа случаев, когда истек срок подтверждения сообщения). NACK — это любой вызов ModifyAckDeadline с сроком 0. Обратите внимание, что клиентские библиотеки могут автоматически продлевать 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 сложный | успех | Если для этой подписки используется доставка через push, это поле используется для ее настройки. Пустая pushConfig означает, что подписчик будет получать и подтверждать сообщения с помощью методов API. | ||
| attributes словарь | успех | Атрибуты конфигурации конечной точки. Каждая конечная точка имеет набор поддерживаемых API атрибутов, которые могут использоваться для управления различными аспектами доставки сообщений. В настоящее время поддерживается атрибут x-goog-version, который вы можете использовать для изменения формата отправляемого сообщения. Этот атрибут указывает версию данных, ожидаемых конечной точкой. Это управляет формой отправляемого сообщения (т. е. его полями и метаданными). Версия конечной точки основана на версии API Pub/Sub. Если он не задан во время вызова subscriptions.create, он по умолчанию будет равен версии API, использованной для этого вызова. Если он не задан во время вызова subscriptions.modifyPushConfig, его значение не будет изменено. Вызовы subscriptions.get всегда возвращают допустимую версию, даже если подписка была создана без этого атрибута. Возможные значения для этого атрибута: - v1beta1: использует формат push, определенный в API Pub/Sub v1beta1. - v1 или v1beta2: использует формат push, определенный в API Pub/Sub v1. | ||
| oidcToken сложный | успех | Если указано, Pub/Sub сгенерирует и прикрепит токен OIDC JWT в качестве заголовка Authorization в HTTP-запросе для каждого отправляемого сообщения. | ||
| audience строка | успех | Аудитория, которая будет использоваться при генерации токена OIDC. Требование аудитории JWT определяет получателей, для которых предназначен JWT. Значение аудитории — это строка с одним регистром. Не поддерживается наличие нескольких значений (массива) для поля аудитории. Дополнительная информация о требовании аудитории токена OIDC JWT здесь: https://tools.ietf.org/html/rfc7519#section-4.1.3 Примечание: если не указано, будет использоваться URL push-конечной точки. | ||
| serviceAccountEmail строка | успех | Электронная почта учетной записи сервиса, которая будет использоваться для генерации токена OIDC. Вызывающий (для RPC subscriptions.create, subscriptions.patch и subscriptions.modifyPushConfig) должен иметь разрешение iam.serviceAccounts.actAs для учетной записи сервиса. | ||
| pushEndpoint строка | успех | URL, указывающий на конечную точку, в которую должны отправляться сообщения. Например, конечная точка Webhook может использовать "https://example.com/push". | ||
| retainAckedMessages логическое значение | успех | Указывает, нужно ли хранить подтвержденные сообщения. Если `true`, сообщения не удаляются из очереди подписки, даже если они подтверждены, пока они не выйдут из окна messageRetentionDuration. | ||
| retryPolicy сложный | успех | Политика, которая определяет, как Pub/Sub повторно пытается доставить сообщения для этой подписки. Если не задано, применяется политика повторных попыток по умолчанию. Это обычно подразумевает, что сообщения будут повторно пытаться доставить как можно скорее для здоровых подписчиков. RetryPolicy будет активироваться при событиях NACK или истечения срока подтверждения для данного сообщения. | ||
| maximumBackoff строка | успех | Максимальная задержка между последовательными доставками данного сообщения. Значение должно быть между 0 и 600 секундами. По умолчанию 600 секунд. Продолжительность в секундах с точностью до девяти десятичных знаков, завершающаяся символом 's'. Пример: "3.5s". | ||
| minimumBackoff строка | успех | Минимальная задержка между последовательными доставками данного сообщения. Значение должно быть между 0 и 600 секундами. По умолчанию 10 секунд. Продолжительность в секундах с точностью до девяти десятичных знаков, завершающаяся символом 's'. Пример: "3.5s". | ||
| topic словарь | успех | Ссылка на ресурс Topic. | ||
Авторы
- Google Inc. (@googlecloudplatform)
© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/google/cloud/gcp_pubsub_subscription_module.html
