tocdepth

2

Работа с API

Создание API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. Нажмите Create API.

  4. На странице заполните следующие поля и нажмите Next:

    1. Name — укажите имя API.

    2. API Group — выберите из списка группу. Если нужной группы нет, то нажмите Create API Group.

    3. Gateway Response — выберите из списка свой вариант отклика шлюза или оставьте ответ по умолчанию.

    4. Security Authentication — выберите режим аутентификации:

      • App — проверка подлинности производится в сервисе API Gateway.

      • IAM — проверка подлинности производится в сервисе Identity and Access Management.

      • Custom — использование своей системы или сервиса для аутентификации.

      • None — без проверки подлинности.

    5. Simple Authentication (только для режима аутентификации App) — AppCode используется для проведения простой процедуры аутентификации. Клиенты, вызывающие API, добавляют AppCode в заголовок запроса.

    6. Tag Name — для быстрой идентификации одного API от другого введите нужный тег и нажмите значок Кнопка Плюс.

    7. Description — введите описание API.

    ../_images/s__page-set-basic-information-api-gateway.jpeg

Define API Request

  1. На странице заполните следующие поля и нажмите Next:

    1. Protocol — выберите протокол, который будете использовать для API-вызовов:

      • HTTP.

      • HTTPS.

      • HTTP& HTTPS.

    2. Path — укажите путь для запроса API. Путь, указанный в формате /{serviceName}/{interfaceName}, должен быть определен в блоке Input Parameters. Содержимое фигурных скобок ({}) чувствительно к регистру.

    3. Matching — выберите один из вариантов:

      • Exact match — запросы API будут перенаправляться точно по указанному пути.

      • Prefix match — запросы API будут перенаправляться по пути, который начинается с указанных в поле значений.

    4. Method — выберите метод API.

    5. CORS — активируйте, при необходимости, функцию CORS. Если CORS активирован, то нужно создать другой API, использующий метод «OPTIONS».

      Примечание

      Подробнее смотрите в инструкции Enabling CORS.

      ../_images/s__page-define-api-request.jpeg

    6. Input Parameters — нажмите Add Input Parameter, заполните следующие поля и нажмите ОК:

      • Name — укажите имя параметра.

      • Location — выберите местонахождение параметра в запросе («PATH», «HEADER» или «QUERY»).

      • Type — выберите вид параметра («STRING» или «NUMBER»).

      • Mandatory — если данный параметр необходимо включать в каждый запрос, то выберите Yes.

        В этом случае запросы, которые не содержат данный параметр, будут отклонены.

      • Minimum Length — укажите минимальную длину параметра.

      • Maximum Length — укажите максимальную длину параметра.

      • Example — введите пример параметра.

      • Description — введите описание.

      ../_images/s__add-input-parameters.jpeg

Define Backend Request

  1. На странице заполните следующие поля и нажмите Next.

    Поля различаются в зависимости от типа бэкенда (Backend Type):

HTTP/HTTPS

  1. Backend Type — выберите HTTP/HTTPS.

  2. Protocol — выберите из списка протокол «HTTP» или «HTTPS».

  3. Method — выберите из списка метод выбора запроса.

  4. Configure VPC Channel — укажите, будете ли вы использовать (Configure Now) или нет (Do not configure) VPC Channel.

  5. VPC Channel (при значении поля Method — «Configure now») — выберите из списка канал VPC. Если нужного канала нет, то нажмите Manage VPC Channel.

  6. Host Header (при значении поля Method — «Configure now») — укажите заголовок хоста для запросов, связанных с каналом VPC. По умолчанию в каждом запросе используется исходный заголовок хоста.

  7. Backend Address (при значении поля Method — «Do not configure») — введите IP-адрес бэкенда или доменное имя, с указанием номера порта (например, 190.168.10.20:123). По умолчанию будет использоваться порт 80 для HTTP и 443 для HTTPS, если порт не указан.

  8. Path — укажите путь (URI) к серверной службе. Путь может содержать в себе параметры, которые должны быть заключены в фигурные скобки («{}»). Например, /getUserInfo/{userId}. Если путь содержит переменную окружения (environment variables), заключите переменную окружения в знаки «#», например, /#path#. Можно использовать несколько переменных окружения, например /#path##request#.

  9. Timeout — укажите длительность тайм-аута. Диапазон: 1-60 000 мс значение по умолчанию — 5000 мс. Если во время отладки API возникает ошибка тайм-аута бэкенда, можно увеличить значение тайм-аута.

  10. Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.

См.также

  • Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.

  • Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.

../_images/s__define-backend-request-http.jpeg

FunctionGraph

  1. Backend Type — выберите FunctionGraph.

  2. Function URN — нажмите на Select Function URN, выберите из списка нужную функцию, созданную в сервисе FunctionGraph, и нажмите ОК.

  3. Version — выберите из списка версию функции.

  4. Invocation Mode — выберите режим вызова функции: синхронный (Synchronous) или асинхронный (Asynchronous).

  5. Timeout — укажите длительность тайм-аута. Диапазон: 1-60 000 мс, значение по умолчанию — 5000 мс. Если во время отладки API возникает ошибка тайм-аута бэкенда, можно увеличить значение тайм-аута.

  6. Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.

См.также

  • Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.

  • Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.

../_images/s__define-backend-request-functiongraph.jpeg

Mock

Тип бэкенда Mock можно применять до рабочего использования данного API. При выборе Mock API-запросы на бэкенд направляться не будут. В диалоговом окне нажмите Yes.

  1. Backend Type — выберите Mock.

  2. Response — укажите ответ сервиса на API-запрос.

  3. Backend Authentication — если для сервера требуется проверка подлинности API вызова, активируйте данное поле и укажите пользовательские настройки авторизации на основе функции сервиса FunctionGraph.

См.также

  • Подробнее о настройке авторизации на основе функции смотрите в инструкции Creating a Custom Authorizer.

  • Описание полей Backend, Constant и System Parameters смотрите в разделе Parameters.

../_images/s__define-backend-request-mock.jpeg

Parameters

  1. Backend Parameters — если в поле Path были указаны параметры (в фигурных скобках «{}»), то эти параметры необходимо импортировать (нажмите Import Input Parameter) или ввести (нажмите Add Backend Parameter Mapping) в данном блоке настроек.

  2. Constant Parameters — можно определить параметры для получения констант, невидимых для вызывающих API. При запросе серверной службы API Gateway добавляет данные параметры в указанные позиции запроса, а затем отправляет запрос в бэкенд.

  3. System Parameter — можно указать системные параметры запроса.

Примечание

Можно создать не более 50-ти позиций Backend, Constant и System Parameters.

../_images/s__page-parameters.jpeg

Add Backend Policy

Дополнительно к бэкенду по умолчанию можно добавить до 5 дополнительных бэкендов. После добавления новой политики бэкенда нажмите Add Backend Policy, измените нужные параметры настроек, а также заполните следующие поля:

  1. Нажмите Add Backend Policy.

  2. Name — укажите имя новой политики бэкенда.

  3. Effective Mode — выберите режим выполнения условий выбора бэкенда: запрос идет на бэкенд при выполнении любого из условий (Any condition met) или только если все условия будут выполнены (All conditions met).

  4. Policy Conditions — чтобы добавить новое условие, нажмите Add Policy Condition.

../_images/s__page-add-backend-policy.jpeg

Define Response

Введите ответы сервиса и нажмите Finish:

  1. Example Success Response — введите пример отклика на успешно выполненный запрос.

  2. Example Failure Response — введите пример отклика на неудачно выполненный запрос.

Просмотр API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. Нажмите на имя нужного API.

  4. На данной странице вы можете совершить все необходимые операции с API: экспортировать (Export API), перейти в режим отладки (Debug), опубликовать (Publish), перевести API в автономный режим (Take Offline), редактировать (Edit) или удалить (Delete).

  5. На странице API в зависимости от вкладки можно сделать следующее:

    1. Dashboard — доступен URL и, при наличии, доменное имя, а также метрики по вызовам данного API.

    ../_images/s__api-dashboard.jpeg

    1. API Call — отображена схема настройки данного API и основная информация о нем.

    ../_images/s__api-call.jpeg

    1. Authorization — на данной вкладке можно применить (Select App) или отклонить (Cancel Authorization) клиентское приложение (только для способа авторизации App).

    2. Request Throttling Policies — на данной вкладке можно применить (Bind) или отклонить (Unbind) политику регулирования запросов.

    3. Access Control Policies — на данной вкладке можно применить (Bind) или отклонить (Unbind) политику доступа.

    4. Signature Keys — на данной вкладке можно применить (Bind) или отклонить (Unbind) цифровые подписи.

    5. Publication History — на данной вкладке сохраняется история изменений API в разрезе среды, в которой он был опубликован. Здесь можно посмотреть изменения (View Details) и вернуться к одной из версий вашего API (Switch Version).

Изменение API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите More и выберите из списка Edit.

    ../_images/s__apis-more-edit.jpeg

  4. Для переключения между страницами настроек воспользуйтесь кнопками Next или Previous. Измените нужные поля и нажмите Finish.

  5. После внесения изменений в опубликованный API его нужно снова опубликовать Key и соответствующим ему значением (Value) для запросов (Query Parameters) и HTTP-заголовков (Header Parameters).

    1. Body — введите тело запроса (только для методов PATCH, POST или PUT).

    2. Send Request — нажмите кнопку для отправки запроса.

    3. Request — в данном поле отображается отправленный запрос.

    4. Response — в данном поле отображается ответ на запрос.

      ../_images/s__publish-edited-api.jpeg

  6. Из окна отладки можно также перейти к публикации (нажмите Publish) или правке API (нажмите Edit).

Авторизация клиентского приложения (App)

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите Authorize App.

  4. Нажмите Select App, выберите среду (Environment) и приложение и нажмите ОК.

../_images/s__select-app-environment.jpeg

Отмена авторизации клиентского приложения (App)

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите Authorize App.

  4. Нажмите на значок Стрелка вниз и в строке с нужным клиентским приложением нажмите Cancel Authorization.

    ../_images/s__cancel-app-authorize.jpeg

  5. Нажмите Yes.

Публикация API

API можно опубликовать в одной или нескольких средах. Среда по умолчанию — RELEASE.

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите Publish.

  4. Заполните поля и нажмите Publish:

    1. Environment — выберите из списка нужную среду, в которой нужно опубликовать API. Если нужной среды нет, нажмите Create Environment.

    2. Description — введите описание.

Перевод API в автономный режим

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите More и выберите из списка Take Offline.

  4. В поле Environment выберите из списка среду, в которой API нужно перевести в автономный режим, и нажмите Yes.

Импорт API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. Нажмите Import API.

  4. Заполните следующие поля:

    1. Import to — выберите одну из опций:

      • New group — укажите для импорта API в новую группу. При выборе данной опции система автоматически создаст новую группу и загрузит в нее API.

      • Existing group — укажите для импорта API в существующую группу. Выберите из раскрывающегося списка одну из существующих групп, и система загрузит API в нее.

    2. Overwrite (только при выборе Existing group) — при выборе данной опции настройки API перезапишутся в соответствии с загружаемым файлом.

    3. Overwrite Extended Definition — при выборе данной опции политики управления доступом (Access Control) и регулирования запросов (Throttling Policy) импортируемого API перезапишутся в соответствии с загружаемым файлом.

    4. Parameter Import → File — нажмите File и выберите нужный файл для загрузки. Поддерживаются форматы файлов YAML и JSON.

      ../_images/s__settings-import-api.jpeg

  5. В окне редактора также можно сделать следующее:

    1. Check — проверить синтаксис загруженного файла.

    2. Format — отформатировать содержимое файла.

    3. Download — скачать отредактированные данные.

      ../_images/s__parameter-import.jpeg

  6. Для немедленного импорта нажмите Fast Roll Out.

    Чтобы произвести дополнительные настройки API, нажмите Configure Global Settings.

  7. На странице Configure Global Settings измените нужные поля и нажмите Next.

    ../_images/s__configure-global-settings.jpeg

  8. На странице Configure APIs измените нужные поля и нажмите кнопку Submit.

../_images/s__configure-apis.jpeg

Экспорт API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. Нажмите Export API.

    ../_images/s__apis-export-api.jpeg

  4. Заполните следующие поля:

    1. API Group — выберите из списка нужную группу.

    2. Environment — выберите из списка нужную среду.

    3. APIs — нажмите Select API, выберите нужные API к экспорту и нажмите ОК.

    4. API Definition — выберите из списка один из следующих вариантов полноты включения информации в файл экспорта:

      • Full — в файл будет включено описание запроса, бэкенда и ответа на запрос.

      • Extended — в файл будет включено описание запроса, бэкенда и ответа, а также политики регулирования запросов (throttling policy), политики контроля доступа (access control policy) и других настроек API.

      • Basic — в файл будет включено описание запроса и ответа. Описание бэкенда не включено. Также в файл будут включены как стандартные, так и расширенные поля Swagger.

    5. Format — укажите, в каком формате будет экспортируемый файл: JSON или YAML.

    6. Version — укажите версию API для экспорта. Если версия не указана, то будут включены данные на текущую дату и время.

    7. Нажмите Export.

.json или .yaml будет скачан в папку Downloads (Загрузки).

../_images/s__settings-export-api.jpeg

Мониторинг

Для отслеживания показателей API можно использовать встроенные метрики сервиса в разделе Dashboard. Чтобы перейти метрикам:

  1. Перейдите в раздел API Publishing → APIs.

  2. Нажмите на название нужного API.

  3. Перейдите на вкладку Dashboard.

В этом разделе в режиме реального времени можно отслеживать следующие показатели:

  • Requests — количество запросов;

  • Errors — количество запросов с ошибками;

  • Data Traffic — объем переданных данных;

  • Latency — время задержки.

Чтобы перейти более детальному мониторингу в сервисе Cloud Eye, нажмите View Metric.

../_images/s__view-cloudeye-metrics.jpeg

В Cloud Eye доступно больше показателей для мониторинга работы сервиса.

../_images/s__cloudeye-graph.jpeg

Удаление API

  1. В списке сервисов выберите API Gateway.

  2. Далее выберите API Publishing → APIs.

  3. В строке с нужным API нажмите More и выберите из списка Delete.

  4. Введите в поле слово DELETE и нажмите Yes.

Примечание

Удалить можно только неопубликованное API. Сначала переведите API в автономный режим (во всех средах, в которых он опубликован), после чего можно его удалить.

Запустили Evolution free tier
для Dev & Test
Получить