---
metadata:
  - name: generator
    content: Diplodoc Platform v5.56.0
alternate:
  - https://ydb.tech/docs/en/reference/sqs-api/examples.md?version=main
  - https://ydb.tech/docs/ru/reference/sqs-api/examples.md?version=main
  - href: ru/reference/sqs-api/examples.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
sourcePath: ru/core/reference/sqs-api/examples.md
---
> **Documentation Index:** Fetch the complete configuration index at https://ydb.tech/docs/ru/llms.txt

# Примеры работы с топиком через Amazon SQS API
<!-- markdownlint-disable blanks-around-fences -->

В этой статье приведены примеры работы с [топиками](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main) с использованием Amazon SQS API с помощью [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html).

<!-- source: ru/reference/sqs-api/_includes/limitations.md -->
{% note info %}

Работа с топиками по Amazon SQS-протоколу поддерживается только для [Amazon JSON protocol](https://docs.amazonaws.cn/en_us/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-json-faqs.html).

{% endnote %}
<!-- endsource: ru/reference/sqs-api/_includes/limitations.md -->

<!-- source: ru/reference/sqs-api/_includes/examples_prerequisites.md -->
Перед выполнением примеров настройте доступ к Amazon SQS API (в Open Source-версии — отключите требование аутентификации, см. раздел про [аутентификацию](https://ydb.tech/docs/ru/reference/sqs-api/auth.md?version=main)).

Если вы используете AWS CLI, убедитесь, что он не требует настроенных AWS‑креденшалов: либо добавьте `--no-sign-request` к командам, либо задайте любые значения `AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`.
<!-- endsource: ru/reference/sqs-api/_includes/examples_prerequisites.md -->

## Формирование endpoint для подключения

Endpoint для доступа к Amazon SQS API формируется следующим образом:

`https://{db-balancer}:{port}/{database}`

Где:

- `db-balancer` — DNS-имя HTTPS-балансировщика, у которого в качестве backend указаны compute-ноды базы данных (или адрес узла/сервиса, где запущен HTTP Proxy);
- `port` — порт, на котором доступен HTTP Proxy;
- `database` — полный путь базы данных, в которой находятся топики.

Этот endpoint указывается в AWS CLI через параметр `--endpoint`.

{% note info %}

В примерах используется endpoint `https://my_db.balancer.example.com:8443/Root/my_db`. В нём:

- `my_db.balancer.example.com` — DNS-имя балансировщика, по которому доступен Amazon SQS-протокол;
- `8443` — сетевой порт;
- `/Root/my_db` — имя базы данных.

{% endnote %}

## Создание топика

Для создания топика выполните команду:

```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" \
  sqs create-queue --queue-name "my_topic"
```

После выполнения команды будет создан [топик](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main) с указанным именем и [разделяемым (общим) читателем](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main#shared-consumer) с именем `ydb-sqs-consumer`. Проверить существование топика можно с помощью команды [scheme describe](https://ydb.tech/docs/ru/reference/ydb-cli/commands/scheme-describe.md?version=main) [YDB CLI](https://ydb.tech/docs/ru/reference/ydb-cli/index.md?version=main):

```shell
ydb -e grpcs://my_db.balancer.example.com:2135 -d /Root/my_db scheme describe my_topic
```

Для создания FIFO-очереди используйте атрибут `FifoQueue=true`. Для FIFO-очередей рекомендуется заканчивать имя на `.fifo`, чтобы соответствовать соглашению об именовании Amazon SQS:

```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" \
  sqs create-queue \
  --queue-name "my_topic.fifo" \
  --attributes FifoQueue=true
```

После выполнения команды будет создан [топик](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main) с именем `my_topic.fifo` и [разделяемым (общим) читателем](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main#shared-consumer) с именем `ydb-sqs-consumer`, у которого включено сохранение порядка сообщений.

## Получение списка топиков

Для получения списка топиков, с которыми возможна работа по протоколу Amazon SQS, выполните команду:

```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" sqs list-queues
```

### Получение QueueUrl топика

Чтобы получить `QueueUrl` топика, выполните команду:

```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

aws --endpoint "$ENDPOINT" sqs get-queue-url \
  --queue-name "my_topic@my_consumer"
```

Где:

- `{queue_name}` — значение параметра `--queue-name`, имя Amazon SQS-очереди в формате `{topic_name}@{consumer_name}`. Если [разделяемый (общий) читатель](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main#shared-consumer) имеет имя `ydb-sqs-consumer`, достаточно указать только `{topic_name}`;
- `{topic_name}` — имя топика с путём от корня базы данных, в которой он создан, например `production/order` (топик `order` в директории `production`);
- `{consumer_name}` — имя [разделяемого (общего) читателя](https://ydb.tech/docs/ru/concepts/datamodel/topic.md?version=main#shared-consumer) на топике, например `ydb-sqs-consumer`.

В примере выше `my_topic` — это `{topic_name}`, а `my_consumer` — `{consumer_name}`.


## Запись в топик и чтение из топика

Для операций чтения и записи AWS CLI использует параметр `--queue-url`. Его можно получить через `get-queue-url`.

Ниже приведён пример:

- получение `QueueUrl`;
- запись сообщения;
- чтение сообщения.

```shell
ENDPOINT="https://my_db.balancer.example.com:8443/Root/my_db"

# получить QueueUrl
QUEUE_URL="$(aws --endpoint "$ENDPOINT" sqs get-queue-url --queue-name "my_topic" --query 'QueueUrl' --output text)"

# записать сообщение в топик
aws --endpoint "$ENDPOINT" sqs send-message \
  --queue-url "$QUEUE_URL" \
  --message-body "hello from aws cli"

# прочитать сообщение (long polling)
aws --endpoint "$ENDPOINT" sqs receive-message \
  --queue-url "$QUEUE_URL" \
  --wait-time-seconds 20 \
  --max-number-of-messages 1
```