API

API — ключевой концепт шлюза. Мы можем управлять API через сервер управления API шлюза.

Атрибуты API

ID

Уникальный идентификатор API

Название

Название API

URLPattern

Выражение для сопоставления URL. Шлюз использует это для совпадения с исходными запросами URL. URLPattern должен использоваться вместе с Method. Эти два условия должны выполняться для того чтобы запрос считался совпавшим с API.

Выражение URLPattern

/ используется для разделения пути URL. Каждый раздел может быть одного из следующих типов:

• строковая константа: любой легальный URL. Можно использовать * для совпадения со всеми строками;
• (число): аргумент типа число;
• (строка): аргумент типа строка;
• (перечисление:перечисление1|перечисление2|...): аргумент типа перечисление. Доступные значения перечисления разделены символом |.

Если эти переменные необходимы, например, в URL Rewrite, можно использовать: * (число):id; * (строка):name; * (перечисление:on|off):action;

Примеры:

• /api/v1/product/(число):id;
• /api/v1/product/(число):id/(перечисление:online|offline):action;
• /api/v1/*;

Метод (необязательно)

Используется для совпадения поля HTTP Method запроса HTTP. Значение * совпадает со всеми методами HTTP (GET, PUT, POST, DELETE).

Область (необязательно)

Совпадает с полем HOST запроса HTTP.

Правила Совпадения

Правила совпадения для URLPattern, Method, Domain

• MatchDefault URLPattern && (Method || Domain);
• MatchAll URLPattern && (Method && Domain);
• MatchAny URLPattern && (Method || Domain);## Состояние UP, Down. API действителен только если его состояние UP.

Управление доступом по IP (необязательно)

Белый список и черный список

Значение по умолчанию (необязательно)

Значение по умолчанию API. Когда нет доступного сервера в кластере back-end, шлюз возвращает это значение, которое состоит из кода, HTTP Body, заголовка и cookie. Это может быть использовано как значение по умолчанию для Mock или back-end сервисов.

Агрегация запросов

Оригинальный запрос переадресуется на несколько серверов back-end и ответы объединяются в экземпляр JSON, чьи атрибуты соответствуют каждому ответу. Множественные переадресованные запросы могут отправляться одновременно или пакетом (аргумент запроса зависит от предыдущего ответа). BatchIndex устанавливает порядок каждого переадресованного запроса.

Пример

• Оригинальный запрос: /api/v1/aggregation/1
• Переадресованный запрос: /api/v1/users/1, Ответ: {"name":"zhangsan"}, Атрибут: user
• Переадресованный запрос: /api/v1/accounts/1, Ответ: {"type":"test", "accountId":"123"}, Атрибут: account
• Конечный ответ: {"user":{"name":"zhangsan"}, "account":{"type":"test", "accountId":"123"}}

Узлы

Запросы переадресуются как минимум в один кластер back-end. Один запрос может быть отправлен сразу нескольким кластерам back-end одновременно (в настоящее время поддерживаются только HTTP GET-запросы). Переадресованные запросы поддерживают следующие возможности.### Перезапись URL Он восстанавливает реальные URL, переадресованные на серверы back-end.

Выражение перезаписи URL

Поддерживаются переменные в выражениях. В режиме выполнения $() заменяются на реальные значения. Для доступа к атрибутам переменной используется ..

Переменная origin

Переменная origin используется для извлечения строки запроса (query string), заголовков (headers), cookie, тела запроса (body) исходных запросов. Поддерживается отдельный выбор значений для нескольких аргументов с одним и тем же именем.

Исходный запрос

• URL: /api/v1/users?id=1&name=fagongzi&page=1&pageSize=100,
• Заголовок: x-test-token: token1, x-test-id: 100
• Cookie: x-cookie-token: token2, x-cookie-id: 200
• Тело: {"type":1, "value":{"id":100, "name":"zhangsan"}}

Форма переменной

• $(origin.query) = ?id=1&name=fagongzi&page=1&pageSize=100
• $(origin.path) = /api/v1/users
• $(origin.query.id) = 1, $(origin.query.name) = fagongzi, $(origin.query.page) = 1, $(origin.query.pageSize) = 100
• $(origin.headers.x-test-token) = token1, $(origin.headers.x-test-id) = 100
• $(origin.cookies.x-cookie-token) = token2, $(origin.cookies.x-cookie-id) = 200
• $(origin.body.type) = 1, $(origin.body.value.id) = 100, $(origin.body.value.name) = zhangsan

Переменная param

Переменная param используется для извлечения переменных из шаблона URL API.

Предположим:

• Шаблон URL API: /api/v1/users/(number):id/(enum:on|off):action
• URL запроса: /api/v1/users/100/on

Форма переменной

• $(param.id) = 100
• $(param.action) = on

Переменная depend

Переменная depend используется для извлечения данных из возвращаемых значений зависимых агрегирующих запросов.Предположим, что агрегирующий запрос состоит из двух запросов — пользователя и счета

• пользователь: {"name": "zhangsan"}
• счет: {"id": "123456"}

Пример переменной

• $(depend.user.name) = zhangsan
• $(depend.account.id) = 123456

Примеры выражений перезаписи URL

• /api/v1/users$(origin.query)
• $(origin.path)?name=$(origin.header.x-user-name)&id=$(origin.body.user.id)
• /api/v1/users?id=$(param.id)&action=$(param.action)
• /api/v1/accounts?id=$(depend.user.accountId)

Поддержка проверки аргументов в исходных запросах

Проверка правил регулярных выражений конфигурации любого атрибута в querystring, json body, cookie, header и path value поддерживается

Поддержка повторной попытки после неудачи

retryStrategy можно установить для повторной попытки на основе HTTP-статуса ответа. Можно задать максимальное количество попыток и интервал между ними.

Время ожидания API

ReadTimeout и WriteTimeout можно установить для задания времени ожидания чтения и записи запроса. Если значения не установлены, используется глобальная конфигурация по умолчанию.

Perms (необязательно)

Используется для конфигурирования прав доступа API. Пользователям требуется разработать свои плагины проверки прав доступа.

AuthFilter (необязательно)

Устанавливает имя плагина аутентификации API. Ссылка на реализацию плагина аутентификации JWT плагин.

RenderTemplate

RenderTemplate может использоваться для переопределения ответов, которые включают формат данных и поля.## ИспользоватьПоУмолчанию (необязательно) Если значение равно true и существует ЗначениеПоУмолчанию, то ЗначениеПоУмолчанию используется как значение ответа.

ПравилоСоответствия (необязательно)

Позиция (необязательно)

Это значение используется в порядке возрастания при этапе соответствия API. Чем меньше значение, тем выше приоритет. Значение по умолчанию равно 0.

Тэги (необязательно)

Для обслуживания и поиска.

ОпцииWebSocket (необязательно)

Опции websocket, websocket. Внимание: websocket всё ещё находится в тестовой фазе. По умолчанию закрыт. --websocket можно использовать для запуска. Когда шлюз перенаправляет websocket, Origin использует адрес серверов back-end по умолчанию. Если требуется установить специальное значение, аргумент Origin можно задать.

МаксимальноеQPS (необязательно)

Максимальное значение QPS, которое может поддерживать API. Используется для контроля трафика. Шлюз использует алгоритм корзины с токенами, ограничивая трафик значением МаксимальногоQPS, что защищает серверы back-end от перегрузки. Приоритет API выше, чем в сервер.

РазрывЦепи (необязательно)

Правила разрыва цепи для back-end API. Он имеет три режима.

РазрывЦепи (необязательно)

Состояние разрыва цепи для сервера back-end:

• ОткрытоНормально. Все трафик проходит. Когда шлюз обнаруживает соотношение неудачных запросов ко всем запросам, достигшее определённого порога, разрыв цепи переключается с режима "Открыто" на режим "Закрыто".* Полуоткрыто Попытка восстановления. Шлюз пытается направить определённый процент трафика на сервер и наблюдает за результатом. Если ожидание оправдано, CircuitBreaker переходит в состояние "Открыто". В противном случае — в состояние "Закрыто".

• Закрыто

  Шлюз не направляет никакого трафика на этот сервер. Когда порог времени истёк, шлюз автоматически пытается восстановиться, переходя в состояние "Полуоткрыто".