Examples of working with topics via SQS API

This article provides examples of working with topics using the SQS API via AWS CLI.

Before running the examples, configure access to the SQS API (in the Open Source version, disable the authentication requirement, see the section on authentication).

If you use AWS CLI, make sure it does not require configured AWS credentials: either add --no-sign-request to the commands, or set any values for AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY.

Forming the endpoint for connection

The endpoint for accessing the SQS API is formed as follows:

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

Where:

• db-balancer — DNS name of the HTTPS load balancer whose backend includes the database compute nodes (or the address of the node/service where the HTTP Proxy is running).
• port — port on which the HTTP Proxy is available.
• database — full path of the database where the topics are located.

This endpoint is specified in AWS CLI via the --endpoint parameter.

Creating a topic

To create a topic, run the command:

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

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

After executing the command, a topic with the specified name and a shared (common) reader named ydb-sqs-consumer will be created. You can verify the topic's existence using the scheme describe command of the YDB CLI:

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

To create a FIFO queue, use the FifoQueue=true attribute. For FIFO queues, it is recommended to end the name with .fifo to comply with the Amazon SQS naming convention:

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

After executing the command, a topic named my_topic.fifo and a shared (common) reader named ydb-sqs-consumer will be created, with message order preservation enabled.

Getting a list of topics

To get a list of topics that can be accessed via the SQS protocol, run the command:

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

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

Writing to a topic and reading from a topic

For read and write operations, AWS CLI uses the --queue-url parameter. It can be obtained via get-queue-url.

Below is an example:

• obtaining QueueUrl
• writing a message
• reading a message

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

# get QueueUrl
QUEUE_URL="$(aws --endpoint "$ENDPOINT" sqs get-queue-url --queue-name "my_topic" --query 'QueueUrl' --output text)"

# write a message to a topic
aws --endpoint "$ENDPOINT" sqs send-message \
  --queue-url "$QUEUE_URL" \
  --message-body "hello from aws cli"

# read a message (long polling)
aws --endpoint "$ENDPOINT" sqs receive-message \
  --queue-url "$QUEUE_URL" \
  --wait-time-seconds 20 \
  --max-number-of-messages 1