В бессерверном режиме работы YDB поддерживает Document API — HTTP API, совместимое с Amazon DynamoDB. Это низкоуровневый API для работы с таблицами и создания, чтения, изменения и удаления данных. С помощью этого API можно выполнять операции над документными таблицами, совместимыми с AWS DynamoDB.

Для работы с таблицами в Document API поддерживаются следующие методы:

Для работы с элементами таблиц поддерживаются следующие методы:

С подробным описанием сигнатур каждого метода вы можете познакомиться в справочнике API.

Совместимость API даёт возможность пользователю работать с YDB при помощи инструментов AWS, таких как утилиты командной строки AWS CLI и AWS SDK для всех языков программирования, а также переносить свои приложения из AWS DynamoDB в YDB.

Давайте пройдём базовый сценарий работы с данными: создадим таблицу, запишем в неё данные и прочитаем их.

Создайте базу данных YDB в бессерверном режиме.

Перейдите на вкладку Обзор созданной БД.

Сохраните значение эндпойнта, указанное в блоке Document API эндпоинт.

Для удобства сохраните значение эндпойнта в переменной окружения с помощью команды export.

export ENDPOINT=<значение_endpoint>

Рекомендованным способом использования Document API являются AWS CLI и AWS SDK, с которыми вы познакомитесь в дальнейших уроках. Здесь же мы используем утилиту cURL как простой пример применения низкоуровневого HTTP API.

Выполните команду:

curl \
  -H 'X-Amz-Target: DynamoDB_20120810.CreateTable' \
  -H "Authorization: Bearer $(yc iam create-token)" \
  -H "Content-Type: application/json" \
  -d '{"TableName": "docapitest/series","AttributeDefinitions":[{"AttributeName": "series_id", "AttributeType": "N"},{"AttributeName": "title", "AttributeType": "S"}],"KeySchema":[{"AttributeName": "series_id", "KeyType": "HASH"},{"AttributeName": "title", "KeyType": "RANGE"}]}' \
  $ENDPOINT

В консоли управления убедитесь, что таблица series появилась в директории docapitest указанной базы.

Добавьте запись в базу с помощью следующей команды:

curl \
  -H 'X-Amz-Target: DynamoDB_20120810.PutItem' \
  -H "Authorization: Bearer $(yc iam create-token)" \
  -H "Content-Type: application/json" \
  -d '{"TableName": "docapitest/series", "Item": {"series_id": {"N": "1"}, "title": {"S": "IT Crowd"}, "series_info": {"S": "The IT Crowd is a British sitcom produced by Channel 4, written by Graham Linehan, produced by Ash Atalla and starring Chris ODowd, Richard Ayoade, Katherine Parkinson, and Matt Berry."}, "release_date": {"S": "2006-02-03"}}}' \
  $ENDPOINT

Прочитайте запись с помощью команды:

curl \
  -H 'X-Amz-Target: DynamoDB_20120810.GetItem' \
  -H "Authorization: Bearer $(yc iam create-token)" \
  -H "Content-Type: application/json" \
  -d '{"TableName": "docapitest/series", "Key": {"series_id":{"N":"1"}, "title":{"S":"IT Crowd"}}}' \
  $ENDPOINT

Удалите созданную ранее таблицу.

curl \
  -H 'X-Amz-Target: DynamoDB_20120810.DeleteTable' \
  -H "Authorization: Bearer $(yc iam create-token)" \
  -H "Content-Type: application/json" \
  -d '{"TableName": "docapitest/series"}' \
  $ENDPOINT

При работе через Document API стоимость обработки каждого документа равна стоимости единицы запроса в RU, умноженной на размер документа в блоках. Размер в блоках равен размеру в байтах, делённому на размер блока и округлённому в большую сторону. Запрос несуществующего документа приравнивается к чтению документа размером в 1 блок.

Если запрос обрабатывает несколько документов (например BatchGetItem), итоговая стоимость равна сумме стоимостей по каждому документу. Операции со схемой данных, такие как CreateTable, DeleteTable, DescribeTable, ListTables, не тарифицируются. В таблице ниже приведён пример расчёта стоимости для различных вызовов Document API.