- tocdepth
2
Работа с API
На этой странице
Создание API
Выберите
.Далее выберите
.Нажмите Create API.
На странице заполните следующие поля и нажмите Next:
Name — укажите имя API.
API Group — выберите из списка группу. Если нужной группы нет, то нажмите Create API Group.
Gateway Response — выберите из списка свой вариант отклика шлюза или оставьте ответ по умолчанию.
Security Authentication — выберите режим аутентификации:
App — проверка подлинности производится в сервисе API Gateway.
IAM — проверка подлинности производится в сервисе Identity and Access Management.
Custom — использование своей системы или сервиса для аутентификации.
None — без проверки подлинности.
Simple Authentication (только для режима аутентификации App) — AppCode используется для проведения простой процедуры аутентификации. Клиенты, вызывающие API, добавляют AppCode в заголовок запроса.
Tag Name — для быстрой идентификации одного API от другого введите нужный тег и нажмите значок .
Description — введите описание API.
Define API Request
На странице заполните следующие поля и нажмите Next:
Protocol — выберите протокол, который будете использовать для API-вызовов:
HTTP.
HTTPS.
HTTP& HTTPS.
Path — укажите путь для запроса API. Путь, указанный в формате
/{serviceName}/{interfaceName}
, должен быть определен в блоке Input Parameters. Содержимое фигурных скобок ({}
) чувствительно к регистру.Matching — выберите один из вариантов:
Exact match — запросы API будут перенаправляться точно по указанному пути.
Prefix match — запросы API будут перенаправляться по пути, который начинается с указанных в поле значений.
Method — выберите метод API.
CORS — активируйте, при необходимости, функцию CORS. Если CORS активирован, то нужно создать другой API, использующий метод «OPTIONS».
Примечание
Подробнее смотрите в инструкции Enabling CORS.
Input Parameters — нажмите Add Input Parameter, заполните следующие поля и нажмите ОК:
Name — укажите имя параметра.
Location — выберите местонахождение параметра в запросе («PATH», «HEADER» или «QUERY»).
Type — выберите вид параметра («STRING» или «NUMBER»).
- Mandatory — если данный параметр необходимо включать в каждый запрос, то выберите Yes.
В этом случае запросы, которые не содержат данный параметр, будут отклонены.
Minimum Length — укажите минимальную длину параметра.
Maximum Length — укажите максимальную длину параметра.
Example — введите пример параметра.
Description — введите описание.
Define Backend Request
На странице заполните следующие поля и нажмите Next.
Поля различаются в зависимости от типа бэкенда (Backend Type):
HTTP/HTTPS
Backend Type — выберите HTTP/HTTPS.
Protocol — выберите из списка протокол «HTTP» или «HTTPS».
Method — выберите из списка метод выбора запроса.
Configure VPC Channel — укажите, будете ли вы использовать (Configure Now) или нет (Do not configure) VPC Channel.
VPC Channel (при значении поля Method — «Configure now») — выберите из списка канал VPC. Если нужного канала нет, то нажмите Manage VPC Channel.
Host Header (при значении поля Method — «Configure now») — укажите заголовок хоста для запросов, связанных с каналом VPC. По умолчанию в каждом запросе используется исходный заголовок хоста.
Backend Address (при значении поля Method — «Do not configure») — введите IP-адрес бэкенда или доменное имя, с указанием номера порта (например,
190.168.10.20:123
). По умолчанию будет использоваться порт 80 для HTTP и 443 для HTTPS, если порт не указан.Path — укажите путь (URI) к серверной службе. Путь может содержать в себе параметры, которые должны быть заключены в фигурные скобки («{}»). Например,
/getUserInfo/{userId}
. Если путь содержит переменную окружения (environment variables), заключите переменную окружения в знаки «#», например,/#path#
. Можно использовать несколько переменных окружения, например/#path##request#
.Timeout — укажите длительность тайм-аута. Диапазон: 1-60 000 мс значение по умолчанию — 5000 мс. Если во время отладки API возникает ошибка тайм-аута бэкенда, можно увеличить значение тайм-аута.
Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.
См.также
Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.
Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.
FunctionGraph
Backend Type — выберите FunctionGraph.
Function URN — нажмите на Select Function URN, выберите из списка нужную функцию, созданную в сервисе FunctionGraph, и нажмите ОК.
Version — выберите из списка версию функции.
Invocation Mode — выберите режим вызова функции: синхронный (Synchronous) или асинхронный (Asynchronous).
Timeout — укажите длительность тайм-аута. Диапазон: 1-60 000 мс, значение по умолчанию — 5000 мс. Если во время отладки API возникает ошибка тайм-аута бэкенда, можно увеличить значение тайм-аута.
Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.
См.также
Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.
Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.
Mock
Тип бэкенда Mock можно применять до рабочего использования данного API. При выборе Mock API-запросы на бэкенд направляться не будут. В диалоговом окне нажмите Yes.
Backend Type — выберите Mock.
Response — укажите ответ сервиса на API-запрос.
Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.
См.также
Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.
Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.
Parameters
Backend Parameters — если в поле Path были указаны параметры (в фигурных скобках «{}»), то эти параметры необходимо импортировать (нажмите Import Input Parameter) или ввести (нажмите Add Backend Parameter Mapping) в данном блоке настроек.
Constant Parameters — можно определить параметры для получения констант, невидимых для вызывающих API. При запросе серверной службы API Gateway добавляет данные параметры в указанные позиции запроса, а затем отправляет запрос в бэкенд.
System Parameter — можно указать системные параметры запроса.
Примечание
Можно создать не более 50-ти позиций Backend, Constant и System Parameters.
Add Backend Policy
Дополнительно к бэкенду по умолчанию можно добавить до 5 дополнительных бэкендов. После добавления новой политики бэкенда нажмите Add Backend Policy, измените нужные параметры настроек, а также заполните следующие поля:
Нажмите Add Backend Policy.
Name — укажите имя новой политики бэкенда.
Effective Mode — выберите режим выполнения условий выбора бэкенда: запрос идет на бэкенд при выполнении любого из условий (Any condition met) или только если все условия будут выполнены (All conditions met).
Policy Conditions — чтобы добавить новое условие, нажмите Add Policy Condition.
Define Response
Введите ответы сервиса и нажмите Finish:
Example Success Response — введите пример отклика на успешно выполненный запрос.
Example Failure Response — введите пример отклика на неудачно выполненный запрос.
Просмотр API
Выберите
.Далее выберите
.Нажмите на имя нужного API.
На данной странице вы можете совершить все необходимые операции с API: экспортировать (Export API), перейти в режим отладки (Debug), опубликовать (Publish), перевести API в автономный режим (Take Offline), редактировать (Edit) или удалить (Delete).
На странице API в зависимости от вкладки можно сделать следующее:
Dashboard — доступен URL и, при наличии, доменное имя, а также метрики по вызовам данного API.
API Call — отображена схема настройки данного API и основная информация о нем.
Authorization — на данной вкладке можно применить (Select App) или отклонить (Cancel Authorization) клиентское приложение (только для способа авторизации App).
Request Throttling Policies — на данной вкладке можно применить (Bind) или отклонить (Unbind) политику регулирования запросов.
Access Control Policies — на данной вкладке можно применить (Bind) или отклонить (Unbind) политику доступа.
Signature Keys — на данной вкладке можно применить (Bind) или отклонить (Unbind) цифровые подписи.
Publication History — на данной вкладке сохраняется история изменений API в разрезе среды, в которой он был опубликован. Здесь можно посмотреть изменения (View Details) и вернуться к одной из версий вашего API (Switch Version).
Изменение API
Выберите
.Далее выберите
.В строке с нужным API нажмите More и выберите из списка Edit.
Для переключения между страницами настроек воспользуйтесь кнопками Next или Previous. Измените нужные поля и нажмите Finish.
После внесения изменений в опубликованный API его нужно снова опубликовать Key и соответствующим ему значением (Value) для запросов (Query Parameters) и HTTP-заголовков (Header Parameters).
Body — введите тело запроса (только для методов PATCH, POST или PUT).
Send Request — нажмите кнопку для отправки запроса.
Request — в данном поле отображается отправленный запрос.
Response — в данном поле отображается ответ на запрос.
Из окна отладки можно также перейти к публикации (нажмите Publish) или правке API (нажмите Edit).
Авторизация клиентского приложения (App)
Выберите
.Далее выберите
.В строке с нужным API нажмите Authorize App.
Нажмите Select App, выберите среду (Environment) и приложение и нажмите ОК.
Отмена авторизации клиентского приложения (App)
Выберите
.Далее выберите
.В строке с нужным API нажмите Authorize App.
Нажмите на значок и в строке с нужным клиентским приложением нажмите Cancel Authorization.
Нажмите Yes.
Публикация API
API можно опубликовать в одной или нескольких средах. Среда по умолчанию — RELEASE.
Выберите
.Далее выберите
.В строке с нужным API нажмите Publish.
Заполните поля и нажмите Publish:
Environment — выберите из списка нужную среду, в которой нужно опубликовать API. Если нужной среды нет, нажмите Create Environment.
Description — введите описание.
Перевод API в автономный режим
Выберите
.Далее выберите
.В строке с нужным API нажмите More и выберите из списка Take Offline.
В поле Environment выберите из списка среду, в которой API нужно перевести в автономный режим, и нажмите Yes.
Импорт API
Выберите
.Далее выберите
.Нажмите Import API.
Заполните следующие поля:
Import to — выберите одну из опций:
New group — укажите для импорта API в новую группу. При выборе данной опции система автоматически создаст новую группу и загрузит в нее API.
Existing group — укажите для импорта API в существующую группу. Выберите из раскрывающегося списка одну из существующих групп, и система загрузит API в нее.
Overwrite (только при выборе Existing group) — при выборе данной опции настройки API перезапишутся в соответствии с загружаемым файлом.
Overwrite Extended Definition — при выборе данной опции политики управления доступом (Access Control) и регулирования запросов (Throttling Policy) импортируемого API перезапишутся в соответствии с загружаемым файлом.
— нажмите File и выберите нужный файл для загрузки. Поддерживаются форматы файлов YAML и JSON.
В окне редактора также можно сделать следующее:
Check — проверить синтаксис загруженного файла.
Format — отформатировать содержимое файла.
Download — скачать отредактированные данные.
Для немедленного импорта нажмите Fast Roll Out.
Чтобы произвести дополнительные настройки API, нажмите Configure Global Settings.
На странице Configure Global Settings измените нужные поля и нажмите Next.
На странице Configure APIs измените нужные поля и нажмите кнопку Submit.
Экспорт API
Выберите
.Далее выберите
.Нажмите Export API.
Заполните следующие поля:
API Group — выберите из списка нужную группу.
Environment — выберите из списка нужную среду.
APIs — нажмите Select API, выберите нужные API к экспорту и нажмите ОК.
API Definition — выберите из списка один из следующих вариантов полноты включения информации в файл экспорта:
Full — в файл будет включено описание запроса, бэкенда и ответа на запрос.
Extended — в файл будет включено описание запроса, бэкенда и ответа, а также политики регулирования запросов (throttling policy), политики контроля доступа (access control policy) и других настроек API.
Basic — в файл будет включено описание запроса и ответа. Описание бэкенда не включено. Также в файл будут включены как стандартные, так и расширенные поля Swagger.
Format — укажите, в каком формате будет экспортируемый файл: JSON или YAML.
Version — укажите версию API для экспорта. Если версия не указана, то будут включены данные на текущую дату и время.
Нажмите Export.
.json
или .yaml
будет скачан в папку Downloads (Загрузки).
Мониторинг
Для отслеживания показателей API можно использовать встроенные метрики сервиса в разделе Dashboard. Чтобы перейти метрикам:
Перейдите в раздел
.Нажмите на название нужного API.
Перейдите на вкладку Dashboard.
В этом разделе в режиме реального времени можно отслеживать следующие показатели:
Requests — количество запросов;
Errors — количество запросов с ошибками;
Data Traffic — объем переданных данных;
Latency — время задержки.
Чтобы перейти более детальному мониторингу в сервисе Cloud Eye, нажмите View Metric.
В Cloud Eye доступно больше показателей для мониторинга работы сервиса.
Удаление API
Выберите
.Далее выберите
.В строке с нужным API нажмите More и выберите из списка Delete.
Введите в поле слово DELETE и нажмите Yes.
Примечание
Удалить можно только неопубликованное API. Сначала переведите API в автономный режим (во всех средах, в которых он опубликован), после чего можно его удалить.
для Dev & Test