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

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

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

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

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

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

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

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

Название	Тип	Обязательный параметр	Описание
-	str, enum	Да	Возможные значения: 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-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
    post:
      operationId: postDemo
      x-cloud-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
      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
   x-cloud-backends:
     HttpBackend:
       name: Http_Backend
      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_code	int	Да	Возможные значения: 200–599. HTTP-код ответа, когда бэкенд находится в статусе unhealthy.
healthy	CircuitBreakerHealthyObject	Да	Настройки healthy статуса для бэкенда.
unhealthy	CircuitBreakerUnhealthyObject	Да	Настройки unhealthy статуса для бэкенда.

Параметры CircuitBreakerHealthyObject

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

Параметры CircuitBreakerUnhealthyObject

Название	Тип	Обязательный параметр	Описание
http_statuses	list[int]	Нет	Список кодов статуса для unhealthy backend. Возможные значения: 500, 599. По умолчанию 500.
failures	int	Да	Количество успешных запросов для unhealthy backend. Должно быть более 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-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
      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-backends:
    HttpBackend:
      name: Http_Backend
      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. Примеры: ["https://example.com", https://example2.com"]"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-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
components:
  x-cloud-backends:
    HttpBackend:
      name: Http_Backend
      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-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
      x-cloud-limit-count:
        count: 10
        time_window: 5
        rejected_code: 429
components:
  x-cloud-backends:
    HttpBackend:
      name: Http_Backend
      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-proxy-rewrite, x-cloud-backend.

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

Пример спецификации на уровне 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, то в backend будет добавлено значение параметра 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-backend

Несовместимо с расширением 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-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
    post:
      operationId: postDemo
      x-cloud-backend:
        $ref: "#/components/x-cloud-backends/HttpBackend"
      x-cloud-proxy-rewrite:
        uris:
        - forward_from: /
          forward_to: /v2
        headers:
          X-Version: 1
components:
  x-cloud-backends:
    HttpBackend:
      name: Http_Backend
      description: TestDescription
      type: url
      scheme: https
      nodes:
      - host: example.com
        weight: 1
      timeout:
        connect: 3
        send: 3
        read: 3

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

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

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

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

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

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

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

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

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

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

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

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

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

В таблице ниже перечислены параметры для шлюза 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_container
description	str	Нет	Описание подключения.
scheme	str, enum	Да	Протокол подключения. Возможные значения: http, https, grpc, grpcs.
nodes	list[NodeObject]	Нет	Узлы подключения.
timeout	TimeoutObject	Да	Таймауты подключения.

NodeObject

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

TimeoutObject

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

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

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

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

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

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

openapi: 3.0.0
info:
  version: 1.0.0
  title: Test
paths:
  /:
    get:
      operationId: getDemo
      x-cloud-backend:
        name: Http_Backend
        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

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

Домены

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

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

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

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