[Документация Yandex Cloud](../../../index.md) > [Yandex API Gateway](../../index.md) > [Концепции](../index.md) > [Расширения спецификации](index.md) > Интеграции > Managed Service for YDB

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

Расширение `x-yc-apigateway-integration:cloud_ydb` позволяет выполнять операции с [документными таблицами](../../../ydb/concepts/dynamodb-tables.md) в базе данных Yandex Managed Service for YDB. Чтобы взаимодействовать с YDB, используется [Document API](../../../ydb/docapi/api-ref/index.md), который совместим с Amazon DynamoDB.

Добавить расширение в спецификацию можно с помощью [конструктора спецификаций](../../operations/spec-constructor/index.md).

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

Операция | Поддерживаемые параметры | Что вернет API Gateway в формате JSON,<br/>если операция выполнится успешно
----|----|-----
[PutItem](../../../ydb/docapi/api-ref/actions/putItem.md) | `table_name` | Элемент, сохраненный в таблице
[GetItem](../../../ydb/docapi/api-ref/actions/getItem.md) | `table_name`<br/>`key` | Элемент, прочитанный из таблицы
[UpdateItem](../../../ydb/docapi/api-ref/actions/updateItem.md) | `table_name`<br/>`key`<br/>`update_expression`<br/>`expression_attribute_values` | Элемент, обновленный в таблице
[DeleteItem](../../../ydb/docapi/api-ref/actions/deleteItem.md) | `table_name`<br/>`key` | Элемент, удаленный из таблицы
[Scan](../../../ydb/docapi/api-ref/actions/scan.md) | `table_name`<br/>`limit`<br/>`exclusive_start_key` | Список элементов, прочитанных из таблицы

Чтобы при выполнении операции `PutItem`, тело запроса преобразовалось в ассоциативный массив со значениями типа [AttributeValue](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html) и подставилось в параметр `Item`, передайте его в формате JSON.

Если для операции `UpdateItem` в теле запроса придет объект в формате JSON, из его полей сформируется набор изменений [AttributeUpdates](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LegacyConditionalParameters.AttributeUpdates.html) и подставится в соответствующий параметр операции.

## Поддерживаемые параметры {#parameters}

В таблице ниже перечислены параметры, специфичные для API-шлюза сервиса API Gateway. Описание остальных параметров читайте в [спецификации OpenAPI 3.0](https://github.com/OAI/OpenAPI-Specification).

Параметр | Тип | Обязательный | Подстановка<br/>параметров | Описание
----|----|-----|----|----
`action` | `string` | Да | Нет | Выполняемая операция. Возможные значения: `PutItem`, `GetItem`, `UpdateItem`, `DeleteItem`, `Scan`.
`database` | `string` | Да | Нет | Относительный путь к базе данных.
`service_account_id` | `string` | Да | Нет | Идентификатор сервисного аккаунта. Используется для авторизации при выполнении операции с базой данных. Если параметр не указан, используется значение [верхнеуровневого параметра](index.md#top-level) `service_account_id`.
`table_name` | `string` | Да | Да | Название таблицы, с которой выполняется операция.
`key` | `string` | Нет | Да | Первичный ключ элемента, с которым выполняется операция. Набор атрибутов и их значений в формате JSON. Необходимо указать все ключевые атрибуты. Значения атрибутов автоматически преобразовываются в объекты типа [AttributeValue](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html). Используется в операциях [GetItem](../../../ydb/docapi/api-ref/actions/getItem.md), [UpdateItem](../../../ydb/docapi/api-ref/actions/updateItem.md) и [DeleteItem](../../../ydb/docapi/api-ref/actions/deleteItem.md).
`update_expression` | `string` |  Нет | Да | Выражение, которое определяет, как и какие атрибуты нужно обновить. Используется в операции [UpdateItem](../../../ydb/docapi/api-ref/actions/updateItem.md).
`expression_attribute_values` | `string` | Нет | Да | Алиас, который можно использовать в выражении `update_expression` вместо значения атрибута. Алиас должен начинаться с символа двоеточия `:`. Используется в операции [UpdateItem](../../../ydb/docapi/api-ref/actions/updateItem.md).
`limit` | `string` | Нет | Да | Максимальное количество прочитанных элементов. Используется в операции [Scan](../../../ydb/docapi/api-ref/actions/scan.md).
`exclusive_start_key` | `string` | Нет | Да | Первичный ключ элемента, с которого начнется поиск. Набор атрибутов и их значений в формате JSON. Значения атрибутов автоматически преобразовываются в объекты типа [AttributeValue](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_AttributeValue.html). Используется в операции [Scan](../../../ydb/docapi/api-ref/actions/scan.md).

## Примеры спецификаций {#examples}

### Спецификация расширения {#spec}

Пример [REST API](../../../glossary/rest-api.md) сервиса, который позволяет создавать, получать, обновлять и удалять сущности фильмов:

```yaml
openapi: 3.0.0
info:
  title: Movies API
  version: 1.0.0
servers:
  - url: https://d5dm1lba80md********.i9******.apigw.yandexcloud.net
paths:
  /movies:
    get:
      description: Get movies
      x-yc-apigateway-integration:
        type: cloud_ydb
        action: Scan
        database: /kz1/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: /kz1/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: /kz1/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: /kz1/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: /kz1/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**********
```

### Спецификация для таблиц с несколькими первичными ключами {#composite-primary-key-spec}

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

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

```yaml
openapi: 3.0.0
info:
  title: Staff API
  version: 1.0.0
servers:
  - url: https://d5dm1lba80md********.i9******.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: /kz1/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**********
```

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

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

Где:

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

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