Облачная платформаEvolution

Расширения спецификации API Gateway

Эта статья полезна?

Здесь описана спецификация расширений, которые начинаются с префикса x-cloud.

Расширение x-cloud-authtype

Расширение x-cloud-authtype позволяет указать тип авторизации для правила.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
-	str, enum	Да	Возможные значения: awsSigv4, iam Тип авторизации указывается в секции components:securitySchemes. Сейчас доступно 2 типа авторизации. В securitySchemes игнорируются все параметры, кроме x-cloud-authtype.

Особенности расширения

Значение можно объявить только в components:securitySchemes. На уровне root, operation его можно переиспользовать с помощью OpenAPI-объекта security.

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

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
security:
  - awsSignatureAuth: []
paths:
   /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
    post:
      operationId: postDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
      security:
         - iamAuth: []
 components:
   securitySchemes:
     iamAuth:
       type: apiKey   # this parameter is ignored
       name: Authorization    # this parameter is ignored
       in: header   # this parameter is ignored
       x-cloud-authtype: iam
   awsSignatureAuth:
      type: apiKey    # this parameter is ignored
      name: Authorization   # this parameter is ignored
      in: header    # this parameter is ignored
      x-cloud-authtype: awsSigv4
   x-cloud-upstreams:
     HttpUpstream:
       name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
        - host: example.com
          weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-circuit-breaker

Расширение x-cloud-circuit-breaker позволяет отклонять API запросы в случае недоступности бекэнда.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
max_breaker_sec	int	Да	Максимальное время работы режима отклонения запросов, сек. Значение должно быть больше или равно 3.
break_response_body	str	Нет	Тело ответа, когда upstream находится в статусе unhealthy. Внимание Параметр временно отключен.
break_response_headers	list[Object[str, str]]	Нет	Заголовки ответа, когда upstream находится в статусе unhealthy. Внимание Параметр временно отключен.
break_response_code	int	Да	Возможные значения: 200–599. HTTP-код ответа, когда upstream находится в статусе unhealthy.
healthy	CircuitBreakerHealthyObject	Да	Настройки healthy статуса для upstream.
unhealthy	CircuitBreakerUnhealthyObject	Да	Настройки unhealthy статуса для upstream.

Параметры CircuitBreakerHealthyObject

Название	Тип	Обязательный параметр	Описание
http_statuses	list[int]	Нет	Список кодов статуса для healthy upstream. Возможные значения: 200–599. По умолчанию 200.
successes	int	Да	Количество успешных запросов для healthy upstream. Должно быть более 0.

Параметры CircuitBreakerUnhealthyObject

Название	Тип	Обязательный параметр	Описание
http_statuses	list[int]	Нет	Список кодов статуса для unhealthy upstream. Возможные значения: 500, 599. По умолчанию 500.
failures	int	Да	Количество успешных запросов для unhealthy upstream. Должно быть более 0.

Особенности расширения

Может быть объявлено на уровне root, path, operation.

Использование ref разрешено только через components:x-cloud-circuit-breakers.

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

Пример спецификации на уровне path:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
    x-cloud-circuit-breaker:
      break_response_code: 502
      max_breaker_sec: 3
      unhealthy:
        http_statuses:
          - 502
          - 504
        failures: 3
      healthy:
        http_statuses:
          - 200
          - 201
        successes: 3
components:
  x-cloud-upstreams:
    HttpUpstream:
      name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
        - host: example.com
          weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-cors

Расширение x-cloud-cors позволяет настроить совместное использование ресурсов (CORS).

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
allow_origins	str или list	Нет	Источники, для которых разрешен CORS. Примеры: list[str] = ["https://example.com", https://example2.com"]str = "https://example.com,https://example2.com"
allow_headers	str или list	Нет	Заголовки запросов, которые разрешены при доступе к ресурсу.
expose_headers	str или list	Нет	Заголовки ответов, которые разрешены при доступе к ресурсу.
allow_methods	str или list, enum	Нет	Методы, для которых разрешен CORS. Возможные значения: ["GET", "POST", "DELETE", "PATCH", "HEAD", "OPTIONS", "CONNECT", "TRACE", "*"]
max_age	str или list, enum	Нет	Максимальное время в секундах, в течение которого результат кешируется. По умолчанию 5. Если время находится в пределах этого ограничения, браузер проверит кешированный результат. Установите значение -1, чтобы отключить кеширование. Максимальное значение зависит от браузера.
allow_credential	boolean	Нет	Разрешить запросы, содержащие заголовок Access-Control-Allow-Credentials. Внимание При значении True запрещено использовать «*» в полях allow_origins, allow_headers, expose_headers, allow_methods.

Особенности расширения

Может быть объявлено на уровне root, path.

Использование ref разрешено только через x-cloud-cors-rules.

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

Пример спецификации на уровне root:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
x-cloud-cors:
  allow_origins: '*'
  allow_methods: ["GET"]
  allow_headers: '*'
  allow_credential: false
  expose_headers: '*'

paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
components:
  x-cloud-upstreams:
    HttpUpstream:
      name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
        - host: example.com
          weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-limit-count

Расширение x-cloud-limit-count позволяет ограничить число запросов к целевому хосту в период времени.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
count	int	Да	Максимальное количество запросов в единицу времени. Должно быть больше 0.
time_window	int	Да	Время в секундах, через которое счетчик количества запросов будет сброшен. Должно быть больше 0.
rejected_code	int	Нет	Код HTTP-ответа, возвращаемый в случае отклонения запроса из-за превышения лимита. Диапазон значений: 200 - 599. По умолчанию 503.

Особенности расширения

Может быть объявлено на уровне root, path, operation.

Использование ref разрешено только через components:x-cloud-limit-counts.

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

Пример спецификации на уровне operation:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
      x-cloud-limit-count:
        count: 10
        time_window: 5
        rejected_code: 429
components:
  x-cloud-upstreams:
    HttpUpstream:
      name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
        - host: example.com
          weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-log-group

Расширение x-cloud-log-group позволяет включить логирование запросов для правил.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
-	UUID	Да	Лог-группа может указываться на уровнях root, path и operation следующим образом — x-cloud-log-group: <UUID>. Должно быть больше 0.

Особенности расширения

Может быть объявлено на уровне root, path, operation.

Использование ref разрешено только через components:x-cloud-log-groups.

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

Пример спецификации на уровне operation:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-log-group: 5afbf5a5-46da-40d1-a409-c9a3310b720a
      x-cloud-mock:
        content_type: "application/json"
        delay: 1
        response_status: 200
        response_example: '{"status": "Success GET"}'

Расширение x-cloud-mock

Расширение x-cloud-mock возвращает в ответе статичные данные без участия стороннего сервиса.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
delay	int	Нет	Задержка ответа в секундах. Должна быть больше 0.
response_status	int, enum: [200-599]	Нет	HTTP-код ответа. Диапазон значений: 200 - 599.

Особенности расширения

Может быть объявлено на уровне operation.

Использование ref разрешено только через components:x-cloud-mocks.

Несовместимо с расширениями x-cloud-circuit-breaker, x-cloud-redirect, x-cloud-traffic-split, x-cloud-proxy-rewrite, x-cloud-upstream.

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

Пример спецификации на уровне operation:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-mock:
        content_type: "application/json"
        delay: 1
        response_status: 200
        response_example: '{"status": "Success GET"}'

Расширение x-cloud-proxy-cache

Расширение x-cloud-proxy-cache позволяет настроить хранение в кеше ответов на запросы.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
cache_methods	str или list[str], enum	Да	Методы запросов, которые будут закешированы. Возможные значения: GET, POST, HEAD.
cache_ttl	int	Да	Время в секундах, по истечении которого кешированные данные удаляются, если нет повторных запросов. Должно быть больше 0.
cache_http_status	int	Да	Время в секундах, по истечении которого кешированные данные удаляются, если нет повторных запросов.

Особенности расширения

Может быть объявлено на уровнях root, path.

Использование ref разрешено только через components:x-cloud-proxy-cache-rules.

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

Пример спецификации на уровне operation:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-mock:
        content_type: "application/json"
        delay: 1
        response_status: 200
        response_example: '{"status": "Success GET"}'

Расширение x-cloud-proxy-rewrite

Расширение x-cloud-proxy-rewrite позволяет настроить правила перенаправления трафика на целевой бэкенд через прокси.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
uris	list[ProxyRewriteUriObject]	Да	Правила переадресации, определенные в ProxyRewriteUriObject.
headers	Object[str, str]	Нет	Заголовки, которые будут добавлены к запросу при маршрутизации на целевой хост.

В таблице ниже перечислены параметры ProxyRewriteUriObject.

Название	Тип	Обязательный параметр	Описание
forward_from	str, regex	Да	URI, к которому будет применено правило маршрутизации на forward_to. Если запрошенный клиентом URI совпадает со значением forward_from, то в upstream будет добавлено значение параметра forward_to. Регулярное выражение для проверки: ^(\/([a-zA-Z0-9\-\.\_\~\!\$\&\'\\+\,\;\=\:\@]\|(%[a-fA-F0-9]{2,2})))+$
forward_to	str, regex	Нет	URI, на который будет перенаправлен трафик на целевой бекэнд. Регулярное выражение для проверки: ^(\/([a-zA-Z0-9\-\.\_\~\!\$\&\'\\+\,\;\=\:\@]\|(%[a-fA-F0-9]{2,2})))+$

Особенности расширения

Может быть объявлено на уровнях path, operation.

Требует наличия расширений x-cloud-upstream или x-cloud-traffic-split.

Несовместимо с расширениями x-cloud-redirect или x-cloud-mock.

Использование ref разрешено только через components:x-cloud-proxy-rewrites.

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

Пример спецификации на уровне path:

Примечание

Так как x-cloud-proxy-rewrite указан на уровне path, плагин применится как к методу GET, так и к методу POST.

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
    post:
      operationId: postDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
    x-cloud-proxy-rewrite:
      uris:
      - forwarded_from: /
        forwarded_to: /v2
      headers:
        X-Version: 1
components:
  x-cloud-upstreams:
    HttpUpstream:
      name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
      - host: example.com
        weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-redirect

Расширение x-cloud-redirect позволяет перенаправить запрос на определенный URL-адрес целевого хоста.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
uri	str	Да	URL-адрес, куда будет перенаправлен запрос.
ret_code	int, enum	Нет	Возможные значения: 200–599. Значение по умолчанию: 302. HTTP-код ответа, когда upstream находится в статусе unhealthy.
encode_uri	boolean	Нет	Если указано значение True, URI в заголовке Location будет закодирован в соответствии с RFC3986.
append_query_string	boolean	Нет	Добавляет query-параметры запроса в заголовок Location. Eсли URI уже содержит query-параметр, новые параметры query будут добавлены через &.

Особенности расширения

Может быть объявлено на уровнях operation, path.

Несовместимо с расширениями x-cloud-circuit-breaker, x-cloud-limit-count, x-cloud-proxy-cache, x-cloud-proxy-rewrite, x-cloud-response-rewrite, x-cloud-upstream, x-cloud-traffic-split.

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

Пример спецификации на уровне operation:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /redirect:
    get:
      operationId: getDemo
      x-cloud-redirect:
        uri: https://example.com
        encode_uri: true
        append_query_string: true

Расширение x-cloud-response-rewrite

Расширение x-cloud-response-rewrite позволяет переписать код ответа, тело ответа, заголовки ответа.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
status_code	int	Да	Возможные значения: 200–599. Код HTTP-ответа, возвращаемый при перезаписи. Оставьте поле пустым, если перезапись кода ответа не требуется.
body	str	Нет	Тело HTTP-ответа, возвращаемое при перезаписи. Оставьте поле пустым, если перезапись тела ответа не требуется.
headers	Object[str, str]	Нет	Время в секундах, по истечении которого кешированные данные удаляются, если нет повторных запросов.

Особенности расширения

Может быть объявлено на уровнях operation.

Использование ref разрешено только через components:x-cloud-response-rewrites.

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

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        $ref: "#/components/x-cloud-upstreams/HttpUpstream"
      x-cloud-response-rewrite:
        status_code: 200
        body: '{"status": "Success"}'
        body_base64: false
        headers:
          X-Test-Header: value
components:
  x-cloud-upstreams:
    HttpUpstream:
      name: Http_Upstream
      description: TestDescription
      type: url
      scheme: https
      nodes:
        - host: example.com
          weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

Расширение x-cloud-traffic-split

Расширение x-cloud-traffic-split позволяет разделять трафик на целевые бекэнды в различных соотношениях.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
groups	TrafficSplitGroupObject	Нет	Список групп для разделения трафика

В таблице ниже перечислены параметры TrafficSplitGroupObject.

Название	Тип	Обязательный параметр	Описание
match	TrafficSplitGroupHeaderObject	Да	Заголовок, определяющий, к какой группе отнести запрос клиента.
backends	list[TrafficSplitWeightedUpstreamObject]	Да	Список взвешенных подключений (объектов upstream) группы.

В таблице ниже перечислены параметры TrafficSplitWeightedUpstreamObject.

Название	Тип	Обязательный параметр	Описание
backend	объект x-cloud-upstream или $ref:	Да	Настройки подключения.
weight	int	Да	Вес подключения.

Особенности расширения

Может быть объявлено на уровнях operation.

Несовместимо с расширениями x-cloud-mock, x-cloud-redirect, x-cloud-upstream.

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

Пример спецификации на уровне operation:

 openapi: 3.0.0
 info:
   version: 1.0.0
   title: Test
 paths:
/:
  get:
    operationId: getDemo
    x-cloud-traffic-split:
      groups:
        - match:
          - variable: X-Version
            operator: ==
            value: "1"
          backends:
          - backend:
              $ref: "#/components/x-cloud-upstreams/CloudUpstream"
            weight: 1

        - match:
            - variable: X-Version
              operator: ==
              value: "2"
          backends:
          - backend:
              $ref: "#/components/x-cloud-upstreams/HttpBinUpstream"
            weight: 1
 components:
   x-cloud-upstreams:
     CloudUpstream:
       name: CloudUpstream
       description: TestDescription
       type: url
       scheme: https
       nodes:
         - host: cloud.ru
           weight: 1
       timeout:
         connect: 3
         send: 3
         read: 3
     HttpBinUpstream:
       name: HttpBin_Upstream
       description: TestDescription
       type: url
       scheme: https
       nodes:
         - host: httpbin.org
           weight: 1
       timeout:
         connect: 3
         send: 3
         read: 3

Расширение x-cloud-upstream

Расширение x-cloud-upstream позволяет создать подключение, которое содержит сведения о целевом хосте вашего бекэнда, принимающем запросы к API.

Внимание

Данное расширение несовместимо с текущей версией UI, его использование без вспомогательного плагина x-cloud-proxy-rewrite приведет к ошибке рендера в UI. Необходимо задать расширение x-cloud-proxy-rewrite.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
name	str, regex	Да	Имя подключения. Допустимые значения: ^[a-z, A-Z, 0-9][a-z, A-Z, 0-9_\-\.]{0,99}$
type	str, enum	Да	Тип подключения. Возможные значения: url serverless_function serverless_container vm
description	str	Нет	Описание подключения.
scheme	str, enum	Да	Протокол подключения. Возможные значения: http, https, grpc, grpcs.
nodes	list[UpstreamNodeObject]	Нет	Узлы подключения.
timeout	UpstreamTimeoutObject	Да	Таймауты подключения.

UpstreamNodeObject

Название	Тип	Обязательный параметр	Описание
host или function_id или container_id или vm_id	str/UUID	Да	Доменное имя/ip-адрес/идентификатор целевого хоста. Имя и формат значения параметра соответствует значению параметра type расширения x-cloud-upstream: host: str = url function_id: UUID = serverless_function container_id: UUID = serverless_container vm_id: UUID = vm (значение не поддерживается)
weight		Да	Вес плеча. Если указано несколько подключений, балансировка осуществляется в соответствии с весами узлов.

UpstreamTimeoutObject

Название	Тип	Обязательный параметр	Описание
connect	float	Да	Таймаут на подключение.
read	float	Да	Таймаут на чтение.
send	float	Да	Таймаут на отправку.

Особенности расширения

Может быть объявлено на уровнях operation.

Несовместимо с расширениями x-cloud-mock, x-cloud-redirect.

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

Пример спецификации при значении type, равным url:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-upstream:
        name: Http_Upstream
        description: TestDescription
        type: url
        scheme: https
        nodes:
          - host: httpbin.org
            weight: 1
          - host: cloud.ru
            weight: 1
        timeout:
          connect: 3
          send: 3
          read: 3

Расширение x-cloud-ws

Расширение x-cloud-ws позволяет использовать протокол WebSocket для обмена сообщениями между клиентом и сервером.

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

В таблице ниже перечислены параметры для шлюза Evolution API Gateway.

Название	Тип	Обязательный параметр	Описание
-	boolean	Да	Активация WebSocket может быть указана на уровне operation в формате x-cloud-ws: <bool>.

Особенности расширения

Может быть объявлено на уровнях operation.

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

Пример спецификации с x-cloud-ws:

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test

paths:
  /:
    get:
      operationId: getDemo
      x-cloud-ws: true
      x-cloud-mock:
        content_type: "application/json"
        delay: 1
        response_status: 200
        response_example: '{"status": "Success GET"}'

См.также

Создание шлюза API из файла спецификации

Предыдущая статья

Основные понятия сервиса API Gateway

Следующая статья

Мониторинг и управление

Эта статья полезна?

Поддержка Юридические документы Политика конфиденциальности