# Yandex Message Queue API Reference **Дата документации:** 11 апреля 2026 ## Обзор Yandex Message Queue предоставляет HTTP API, частично совместимый с Amazon SQS API. ### Базовые параметры всех запросов **Адрес:** `POST https://message-queue.api.cloud.yandex.net/` **Заголовки:** - `Content-Type: application/x-www-form-urlencoded` - `Authorization: Authorization string (AWS Signature Version 4)` **Параметры запроса:** - `Action` — название вызываемого метода API - `Version` — всегда `2012-11-05` ### Формат передачи массивов параметров Элементы массивов передаются с индексами начиная с 1: ``` Attribute.1.Name=VisibilityTimeout Attribute.1.Value=40 Attribute.2.Name=MessageRetentionPeriod Attribute.2.Value=1000 ``` ### Формат ответов **Успешный ответ:** ```xml UUID ``` **Ошибочный ответ:** ```xml Sender|Receiver ошибка Описание UUID ``` --- ## API Команды ### Управление очередями #### CreateQueue Создание новой стандартной или FIFO очереди. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueName | string | Да | Имя очереди (макс 80 символов). Для FIFO должно оканчиваться на .fifo | | Attributes.N.* | список | Нет | Атрибуты очереди | | Tags.N.* | список | Нет | Метки очереди | **Атрибуты очереди:** | Атрибут | Тип | Описание | |---|---|---| | DelaySeconds | integer | 0-900 сек. Default: 0 | | MaximumMessageSize | integer | 1024-262144 байт. Default: 262144 | | MessageRetentionPeriod | integer | 60-1209600 сек. Default: 345600 | | ReceiveMessageWaitTimeSeconds | integer | 0-20 сек. Default: 0 | | RedrivePolicy | string | JSON с deadLetterTargetArn и maxReceiveCount | | VisibilityTimeout | integer | 0-43000 сек. Default: 30 | | FifoQueue | boolean | true/false — создание FIFO очереди | | ContentBasedDeduplication | boolean | true/false — дедупликация (FIFO) | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | QueueUrl | string | URL созданной очереди | **Ошибки:** - 400 `QueueDeletedRecently` — очередь удалена недавно, ждать 60 сек - 400 `QueueAlreadyExists` — очередь уже существует --- #### DeleteQueue Удаление очереди. Процесс занимает до 60 секунд. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди (чувствителен к регистру) | **Выходные параметры:** - Нет полей **Ошибки:** - Только стандартные --- #### GetQueueAttributes Получение атрибутов очереди. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | AttributeNames.N | array | Нет | Список запрашиваемых атрибутов | **Значения AttributeNames:** - `All` — все атрибуты - `ApproximateNumberOfMessages` — ориентировочное количество готовых сообщений - `ApproximateNumberOfMessagesDelayed` — отложенные сообщения - `ApproximateNumberOfMessagesNotVisible` — сообщения в процессе передачи - `CreatedTimestamp` — время создания (epoch time) - `DelaySeconds` - `LastModifiedTimestamp` — время последнего изменения (epoch time) - `MaximumMessageSize` - `MessageRetentionPeriod` - `QueueArn` — ARN очереди - `ReceiveMessageWaitTimeSeconds` - `RedrivePolicy` — политика DLQ - `VisibilityTimeout` - `FifoQueue` — флаг FIFO - `ContentBasedDeduplication` — флаг дедупликации **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | Attributes.N.* | array | Массив атрибутов (Name, Value) | **Ошибки:** - 400 `InvalidAttributeName` — неверное имя атрибута --- #### GetQueueUrl Получение URL очереди по имени. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueName | string | Да | Имя очереди (макс 80 символов, чувствителен к регистру) | | QueueOwnerAWSAccountId | string | Нет | Параметр игнорируется | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | QueueUrl | string | URL очереди | **Ошибки:** - 400 `NonExistentQueue` — очередь не существует --- #### ListQueues Получение списка очередей в каталоге (макс 1000). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueNamePrefix | string | Нет | Префикс для фильтрации (чувствителен к регистру) | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | QueueUrl.N | array | Массив URL очередей (до 1000) | **Ошибки:** - Только стандартные --- #### PurgeQueue Очистка очереди (удаление всех сообщений). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди (чувствителен к регистру) | **Выходные параметры:** - Нет полей **Ошибки:** - 400 `NonExistentQueue` — очередь не существует - 403 `PurgeQueueInProgress` — PurgeQueue уже вызывали за последние 60 сек --- #### SetQueueAttributes Изменение атрибутов очереди (может занять до 60 сек). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | Attributes.N.* | список | Да | Список атрибутов | **Поддерживаемые атрибуты:** - DelaySeconds - MaximumMessageSize - MessageRetentionPeriod - ReceiveMessageWaitTimeSeconds - RedrivePolicy - VisibilityTimeout - ContentBasedDeduplication (только FIFO) **Выходные параметры:** - Нет полей **Ошибки:** - 400 `InvalidAttributeName` — неверное имя атрибута --- #### TagQueue Добавление/изменение меток очереди (может занять до 60 сек). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | Tags.N.* | список | Да | Список меток (Tag.N.Key, Tag.N.Value) | **Выходные параметры:** - Нет полей **Ошибки:** - Только стандартные --- #### UntagQueue Удаление меток очереди (может занять до 60 сек). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | TagKeys.N | array | Да | Список ключей для удаления (TagKey.N) | **Выходные параметры:** - Нет полей **Ошибки:** - Только стандартные --- ### Управление сообщениями #### SendMessage Отправка одного сообщения в очередь. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | MessageBody | string | Да | Тело сообщения (макс 256 КБ). XML/JSON/text | | DelaySeconds | integer | Нет | 0-900 сек отложки | | MessageAttributeName.N / MessageAttributeValue.N | array | Нет | Пользовательские атрибуты | | MessageDeduplicationId | string | Да (FIFO) | Макс 128 символов | | MessageGroupId | string | Да (FIFO) | Макс 128 символов | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | MD5OfMessageBody | string | MD5 хэш тела | | MD5OfMessageAttributes | string | MD5 хэш атрибутов | | MessageId | string | Id отправленного сообщения | | SequenceNumber | string | Номер в FIFO (только FIFO) | **Ошибки:** - 400 `UnsupportedOperation` — неподдерживаемая операция - 400 `InvalidMessageContents` — запрещённые символы --- #### SendMessageBatch Отправка до 10 сообщений одновременно (макс 256 КБ общий размер). **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | SendMessageBatchRequestEntry.N | array | Да | Массив до 10 сообщений | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | BatchResultErrorEntry.N | array | Ошибки отправки | | SendMessageBatchResultEntry.N | array | Id, MD5, MessageId успешных | **Ошибки:** - 400 `BatchEntryIdsNotDistinct` — одинаковые Id - 400 `BatchRequestTooLong` — общая длина превышена - 400 `EmptyBatchRequest` — нет сообщений - 400 `InvalidBatchEntryId` — неправильный Id - 400 `TooManyEntriesInBatchRequest` — >10 сообщений - 400 `UnsupportedOperation` — неподдерживаемая операция --- #### ReceiveMessage Получение 1-10 сообщений из очереди. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | MaxNumberOfMessages | string | Нет | 1-10 сообщений. Default: 1 | | MessageAttributeName.N | array | Нет | Имена атрибутов (макс 256 символов) | | ReceiveRequestAttemptId | string | Нет | Id для повтора попытки (FIFO) | | VisibilityTimeout | string | Нет | Таймаут видимости | | WaitTimeSeconds | string | Нет | Long-polling ожидание (0-20 сек) | **Атрибуты сообщения:** - `All` — все атрибуты - `ApproximateFirstReceiveTimestamp` — время первого получения - `ApproximateReceiveCount` — количество получений без удаления - `SenderId` — Id отправителя (IAM) - `SentTimestamp` — время отправки - `MessageDeduplicationId` — Id дедупликации (FIFO) - `MessageGroupId` — Id группы (FIFO) - `SequenceNumber` — номер в группе (FIFO) **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | Message | array | Массив сообщений | **Ошибки:** - 403 `OverLimit` — превышен один из установленных лимитов --- #### DeleteMessage Удаление одного сообщения из очереди. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | ReceiptHandle | string | Да | Id получения из ReceiveMessage | **Выходные параметры:** - Нет полей **Ошибки:** - 400 `InvalidIdFormat` — некорректный формат ReceiptHandle - 400 `ReceiptHandleIsInvalid` — неверный ReceiptHandle --- #### DeleteMessageBatch Удаление до 10 сообщений одновременно. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | DeleteMessageBatchRequestEntry.N | array | Да | Массив до 10 сообщений (Id, ReceiptHandle) | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | BatchResultErrorEntry.N | array | Ошибки удаления | | DeleteMessageBatchResultEntry.N | array | Id успешно удаленных | **Ошибки:** - 400 `BatchEntryIdsNotDistinct` — одинаковые Id - 400 `EmptyBatchRequest` — нет сообщений - 400 `InvalidBatchEntryId` — неправильный Id - 400 `TooManyEntriesInBatchRequest` — >10 сообщений --- #### ChangeMessageVisibility Изменение таймаута видимости сообщения в обработке. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди | | ReceiptHandle | string | Да | Id получения | | VisibilityTimeout | integer | Да | 0-43200 сек новый таймаут | **Выходные параметры:** - Нет полей **Ошибки:** - 400 `MessageNotInflight` — сообщение не в обработке - 400 `ReceiptHandleIsInvalid` — неверный ReceiptHandle **Примечание:** Суммарная длительность таймаута не может быть более 12 часов. --- #### ChangeMessageVisibilityBatch Изменение таймаута видимости до 10 сообщений одновременно. **Параметры запроса:** | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | QueueUrl | string | Да | URL очереди (чувствителен к регистру) | | ChangeMessageVisibilityBatchRequestEntry.N | array | Да | Массив до 10 сообщений | **Выходные параметры:** | Параметр | Тип | Описание | |---|---|---| | BatchResultErrorEntry.N | array | Ошибки | | ChangeMessageVisibilityBatchResultEntry.N | array | Id успешно измененных | **Ошибки:** - 400 `BatchEntryIdsNotDistinct` — одинаковые Id - 400 `EmptyBatchRequest` — нет сообщений - 400 `InvalidBatchEntryId` — неправильный Id - 400 `TooManyEntriesInBatchRequest` — >10 сообщений --- ## Типы данных ### BatchResultErrorEntry Описание ошибки выполнения действия из группы. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | Code | string | Да | Код ошибки | | Id | string | Да | Id сообщения в группе | | Message | string | Нет | Описание ошибки | | SenderFault | boolean | Да | Ошибка на стороне отправителя | --- ### ChangeMessageVisibilityBatchRequestEntry Элемент массива для ChangeMessageVisibilityBatch. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | Id | string | Да | Id ReceiptHandle, уникален в пределе запроса | | ReceiptHandle | string | Да | Id получения сообщения | | VisibilityTimeout | boolean | Нет | Новый таймаут в секундах | --- ### ChangeMessageVisibilityBatchResultEntry Результат для одного сообщения в ChangeMessageVisibilityBatch. | Параметр | Тип | Описание | |---|---|---| | Id | string | Id сообщения с измененным таймаутом | --- ### DeleteMessageBatchRequestEntry Элемент массива для DeleteMessageBatch. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | Id | string | Да | Id, уникален в пределе запроса | | ReceiptHandle | string | Да | Id получения сообщения | --- ### DeleteMessageBatchResultEntry Результат для одного сообщения в DeleteMessageBatch. | Параметр | Тип | Описание | |---|---|---| | Id | string | Id удаленного сообщения | --- ### Message Сообщение из ReceiveMessage. | Параметр | Тип | Описание | |---|---|---| | Attribute.N | array | Системные атрибуты (ApproximateReceiveCount, ApproximateFirstReceiveTimestamp, MessageDeduplicationId, MessageGroupId, SenderId, SentTimestamp, SequenceNumber) | | Body | string | Тело сообщения | | MD5OfBody | string | MD5 хэш тела | | MD5OfMessageAttributes | string | MD5 хэш атрибутов | | MessageAttribute | array | Пользовательские атрибуты (MessageAttributeValue) | | MessageId | string | Уникальный Id | | ReceiptHandle | string | Id получения (новый при каждом получении) | --- ### MessageAttributeValue Значение пользовательского атрибута сообщения. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | BinaryListValue.N | array | Нет | Не реализовано | | BinaryValue | base64 | Нет | Двоичные данные | | DataType | string | Да | String, Number или Binary (для Number используется StringValue) | | StringListValue.N | string | Нет | Не реализовано | | StringValue | string | Нет | Строка UTF-8 | **Примечание:** Имя, тип, значение и тело не могут быть пустыми. Суммарный размер всех частей ≤ 256 КБ. --- ### SendMessageBatchRequestEntry Элемент массива для SendMessageBatch. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | DelaySeconds | integer | Нет | Отложка в секундах | | Id | string | Да | Id сообщения в списке | | MessageAttribute | string | Нет | Атрибуты (имя, тип, значение) | | MessageBody | string | Нет | Тело сообщения | | MessageDeduplicationId | string | Нет | Id дедупликации | | MessageGroupId | string | Нет | Id группы (только FIFO) | --- ### SendMessageBatchResultEntry Результат для одного сообщения в SendMessageBatch. | Параметр | Тип | Обязательный | Описание | |---|---|---|---| | Id | string | Да | Id сообщения в группе | | MD5OfMessageAttributes | string | Нет | MD5 хэш атрибутов | | MD5OfMessageBody | string | Да | MD5 хэш тела | | MessageId | string | Да | Id сообщения | | SequenceNumber | string | Нет | Номер (128 бит, только FIFO) | --- ## Стандартные ошибки Ошибки, возвращаемые всеми методами: | HTTP | Код ошибки | Описание | |---|---|---| | 400 | AccessDeniedException | Недостаточно прав для выполнения действия | | 400 | IncompleteSignature | Подпись запроса не соответствует стандартам AWS | | 500 | InternalFailure | Неизвестная ошибка | | 400 | InvalidAction | Неизвестное значение параметра Action | | 403 | InvalidClientTokenId | Неверный ключ сервисного аккаунта | | 400 | InvalidParameterCombination | Одновременно используются несовместимые параметры | | 400 | InvalidParameterValue | Параметр задан неверно или вне диапазона | | 400 | InvalidQueryParameter | Используется несуществующий параметр | | 404 | MalformedQueryString | Синтаксическая ошибка в запросе | | 400 | MissingAction | Не указан параметр Action | | 403 | MissingAuthenticationToken | Не указан Id ключа сервисного аккаунта | | 400 | MissingParameter | Отсутствует обязательный параметр | | 400 | OptInRequired | Id ключа требует подписки на сервис | | 400 | RequestExpired | Запрос получен через >15 минут от времени в запросе | | 503 | ServiceUnavailable | Сервис недоступен | | 403 | ThrottlingException | Ограничение по числу запросов | | 400 | ValidationError | Значения не соответствуют ограничениям | --- ## Примечания 1. **FIFO очереди:** - Имя должно оканчиваться на `.fifo` - Требуют `MessageGroupId` для SendMessage - Требуют `MessageDeduplicationId` для дедупликации - При ReceiveMessage из одной группы за вызов получается только одно сообщение - Сообщения обрабатываются в порядке отправления 2. **Таймауты:** - VisibilityTimeout: 0-43000 сек, при смене максимум до 12 часов суммарно - ReceiveMessage с WaitTimeSeconds — long-polling (0-20 сек) 3. **Batch операции:** - Максимум 10 элементов в batch - SendMessageBatch: макс 256 КБ общий размер - Результаты проверяются индивидуально (могут быть успехи и ошибки) 4. **Удаление очередей:** - Процесс может занять до 60 секунд - Новую очередь с таким же именем можно создать через 60 сек после удаления 5. **ARN очереди:** - Используется в RedrivePolicy - Может быть получен через GetQueueAttributes с параметром QueueArn --- ## Audit Trails (Аудитные логи) В Audit Trails для Yandex Message Queue поддерживается отслеживание событий уровня конфигурации (Control Plane). ### Формат event_type ``` yandex.cloud.audit.ymq.<имя_события> ``` ### События уровня конфигурации | Имя события | Описание | |---|---| | CreateMessageQueue | Создание очереди сообщений | | DeleteMessageQueue | Удаление очереди сообщений | | UpdateMessageQueue | Изменение очереди сообщений | --- ## Monitoring (Метрики) В Yandex Monitoring поддерживаются метрики сервиса Message Queue. **Общая метка для всех метрик:** `service=message-queue` ### Метрики HTTP API | Имя метрики | Тип, единицы измерения | Описание | Метка | |---|---|---|---| | api.http.errors_count_per_second | DGAUGE, ошибки/с | Количество ошибок выполнения запросов в секунду | method — метод API | | api.http.request_duration_milliseconds | DGAUGE, миллисекунды | Продолжительность выполнения запросов | method — метод API | | api.http.requests_count_per_second | DGAUGE, запросы/с | Количество обработанных запросов в секунду | method — метод API | ### Метрики сервиса | Имя метрики | Тип, единицы измерения | Описание | |---|---|---| | queue.messages.client_processing_duration_milliseconds | DGAUGE, миллисекунды | Время обработки сообщений получателем | | queue.messages.deduplicated_count_per_second | DGAUGE, сообщения/с | Частота дедупликации сообщений | | queue.messages.deleted_count_per_second | DGAUGE, сообщения/с | Частота удаления сообщений из очереди | | queue.messages.empty_receive_attempts_count_per_second | DGAUGE, попытки/с | Кол-во попыток получения пустого сообщения в сек | | queue.messages.inflight_count | DGAUGE, штуки | Кол-во сообщений в обработке (активных) | | queue.messages.oldest_age_milliseconds | DGAUGE, секунды | Время хранения наиболее раннего сообщения в очереди | | queue.messages.purged_count_per_second | DGAUGE, сообщения/с | Частота удаления сообщений методом PurgeQueue | | queue.messages.receive_attempts_count_rate | DGAUGE, штуки | Количество попыток получения сообщений из очереди | | queue.messages.received_bytes_per_second | DGAUGE, байты/с | Общий размер полученных сообщений в сек | | queue.messages.received_count_per_second | DGAUGE, сообщения/с | Количество полученных сообщений в сек | | queue.messages.request_timeouts_count_per_second | DGAUGE, ошибки/с | Кол-во ошибок выполнения запросов ReceiveMessage | | queue.messages.reside_duration_milliseconds | DGAUGE, миллисекунды | Время обработки сообщений в очереди | | queue.messages.sent_bytes_per_second | DGAUGE, байты/с | Общий размер отправленных сообщений в сек | | queue.messages.sent_count_per_second | DGAUGE, сообщения/с | Количество отправленных сообщений в сек | | queue.messages.stored_count | DGAUGE, штуки | Количество сообщений в очереди в текущий момент | --- ## Часто задаваемые вопросы ### Ограничения и лимиты **Q: Что означает ошибка «Cannot create queue: Too many queues»?** A: Достигнут лимит на максимальное количество очередей. Для увеличения лимита обратитесь в техническую поддержку с указанием: - Идентификателя облака - Нужного количества очередей - Назначения (зачем требуется такое количество) **Q: Какой максимальный размер сообщения?** A: Максимальный размер сообщения — 256 КБ. О других ограничениях см. в разделе Квоты и лимиты. ### Доступ и аутентификация **Q: Мне нужна регистрация в Amazon для использования AWS CLI с Message Queue?** A: Нет, AWS CLI можно использовать без регистрации и ключей AWS. Подробнее см. раздел Инструменты. **Q: Какой ключ доступа требуется для работы с Message Queue?** A: Требуется статический ключ доступа. Создайте его в консоли облака. **Q: Что вводить в поле Default output format при настройке AWS CLI?** A: Оставьте это поле пустым. Укажите только идентификатор ключа и секретный ключ. ### Операция и обслуживание **Q: Какой SLA для Message Queue?** A: Message Queue имеет SLA 99,90% на доступность сервиса. **Q: Могу ли я мониторить Message Queue через Prometheus?** A: Да, можно экспортировать метрики в Prometheus и получить список метрик для различных объектов. **Q: Почему все мои сообщения висят в очереди со статусом «В обработке» продолжительное время?** A: Это может быть связано с большим таймаутом видимости в настройках очереди. VisibilityTimeout — это время, на которое сообщение скрывается из очереди после чтения. ### Обработка сообщений **Q: Как удалить сообщение и его дубль из очереди?** A: Дубликаты сообщений не записываются в течение 5 минут. Если прошло 5 минут, дубликат удаляется по его собственному ReceiptHandle. Дубли при чтении указывают на то, что сервис не успел удалить сообщение по истечении taймаута видимости — продлите таймаут. ### Диагностикаи логи **Q: Могу ли я получить логи своей работы в сервисах?** A: Да, обратитесь в техническую поддержку для получения информации о работе с вашими ресурсами из логов сервисов Yandex Cloud.