Nail/SQS-service
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8c5c779a0c8ded9999247e564898dbeb956508eb
SQS-service/doc/api/yandex-message-queue-api-reference.md
T

31 KiB
Raw Blame History

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 version="1.0" encoding="UTF-8"?>
<ActionResponse>
   <ActionResult>
      <!-- Результаты зависят от метода -->
   </ActionResult>
   <ResponseMetadata>
      <RequestId>UUID</RequestId>
   </ResponseMetadata>
</ActionResponse>

Ошибочный ответ:

<ErrorResponse>
   <Error>
      <Type>Sender|Receiver</Type>
      <Code>ошибка</Code>
      <Message>Описание</Message>
   </Error>
   <RequestId>UUID</RequestId>
</ErrorResponse>

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.

Reference in New Issue View Git Blame Copy Permalink