Yandex Cloud
Документация
ПрезентацияСвязаться с намиНачать бесплатно
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Проект Яндекса
© 2026 ТОО «Облачные Сервисы Казахстан»
Yandex API Gateway
RU
  • Начало работы
    • Взаимосвязь ресурсов сервиса
    • Сетевое взаимодействие
      • Обзор
      • Жадные параметры
      • Обобщенный HTTP-метод
      • Авторизация с помощью функции Cloud Functions
      • Авторизация с помощью JWT
      • Поддержка протокола WebSocket
      • Валидация данных
      • CORS
      • Параметризация спецификации
      • Канареечный релиз
      • Ограничение скорости обработки запросов
      • Замена кода ответа
      • Преобразование тела ответа и запроса
    • Квоты и лимиты
  • Управление доступом
  • Инструменты
  • Правила тарификации
  • Справочник Terraform
  • Справочник метрик
  • Аудитные логи Audit Trails
  • Публичные материалы
  • История изменений
  • Вопросы и ответы
  • Обучающие курсы

В этой статье:

  • Поддерживаемые параметры
  • Спецификация расширения
  • Примеры использования
  1. Концепции
  2. Расширения спецификации
  3. Преобразование тела ответа и запроса

Расширение x-yc-schema-mapping

Статья создана
Yandex Cloud
Обновлена 26 августа 2026 г.
Открыть в Markdown
  • Поддерживаемые параметры
  • Спецификация расширения
  • Примеры использования

Расширение x-yc-schema-mapping позволяет преобразовывать JSON-тело запроса к интеграции или ответа от нее.

Расширение предназначено для объекта Schema из OpenAPI-спецификации.

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

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

Параметр

Тип

Описание

type

string

Тип преобразования. Возможные значения: static — тело описано статичным ресурсом.

template

map[string]TemplateObject

Полное описание тела в виде словаря в формате <имя_поля>: "<значение_поля>".

string

Строка с корректным jq-шаблоном, позволяющим выбрать нужные данные из тела. Например: "${.numbers.firstNumber}".

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

Спецификация расширения зависит от типа значения параметра template.

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

Объект (словарь)
jq-шаблон
x-yc-schema-mapping:
  type:static
  template:
    property1: "value1"
    property2: "${.baseProperty1.baseProperty2}"

Пример преобразования тела ответа, где пользователю возвращается сообщение из двух полей, если функция Cloud Functions возвращает код 200 и заголовок Content-Type: application/json:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

paths:
  /pets:
    get:
      responses:
        '200':
          description: Pet
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template:
                    Name: "Dog"
                    Breed: "${.nestedProperty1.nestedProperty2}"
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********
x-yc-schema-mapping:
  type: static
  template: "${.numbers.firstNumber}"

Пример преобразования тела ответа, где пользователю возвращается значение одного из ключей входящего JSON-объекта (число 12), которое получено в результате применения jq-шаблона, заданного в параметре template:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Test API

paths:
  /test:
    get:
      summary: Number
      operationId: Number
      responses:
        200:
          description: Another example
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template: "${.numbers.firstNumber}"
          x-yc-status-mapping: 201
        x-yc-mapping-index:
          200: application/json
      x-yc-apigateway-integration:
        http_code: 200
        http_headers:
          Content-Type: application/json
          Content-Length: '10'
        type: dummy
        content:
          application/json: '{"numbers":{"firstNumber": 12, "secondNumber": 32}}'

Примеры использованияПримеры использования

  • Использование Yandex API Gateway для настройки синтеза речи в Yandex SpeechKit

Была ли статья полезна?

Предыдущая
Замена кода ответа
Следующая
Обзор
Создавайте контент и получайте гранты!Готовы написать своё руководство? Участвуйте в контент-программе и получайте гранты на работу с облачными сервисами!
Подробнее о программе
Проект Яндекса
© 2026 ТОО «Облачные Сервисы Казахстан»