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

Расширение x-yc-apigateway-integration:cloud_ydb

Статья создана
Обновлена 3 октября 2024 г.

Расширение x-yc-apigateway-integration:cloud_ydb позволяет выполнять операции с документными таблицами в базе данных Yandex Managed Service for YDB. Чтобы взаимодействовать с YDB, используется Document API, который совместим с Amazon DynamoDB.

Добавить расширение в спецификацию можно с помощью конструктора спецификаций.

Поддерживаемые операции

Операция Поддерживаемые параметры Что вернет API Gateway в формате JSON,
если операция выполнится успешно
PutItem table_name Элемент, сохраненный в таблице
GetItem table_name
key		 Элемент, прочитанный из таблицы
UpdateItem table_name
key
update_expression
expression_attribute_values		 Элемент, обновленный в таблице
DeleteItem table_name
key		 Элемент, удаленный из таблицы
Scan table_name
limit
exclusive_start_key		 Список элементов, прочитанных из таблицы

Чтобы при выполнении операции PutItem, тело запроса преобразовалось в ассоциативный массив со значениями типа AttributeValue и подставилось в параметр Item, передайте его в формате JSON.

Если для операции UpdateItem в теле запроса придет объект в формате JSON, из его полей сформируется набор изменений AttributeUpdates и подставится в соответствующий параметр операции.

Поддерживаемые параметры

В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в спецификации OpenAPI 3.0.

Параметр Тип Обязательный Подстановка
параметров		 Описание
action string Да Нет Выполняемая операция. Возможные значения: PutItem, GetItem, UpdateItem, DeleteItem, Scan.
database string Да Нет Относительный путь к базе данных.
service_account_id string Да Нет Идентификатор сервисного аккаунта. Используется для авторизации при выполнении операции с базой данных. Если параметр не указан, используется значение верхнеуровневого параметра service_account_id.
table_name string Да Да Название таблицы, с которой выполняется операция.
key string Нет Да Первичный ключ элемента, с которым выполняется операция. Набор атрибутов и их значений в формате JSON. Необходимо указать все ключевые атрибуты. Значения атрибутов автоматически преобразовываются в объекты типа AttributeValue. Используется в операциях GetItem, UpdateItem и DeleteItem.
update_expression string Нет Да Выражение, которое определяет, как и какие атрибуты нужно обновить. Используется в операции UpdateItem.
expression_attribute_values string Нет Да Алиас, который можно использовать в выражении update_expression вместо значения атрибута. Алиас должен начинаться с символа двоеточия :. Используется в операции UpdateItem.
limit string Нет Да Максимальное количество прочитанных элементов. Используется в операции Scan.
exclusive_start_key string Нет Да Первичный ключ элемента, с которого начнется поиск. Набор атрибутов и их значений в формате JSON. Значения атрибутов автоматически преобразовываются в объекты типа AttributeValue. Используется в операции Scan.

Примеры спецификаций

Спецификация расширения

Пример REST API сервиса, который позволяет создавать, получать, обновлять и удалять сущности фильмов:

openapi: 3.0.0
info:
  title: Movies API
  version: 1.0.0
servers:
  - url: https://d3drb9haai**********.apigw.yandexcloud.net
paths:
  /movies:
    get:
      description: Get movies
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: Scan
        database: /ru-central1/b3g1emj917**********/etn1f5fa8f**********
        table_name: movie
        limit: '{limit}'
        exclusive_start_key: '{"id": "{from}"}'
      operationId: getMovies
      parameters:
        - description: Identifier from which will be queried movies in ascending order
          explode: true
          in: query
          name: from
          required: true
          schema:
            type: string
          style: form
        - description: Maximum number of movies in response
          explode: true
          in: query
          name: limit
          required: false
          schema:
            default: 10.0
            type: number
          style: form
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/Movie'
                type: array
          description: Movies
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    post:
      description: Create movie
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: PutItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
      operationId: createMovie
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Movie'
        description: Movie to create
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Created or updated movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
  /movies/{movieId}:
    delete:
      description: Delete movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: DeleteItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: deleteMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Deleted movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    get:
      description: Get movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: GetItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: getMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
    put:
      description: Update movie by id
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: UpdateItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: movie
        key: '{"id": "{movieId}"}'
      operationId: updateMovieById
      parameters:
        - description: Identifier of movie
          explode: false
          in: path
          name: movieId
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Movie'
        description: Movie or attributes to update
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Movie'
          description: Updated movie
        default:
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          description: error
components:
  schemas:
    Movie:
      properties:
        year:
          type: integer
        id:
          type: string
        title:
          type: string
      required:
        - id
        - title
        - year
      type: object
    Error:
      properties:
        message:
          type: string
      required:
        - message
      type: object
x-yc-apigateway:
  service_account_id: ajent55o2h**********

Спецификация для таблиц с несколькими первичными ключами

Если вы используете таблицы с несколькими первичными ключами, то опишите в спецификации каждый из них, а в запросе укажите значения обеих колонок с ключами. В примере ниже показан запрос к таблице staff. В ней содержится информация о сотрудниках компании и ключ, состоящий из двух колонок: FirstName и LastName.

Пример спецификации API Gateway:

openapi: 3.0.0
info:
  title: Staff API
  version: 1.0.0
servers:
  - url: https://d3drb9haai**********.apigw.yandexcloud.net
paths:
  /staff:
    get:
      description: Get member info by first and last name
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: GetItem
        database: /ru-central1/b1g1emj927**********/etn1f4fa4f**********
        table_name: staff
        key: '{"FirstName": "{FirstName}", "LastName": "{LastName}"}'
      operationId: getStaffMemberById
      parameters:
        - description: First name of member
          explode: false
          in: query
          name: FirstName
          required: true
          schema:
            type: string
          style: simple
        - description: Last name of member
          explode: false
          in: query
          name: LastName
          required: true
          schema:
            type: string
          style: simple
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
          description: success
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/success'
          description: Got member
components:
  schemas:
    success:
      properties:
        id:
          type: string
x-yc-apigateway:
  service_account_id: ajent55o2h**********

Запрос для получения информации о сотруднике Иване Ивановом:

curl \
  --request GET \
  --header "Authorization: Bearer `yc iam create-token`" \
  "https://d5d16gda7ell********.apigw.yandexcloud.net/staff?FirstName=Ivan&LastName=Ivanov"

Где:

  • staff — таблица, к которой производится запрос.
  • FirstName — первая часть ключа.
  • LastName — вторая часть ключа.

В результате вернется информация о сотруднике.

Предыдущая
Message Queue
Следующая
Жадные параметры