Связаться с намиПодключиться

Разработка CRUD API для сервиса фильмов

Статья создана
Улучшена
Обновлена 22 октября 2024 г.

С помощью serverless-технологий можно создать CRUD API для сервиса, который хранит данные о фильмах.

Реализация CRUD API использует контейнер Yandex Serverless Containers, который предназначен для работы с базой данных фильмов, развернутой в Yandex Managed Service for YDB.

Контейнер конфигурируется в спецификации API-шлюза Yandex API Gateway по стандарту OpenAPI 3.0 для выполнения определенных HTTP-запросов.

Контейнер будет взаимодействовать с Managed Service for YDB и обрабатывать внешние HTTP-запросы через API-шлюз с использованием HTTP API, совместимого с Amazon DynamoDB. Язык кода приложения CRUD API — TypeScript, среда выполнения — Node.js 16.

Чтобы развернуть проект:

  1. Настройте окружение.
  2. Инициализируйте Terraform.
  3. Создайте базу данных Managed Service for YDB.
  4. Реализуйте CRUD-операции.
  5. Разработайте REST API.
  6. Проверьте работу созданного CRUD API.

Если созданные ресурсы больше не нужны, удалите их.

Перед началом работы

Зарегистрируйтесь в Yandex Cloud и создайте платежный аккаунт:

  1. Перейдите в консоль управления, затем войдите в Yandex Cloud или зарегистрируйтесь.
  2. На странице Yandex Cloud Billing убедитесь, что у вас подключен платежный аккаунт, и он находится в статусе ACTIVE или TRIAL_ACTIVE. Если платежного аккаунта нет, создайте его и привяжите к нему облако.

Если у вас есть активный платежный аккаунт, вы можете создать или выбрать каталог, в котором будет работать ваша инфраструктура, на странице облака.

Подробнее об облаках и каталогах.

В стоимость ресурсов для работы CRUD API входят:

Настройте окружение

  1. Установите утилиту WSL для использования окружения Linux.
  2. Запустите подсистему Linux (по умолчанию — Ubuntu).
  3. Настройте окружение так, как описано в инструкции для операционной системы Linux.

Примечание

Если вы используете дистрибутив, отличный от Ubuntu, установите указанные утилиты с помощью команд вашего пакетного менеджера.

  1. Последовательно установите следующие утилиты с помощью команд в терминале:

    • Curl и Git:

      sudo apt-get install curl git -y

    • WebStorm или другая среда разработки с поддержкой TypeScript:

      sudo snap install webstorm --classic

    • Node.js не ниже версии 16.9.1:

      curl --silent --location https://deb.nodesource.com/setup_16.x | sudo -E bash
sudo apt-get install nodejs
node -v
npm -v

    • TypeScript:

      sudo npm install -g typescript

    • Yandex Cloud CLI:

      curl https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
exec -l $SHELL
yc version

    • AWS CLI:

      curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" --output "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

    • Docker:

      sudo apt-get update
sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release -y
curl --fail --silent --show-error --location https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu \
$(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io -y
sudo docker run hello-world

  2. Установите Terraform не ниже версии 1.0.8.

  3. Создайте профиль Yandex Cloud CLI с базовыми параметрами.

  4. Настройте AWS CLI.

  5. Настройте управление Docker от имени непривилегированного пользователя:

    sudo groupadd docker
sudo usermod -aG docker $USER
newgrp docker
docker run hello-world

  1. Последовательно установите следующие утилиты с помощью команд в терминале:

    • Homebrew:

      /bin/bash -c "$(curl --fail --silent --show-error --location https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    • Curl и Git:

      brew install curl git

    • WebStorm или другая среда разработки с поддержкой TypeScript:

      brew install --cask webstorm

    • Node.js не ниже версии 16.9.1:

      brew install node
node -v
npm -v

    • TypeScript:

      npm install -g typescript

    • Yandex Cloud CLI:

      curl https://storage.yandexcloud.net/yandexcloud-yc/install.sh | bash
exec -l $SHELL
yc version

    • AWS CLI:

      curl "https://awscli.amazonaws.com/AWSCLIV2.pkg" --output "AWSCLIV2.pkg"
sudo installer -pkg AWSCLIV2.pkg -target /

    • Docker:

      brew install --cask docker

  2. Установите Terraform не ниже версии 1.0.8.

  3. Создайте профиль с базовыми параметрами.

  4. Настройте AWS CLI.

Инициализируйте Terraform

  1. Склонируйте репозиторий с исходными файлами для проекта CRUD API:

    git clone https://github.com/yandex-cloud-examples/yc-practicum-serverless-web-application-movie-website.git

    Откройте директорию проекта в WebStorm и изучите исходные файлы.

  2. Перейдите в директорию deploy:

    cd <путь_к_директории_deploy>

  3. Узнайте имя активного профиля (ACTIVE) интерфейса командной строки Yandex Cloud CLI. В терминале выполните команду:

    yc config profile list

  4. Получите параметры активного профиля:

    yc config profile get <имя_профиля>

  5. Скопируйте в файл provider.tf полученные параметры:

  6. Экспортируйте идентификатор каталога в переменную окружения:

    export FOLDER_ID=<идентификатор_каталога>
echo $FOLDER_ID

  7. Выполните команду инициализации Terraform:

    terraform init

    Примечание

    Выполняйте все команды Terraform в директории deploy.

Создайте базу данных Managed Service for YDB

В проекте используется база данных YDB в режиме serverless. БД состоит из двух таблиц: movies для хранения информации о фильмах и votes для хранения оценок пользователей. Каждая запись в таблице содержит идентификатор и конечный набор атрибутов.

  1. Конфигурация Terraform для создания БД описана в файле ydb.tf. Создайте базу данных:

    terraform apply -target=yandex_ydb_database_serverless.movies_database

    Подтвердите создание ресурсов: введите в терминале yes и нажмите Enter.

    В выводе команды будут указаны переменные:

    • movies_database_document_api_endpoint — Document API эндпоинт базы данных.
    • movies_database_path — относительный путь к базе данных.

    Проверить, что БД movies-database успешно создана, можно в консоли управления или с помощью команды CLI yc ydb database list.

  2. Экспортируйте в переменные окружения значения movies_database_document_api_endpoint и movies_database_path из вывода предыдущей команды:

    export DOCUMENT_API_ENDPOINT=<Document_API_эндпоинт_базы_данных>
echo $DOCUMENT_API_ENDPOINT

export MOVIES_DATABASE_PATH=<относительный_путь_к_базе_данных>
echo $MOVIES_DATABASE_PATH

  3. Создайте в БД movies-database таблицы movies и votes:

    aws dynamodb create-table \
  --table-name movies \
  --attribute-definitions \
    AttributeName=id,AttributeType=N \
    AttributeName=title,AttributeType=S \
    AttributeName=type,AttributeType=S \
    AttributeName=original_title,AttributeType=S \
    AttributeName=original_language,AttributeType=S \
    AttributeName=release_date,AttributeType=S \
    AttributeName=poster_path,AttributeType=S \
    AttributeName=popularity,AttributeType=N \
    AttributeName=video,AttributeType=S \
    AttributeName=vote_count,AttributeType=N \
    AttributeName=vote_average,AttributeType=N \
    AttributeName=genres,AttributeType=S \
    AttributeName=backdrop_path,AttributeType=S \
    AttributeName=adult,AttributeType=S \
    AttributeName=overview,AttributeType=S \
  --key-schema \
    AttributeName=id,KeyType=HASH \
  --global-secondary-indexes \
    "[
      {
        \"IndexName\": \"PopularityIndex\",
        \"KeySchema\": [{\"AttributeName\":\"type\",\"KeyType\":\"HASH\"}, {\"AttributeName\":\"popularity\",\"KeyType\":\"RANGE\"}],
        \"Projection\":{
          \"ProjectionType\":\"ALL\"
        }
      }
    ]" \
  --endpoint ${DOCUMENT_API_ENDPOINT}

aws dynamodb create-table \
  --table-name votes \
  --attribute-definitions \
    AttributeName=id,AttributeType=S \
    AttributeName=user_id,AttributeType=S \
    AttributeName=movie_id,AttributeType=N \
    AttributeName=value,AttributeType=N \
  --key-schema \
    AttributeName=id,KeyType=HASH \
  --global-secondary-indexes \
    "[
      {
        \"IndexName\": \"MovieIndex\",
        \"KeySchema\": [{\"AttributeName\":\"movie_id\",\"KeyType\":\"HASH\"}],
        \"Projection\":{
          \"ProjectionType\":\"ALL\"
        }
      }
    ]" \
  --endpoint ${DOCUMENT_API_ENDPOINT}

  4. Проверьте, что таблицы создались:

    aws dynamodb describe-table \
  --table-name movies \
  --endpoint ${DOCUMENT_API_ENDPOINT}

aws dynamodb describe-table \
  --table-name votes \
  --endpoint ${DOCUMENT_API_ENDPOINT}

    Для каждой таблицы поддерживаются два индекса:

    • В таблице movies — индекс для быстрого поиска фильма по его идентификатору и индекс для сортировки фильмов по популярности.
    • В таблице votes — индекс для поиска оценки пользователя по фильму и индекс для получения всех оценок фильма.

Реализуйте CRUD-операции

Слой для работы с базой данных используется каждый раз, когда необходимо создавать, получать, обновлять или удалять записи. Эти действия называют CRUD-операциями.

Взаимодействие с базой данных через Document API реализовано с помощью библиотеки AWS SDK for JavaScript v3:

  • В файле model.ts через интерфейс TypeScript определены модели фильма Movie и оценки Vote.
  • В файле repository.ts реализованы CRUD-операции для работы с этими сущностями.

При выполнении операций с данными для авторизации используются IAM-токены. Для получения IAM-токена перед выполнением операции вызывается сервис метаданных.

Создайте сервисный аккаунт

  1. Конфигурация Terraform для создания сервисного аккаунта описана в файле sa.tf. Создайте сервисный аккаунт:

    terraform apply -target=yandex_iam_service_account.movies_api_sa

    Подтвердите создание ресурсов: введите в терминале yes и нажмите Enter.

  2. В выводе команды, в переменной movies_api_sa_id, указан идентификатор созданного сервисного аккаунта. Экспортируйте его в переменную окружения:

    export MOVIES_API_SA_ID=<идентификатор_сервисного_аккаунта>
echo $MOVIES_API_SA_ID

  3. Назначьте роли сервисному аккаунту:

    yc resource-manager folder add-access-binding ${FOLDER_ID} \
  --role ydb.admin \
  --subject serviceAccount:${MOVIES_API_SA_ID}

yc resource-manager folder add-access-binding ${FOLDER_ID} \
  --role container-registry.images.puller \
  --subject serviceAccount:${MOVIES_API_SA_ID}

yc resource-manager folder add-access-binding ${FOLDER_ID} \
  --role serverless.containers.invoker \
  --subject serviceAccount:${MOVIES_API_SA_ID}

    Где:

    • --role — назначаемая роль.
    • --subject serviceAccount — идентификатор сервисного аккаунта.

    Роли назначаются сервисному аккаунту для следующих действий:

    Роли назначаются на весь каталог, а не на каждый ресурс в отдельности.

Скомпилируйте исходный код приложения на TypeScript

  1. Перейдите в корневую директорию репозитория и установите необходимые зависимости:

    cd <путь_к_директории_sls-web-application>
npm ci

    После выполнения команды в проекте появится директория node_modules, в которой будут находиться все необходимые зависимости.

  2. Запустите сборку проекта:

    npm run build

    После выполнения команды в проекте появится директория dist, в которой будут находиться скомпилированные JS-файлы.

Разработайте REST API

В файле openapi/api.yaml подготовлена спецификация OpenAPI, в которой описаны основные операции для работы с фильмами и оценками.

Для реализации сервиса в соответствии с этой спецификацией используется библиотека OpenAPI Backend в связке с фреймворком Express. В файле app.ts описаны необходимые классы и маппинг операций, а также запуск HTTP-сервиса.

Разверните приложение в Serverless Containers

Соберите приложение в виде Docker-образа и запустите его в Serverless Containers:

  1. В спецификации OpenAPI api.yaml, в поле x-yc-apigateway.service_account_id, укажите идентификатор сервисного аккаунта, который создали ранее.

  2. В файле container-registry.tf описана конфигурация реестра и репозитория, в которые будет загружаться Docker-образ приложения. Перейдите в директорию deploy и создайте ресурсы в Yandex Container Registry:

    cd <путь_к_директории_deploy>
terraform apply -target=yandex_container_registry.default
terraform apply -target=yandex_container_repository.movies_api_repository

    Подтвердите создание ресурсов: введите в терминале yes и нажмите Enter.

  3. В выводе команды, в переменной movies_api_repository_name, указано название репозитория, в который нужно загрузить Docker-образ. Экспортируйте его в переменную окружения:

    export MOVIES_API_REPOSITORY_NAME=<название_репозитория>
echo $MOVIES_API_REPOSITORY_NAME

  4. Настройте Docker для работы с созданным репозиторием:

    yc container registry configure-docker

  5. В файле Dockerfile описана конфигурация для сборки Docker-образа. Соберите образ и загрузите его в созданный на предыдущем шаге репозиторий:

    docker build -t ${MOVIES_API_REPOSITORY_NAME}:0.0.1 .
docker push ${MOVIES_API_REPOSITORY_NAME}:0.0.1

  6. Создайте контейнер Serverless Containers:

    yc sls container create \
  --name movies-api-container \
  --folder-id ${FOLDER_ID}

    Где:

    • --name — имя контейнера.
    • --folder-id — идентификатор каталога.

  7. В выводе команды указан идентификатор созданного контейнера. Экспортируйте его в переменную окружения:

    export MOVIES_API_CONTAINER_ID=<идентификатор_контейнера>
echo $MOVIES_API_CONTAINER_ID

  8. Создайте ревизию контейнера из Docker-образа с версией 0.0.1:

    yc sls container revisions deploy \
  --folder-id ${FOLDER_ID} \
  --container-id ${MOVIES_API_CONTAINER_ID} \
  --memory 512M \
  --cores 1 \
  --execution-timeout 5s \
  --concurrency 4 \
  --environment AWS_ACCESS_KEY_ID=FAKE_AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY=FAKE_AWS_SECRET_ACCESS_KEY,DOCUMENT_API_ENDPOINT=${DOCUMENT_API_ENDPOINT} \
  --service-account-id ${MOVIES_API_SA_ID} \
  --image ${MOVIES_API_REPOSITORY_NAME}:0.0.1

    Где:

    • --folder-id — идентификатор каталога.
    • --container-id — идентификатор контейнера.
    • --memory — объем памяти, доступный контейнеру.
    • --cores — количество ядер vCPU, доступное контейнеру.
    • --execution-timeout — таймаут выполнения.
    • --concurrency — максимальное число одновременных вызовов контейнера. Если вызовов контейнера больше, чем значение параметра --concurrency, сервис масштабирует контейнер — запускает его дополнительные экземпляры.
    • --environment — переменные окружения. Через переменную окружения DOCUMENT_API_ENDPOINT в приложение передается Document API эндпоинт базы данных.
    • --service-account-id — идентификатор сервисного аккаунта.
    • --image — название репозитория.

Разверните API в API Gateway

  1. В спецификации OpenAPI api.yaml замените переменную ${MOVIES_API_CONTAINER_ID} на идентификатор созданного контейнера.

  2. В файле api-gateway.tf описана конфигурация Terraform для создания API-шлюза. Разверните API-шлюз:

    terraform apply -target=yandex_api_gateway.movies_api_gateway

    Подтвердите создание ресурсов: введите в терминале yes и нажмите Enter.

  3. В выводе команды, в переменной movies_api_gateway_domain, указано доменное имя API-шлюза. Экспортируйте его в переменную окружения:

    export MOVIES_API_GATEWAY_DOMAIN=<доменное_имя_API-шлюза>
echo $MOVIES_API_GATEWAY_DOMAIN

Проверьте работу созданного CRUD API

Чтобы проверить работу созданного CRUD API, выполните следующие HTTP-запросы с помощью команды curl:

  1. Получите список фильмов:

    curl "${MOVIES_API_GATEWAY_DOMAIN}/movies?limit=10"

    В ответе должен прийти пустой список [], так как пока в базе нет данных.

  2. Добавьте информацию о фильме:

    curl \
  --location \
  --request POST 'https://${MOVIES_API_GATEWAY_DOMAIN}/movies' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": "301",
    "title": "The Matrix",
    "release_date": 1999
  }'

  3. Получите информацию о фильме:

    curl \
  --location \
  --request GET 'https://${MOVIES_API_GATEWAY_DOMAIN}/movies/301'

  4. Добавьте информацию о другом фильме:

    curl \
  --location \
  --request POST 'https://${MOVIES_API_GATEWAY_DOMAIN}/movies' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": "299",
    "title": "The Matrix Reloaded",
    "release_date": 2003
  }'

  5. Получите список фильмов:

    curl \
  --location \
  --request GET 'https://${MOVIES_API_GATEWAY_DOMAIN}/movies?from=1&limit=5'

Также вы можете загрузить спецификацию в Postman или SwaggerHub, добавив в секцию servers адрес созданного API-шлюза из переменной ${MOVIES_API_GATEWAY_DOMAIN}. Это позволит удобно делать вызовы к REST API.

Посмотрите диагностическую информацию о работе контейнера. В консоли управления перейдите на страницу контейнера. На вкладке Логи находятся сообщения о вызовах контейнера, а на вкладке Мониторинг — графики вызовов контейнера, среднего времени обработки запроса и количества ошибок.

Логи и графики мониторинга также можно посмотреть на странице API-шлюза.

Как удалить созданные ресурсы

Чтобы перестать платить за ресурсы, созданные с помощью Terraform, удалите их. В терминале выполните команду:

terraform destroy

Подтвердите удаление ресурсов: введите в терминале yes и нажмите Enter.

См. также

Предыдущая
Разработка пользовательской интеграции
Следующая
Работа с API-шлюзом по протоколу WebSocket