google.cloud.gcp_pubsub_subscription – Создаёт подписку GCP
Примечание
Этот плагин входит в состав коллекции google.cloud (версия 1.0.2).
Для его установки используйте: 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 целое число | Это максимальное время после получения сообщения подписчиком, в течение которого подписчик должен подтвердить сообщение. После доставки сообщения, но до истечения срока подтверждения и до подтверждения сообщения, оно считается незавершенным и не будет повторно доставлено в течение этого времени (по принципу наилучшего усилия). Для подписок на основе извлечения (pull) это значение используется в качестве начального значения срока подтверждения. Чтобы переопределить это значение для определенного сообщения, вызовите subscriptions.modifyAckDeadline с соответствующим идентификатором подтверждения, если используете pull. Минимальный настраиваемый срок подтверждения, который можно указать, составляет 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. Обратите внимание, что клиентские библиотеки могут автоматически продлевать сроки подтверждения. Этот параметр будет соблюдаться по принципу наилучших усилий. Если этот параметр равен 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 строка / обязательный | Указывает период "время жизни" для связанного ресурса. Ресурс истекает, если он неактивен в течение периода 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, который можно использовать для изменения формата отправленного сообщения. Этот атрибут указывает версию данных, ожидаемых конечной точкой. Это контролирует форму отправленного сообщения (т.е., его поля и метаданные). Версия конечной точки основана на версии 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 в HTTP-запросе для каждого отправленного сообщения. | |||
| audience строка | Аудитория, которая будет использоваться при генерации токена OIDC. Поле аудитории идентифицирует получателей, для которых предназначен 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 повторно пытается доставить сообщения для этой подписки. Если не задано, применяется политика повторных попыток по умолчанию. Это обычно означает, что сообщения будут повторно пытаться доставить как можно скорее для здоровых подписчиков. Политика повторных попыток будет активирована при получении 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. Обратите внимание, что клиентские библиотеки могут автоматически продлевать сроки подтверждения. Этот параметр будет обрабатываться в режиме наилучшего усилия. Если этот параметр равен 0, используется значение по умолчанию 5. | ||
| enableMessageOrdering логическое значение | успех | Если `true`, сообщения, опубликованные с одинаковым orderingKey в PubsubMessage, будут доставлены подписчикам в том порядке, в котором они были получены системой Pub/Sub. В противном случае они могут быть доставлены в произвольном порядке. | ||
| expirationPolicy сложный | успех | Политика, определяющая условия истечения срока действия этой подписки. Подписка считается активной, пока любой подключенный подписчик успешно потребляет сообщения из подписки или выполняет операции с подпиской. Если expirationPolicy не задан, будет использоваться политика по умолчанию со значением ttl в 31 день. Если она задана, но ttl пуста, ресурс никогда не истекает. Минимально допустимое значение для expirationPolicy.ttl — 1 день. | ||
| ttl строка | успех | Указывает продолжительность срока действия ("time-to-live") для связанного ресурса. Ресурс истекает, если он не активен в течение периода 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 сгенерирует и прикрепит JWT-токен OIDC в качестве заголовка Authorization в HTTP-запросе для каждого отправляемого сообщения. | ||
| audience строка | успех | Аудитория, которая будет использоваться при генерации токена OIDC. Требование аудитории идентифицирует получателей, для которых предназначен 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, указывающий конечную точку, в которую должны отправляться сообщения. Например, конечная точка веб-хука может использовать "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–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.11/collections/google/cloud/gcp_pubsub_subscription_module.html
