Руководство: Преобразование и защита вашего API

ОБЛАСТЬ ПРИМЕНЕНИЯ: все уровни управления API

В этом руководстве вы узнаете о настройке политик для защиты или преобразования API. Политики — это коллекция инструкций, которые выполняются последовательно в запросе или ответе API, изменяющего поведение API.

Например, может потребоваться задать пользовательский заголовок ответа. Или защитите внутренний API, настроив политику ограничения скорости, чтобы API не перепользовался разработчиками. Эти примеры — это простое введение в политики Управление API. Дополнительные параметры политики см. в статье Политики Управления API.

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

Предварительные условия

• Ознакомьтесь с терминологией службы управления API в Azure.
• Ознакомьтесь с концепцией использования политик в службе управления API в Azure.
• Завершите выполнение следующего быстрого старта: Создание экземпляра службы управления API Azure. В этом руководстве мы рекомендуем использовать один из классических или уровней v2, например, уровень "Разработчик" или уровень "Базовый v2". Уровень потребления не поддерживает все политики, используемые в этом руководстве.
• Также выполните задачи из руководства по импорту и публикации первого API.

Перейдите к вашему экземпляру службы управления API.

1. На портале Azure найдите и выберите службы управления API:

   

2. На странице управления API выберите ваш экземпляр службы управления API:

   

Проверка исходного ответа

Чтобы увидеть исходный ответ, сделайте следующее.

1. В своем экземпляре службы управления API выберите API.
2. Выберите Swagger Petstore из списка API.
3. Выберите вкладку Тест в верхней части экрана.
4. Выберите операцию GET Finds pets by status и, при необходимости, выберите другое значение параметра status запроса. Выберите Отправить.

Исходный ответ API должен выглядеть так:

Преобразуйте API для добавления настраиваемого заголовка ответа

Управление API включает несколько политик преобразования, которые можно использовать для изменения полезных данных запроса или ответа, заголовков или кодов состояния. В этом примере вы задаете пользовательский заголовок ответа в ответе API.

Настройка политики преобразования

В этом разделе показано, как настроить заголовок ответа с помощью политики set-header. Здесь вы используете редактор политики на основе форм, упрощающий настройку политики.

1. Выберите Swagger Petstore>Проектирование>Все операции.

2. В разделе Outbound processing (Обработка исходящих данных) выберите + Add policy (Добавить политику).

   

3. В окне Add outbound policy (Добавление политики исходящего трафика) выберите Set headers (Задать заголовки).

   

4. Чтобы настроить политику заголовков Set, сделайте следующее:

   1. В разделе "Имя" введите Custom.
   2. В разделе "Значение" выберите + Добавить значение. Введите "Мое настраиваемое значение".
   3. Выберите Сохранить.

5. После настройки элемент политики set-header появится в разделе обработки исходящего трафика.

   

Защита API с помощью добавления политики ограничения скорости (регулирование)

В этом разделе показано, как добавить защиту в API серверной части, настроив ограничения частоты запросов, чтобы разработчики не злоупотребляли API. В этом примере показано, как настроить rate-limit-by-key политику с помощью редактора кода. В этом примере ограничение равно трем вызовам в 15 секунд. Через 15 секунд разработчик может снова повторять вызов API.

1. Выберите Swagger Petstore>Проектирование>Все операции.

2. В разделе Inbound processing (Обработка исходящих запросов) выберите значок редактора кода (</>).

   

3. Поместите курсор на элемент <inbound> на пустой строке. Затем выберите Show snippets (Показать фрагменты) в правом верхнем углу экрана.

   

4. На панели справа в разделе Access restriction policies (Политики ограничения доступа) выберите Limit call rate per key (Ограничить частоту вызовов для одного ключа).

   Элемент <rate-limit-by-key /> будет вставлен в позицию, обозначенную курсором.

   

5. Замените код <rate-limit-by-key /> в элементе <inbound> следующим фрагментом: Затем выберите Сохранить.

   <rate-limit-by-key calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
   

проверка преобразований.

Если на этом этапе взглянуть на код в редакторе, ваши политики будут выглядеть так:

<policies>
     <inbound>
         <rate-limit calls="3" renewal-period="15" counter-key="@(context.Subscription.Id)" />
         <base />
     </inbound>
     <outbound>
         <set-header name="Custom" exists-action="override">
             <value>"My custom value"</value>
           </set-header>
         <base />
     </outbound>
     <on-error>
         <base />
     </on-error>
 </policies>

Оставшаяся часть этого раздела посвящена проверке преобразований политики, которые вы задали в этой статье.

Проверка пользовательского заголовка ответа

1. Выберите Swagger Petstore>Тест.

2. Выберите операцию GET Finds pets by status и, при необходимости, выберите другое значение параметра status запроса. Выберите Отправить.

   Как видно, добавляется пользовательский заголовок ответа:

   

Проверка предела скорости (регулирования)

1. Выберите Swagger Petstore>Тест.

2. Выберите команду GET "Найти домашних животных по состоянию". Выберите Отправить несколько раз подряд.

   После отправки слишком большого количества запросов в настроенный период вы получите ответ на 429 слишком много запросов .

   

3. Подождите не менее 15 секунд, а затем выберите Отправить снова. Теперь вы должны получить ответ 200 — ОК.

Воспользуйтесь помощью Copilot

Вы можете получить помощь по искусственному интеллекту от Copilot для создания и изменения определений политик управления API. Вы можете использовать Copilot для создания и обновления политик, соответствующих определенным требованиям, без необходимости знать синтаксис XML. Вы также можете получить объяснения существующих политик. И Copilot может помочь вам перевести политики, которые, возможно, были настроены в других решениях по управлению API.

• Microsoft Copilot в Azure предоставляет помощь по разработке политик с запросами на естественном языке на портале Azure. Вы можете создать политики в редакторе политик управления API и попросить Copilot объяснить разделы политики.
• GitHub Copilot для Azure в Visual Studio Code предоставляет помощь по разработке политик в Visual Studio Code, и вы можете использовать расширение управления API Azure для Visual Studio Code для ускорения настройки политики. Вы можете использовать естественный язык, чтобы запросить у Copilot Chat или Copilot Edits создание и уточнение определений политики на месте.

Пример запроса:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot работает на основе искусственного интеллекта, поэтому возможны сюрпризы и ошибки. Подробности см. в Общие вопросы об использовании Copilot.

Итоги

Из этого руководства вы узнали, как:

Следующие шаги

Перейдите к следующему уроку: