Выбор подходящей политики управления API
Политики управления API можно использовать для управления поведением развернутого API без необходимости переписывать его код.
В вашей организации по выпуску настольных игр есть набор API, позволяющий партнерским организациям узнавать приблизительную стоимость, сотрудникам — проверять уровень запасов, а клиентам — размещать заказы. Вы хотите решить определенную проблему с производительностью и узнать, чего еще можно достичь с помощью политик.
Сначала давайте узнаем, для чего можно использовать политики.
Что такое политики?
В службе управления API Azure администраторы могут использовать политики, чтобы изменять поведение API-интерфейсов с помощью конфигурации. Основная функциональность и поведение API создаются разработчиками, которые пишут код. Однако администраторы могут использовать политики для установки ограничений, преобразования форматов ответов или соблюдения требований безопасности. В этом модуле мы обсудим использование политик для настройки кэша и управления им.
Политики состоят из отдельных инструкций, выполняющихся по порядку. Документы политики являются XML-структурами, содержащими элементы, которые можно использовать для управления поведением API.
Когда выполняются политики?
В службе управления API Azure политики выполняются в четырех разных ситуациях.
- Входящий трафик: эти политики выполняются при получении запроса от клиента.
- Серверная часть: эти политики выполняются перед перенаправлением запроса в управляемый API.
- Исходящий трафик: эти политики выполняются до отправки ответа клиенту.
- При возникновении исключения эти политики выполняются при возникновении исключения.
В XML-файле политики существует отдельный тег для каждой из этих ситуаций:
<policies>
<inbound>
<base />
<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
</check-header>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
</outbound>
<on-error>
<base />
</on-error>
</policies>
В этом примере видно, что политика проверяет входящие запросы для заголовка с именем Авторизация. Если такой заголовок не указан, политика отображает сообщение об ошибке.
Эта политика также преобразует все исходящие ответы в формате JSON в XML.
Области политики
Область действия политики определяет, как широко она будет применяться. Ниже приведены область политики, из которых можно выбрать:
- Глобальный
- Продукт
- API
- Операция
Глобальный
Политики, применяемые в глобальной области, влияют на все API в пределах экземпляра службы управления API.
Чтобы использовать глобальную область, на панели службы управления API в левой части меню в разделе Управление API выберите API, а затем в центральной области меню щелкните все API. Нажмите кнопку "+ Добавить политику" в разделе "Входящий трафик" или "Исходящий трафик", чтобы просмотреть политики, которые можно добавить в этом область.
В доступных вариантах сделайте выбор, чтобы запустить мастер, который поможет добавить политику с правильным синтаксисом:
Вы также можете открыть редактор XML непосредственно, выбрав символ <тега /> в разделах "Входящие", "Исходящая обработка" или "Серверная часть". Открывшийся редактор политики вмещает содержимое XML по умолчанию. Справа выберите "Показать фрагменты" , чтобы найти сочетания клавиш, которые добавляют политики:
Продукт
В службе управления API можно собрать в одном продукте один или несколько API и управлять доступом к этому продукту как единой сущностью. Политики, применяемые в области продукта, влияют на все API-интерфейсы в этом продукте. API-интерфейсы в других продуктах не затрагиваются. При управлении продуктом в портал Azure выберите область "Политики", чтобы добавить политики с помощью интерактивного мастера или с помощью редактора политик XML:
API
Политики, применяемые на уровне API, влияют только на один API. Чтобы задать политику в область API, на домашней странице Управление API выберите API, а затем выберите API, которым требуется управлять. Наконец, на вкладке "Конструктор " выберите "Все операции". Вы можете задать политики входящего, исходящего трафика или серверной части, которые применяются ко всем операциям в этом API:
Операция
Политики, применяемые на уровне операции, влияют только на одну операцию в API. В приведенном ниже примере администратор выбрал операцию GetSpeaker в Demo Conference API и может настроить политики для входящего и исходящего трафика или серверной части, которые применимы только к этой операции:
В каком порядке применяются политики?
Используйте тег <base />, чтобы определить, когда применяются политики из вышестоящей области. Например, рассмотрим эту политику, которая применяется на уровне API:
<policies>
<inbound>
<base />
<find-and-replace from="game" to="board game" />
</inbound>
</policies>
<base> Так как тег отображается над <find-and-replace> тегом, Azure Управление API сначала применяет политики из глобальных и продуктов область, а затем выполняет политику поиска и замены.
Часто используемые политики
Давайте рассмотрим некоторые действия, которые можно выполнять с помощью политик в службе управления API. Мы введем некоторые из наиболее часто используемых политик, и вы можете ознакомиться с Управление API документацией по полному списку и примерам.
Политики ограничения доступа
Существует несколько политик, которые можно использовать для предотвращения или ограничения доступа к API или его операциям. Например:
Используйте политику заголовка HTTP, чтобы проверка для свойства в заголовке HTTP. Если свойство не найдено, Azure Управление API удаляет запрос.
Политика Ограничение частоты вызовов по подписке ограничивает число вызовов, которые могут поступать из одной подписки API. Эта политика гарантирует, что пользователи из одной подписки не будут применять всю пропускную способность.
Если вы хотите ограничить количество вызовов, поступающих с единым ключом доступа, используйте политику Ограничение частоты вызовов по ключу.
Чтобы разрешить или запретить вызовы с конкретных IP-адресов или диапазонов IP-адресов, используйте политику Ограничение IP-адресов вызывающего объекта. Таким образом, ограничение доступа будет осуществляться как ограничения IP-адресов, которые вы применяете в брандмауэре.
Политики проверки подлинности
Несколько политик позволяют управлять проверкой подлинности. Например:
Используйте политику аутентификации с помощью базовой политики, чтобы включить проверку подлинности в виде обычного текста. Эта форма проверки подлинности широко поддерживается, но помните, что следует защитить ее с помощью SSL-шифрования; В противном случае злоумышленник может перехватывать учетные данные по мере того, как они пересекают сеть.
Используйте политику Проверка подлинности с помощью сертификата клиента, чтобы клиенты могли проходить проверку подлинности, предоставив сертификат клиента.
Междоменные политики
Междоменные запросы считаются угрозами безопасности и отклоняются браузерами и API. Однако они могут быть желательными для определенных операций, а политики Управление API позволяют безопасно разрешать их.
Используйте политику Разрешить междоменные вызовы, чтобы разрешить вызовы от Adobe Flash и Silverlight. Если API или клиентские приложения основаны на предоставлении общего доступа к ресурсам (CORS), используйте политику CORS, чтобы разрешить их.
Код AJAX, который выполняется в браузере, использует формат JSON с заполнением для безопасного выполнения междоменных вызовов. Используйте политику JSONP, чтобы разрешить клиентам использовать этот прием.
Политики преобразования
Часто бывает полезно изменить формат или содержимое ответа в управляемом API. Это можно сделать с помощью нескольких политик. Например:
Для преобразования между JSON и XML используйте политики Преобразование JSON в XML и Преобразование XML в JSON. Эти политики часто помогают обеспечить согласованность нескольких API в продукте. Они также могут удалить необходимость перекодировать API, когда приложение ожидает ответ в определенном формате.
Иногда требуется сохранить ответ в формате XML, но изменить его схему. В таких случаях используйте политику Преобразовать XML, чтобы применить шаблон XSLT.
Используйте политику Поиск и замена строки в тексте для выполнения подстановки строки. Например, если имя торговой марки изменилось, эту политику можно использовать, чтобы убедиться, что изменение отражается во всех ответах, даже если базовые данные по-прежнему содержат ссылки на старое имя.
Политика Маскировка URL-адресов в содержимом позволяет переписать все ссылки в тексте ответа, чтобы они указывали на другое расположение. Эта политика полезна в тех случаях, когда веб-сайт или веб-API были перемещены.
Используйте политику Задать текст, чтобы задать текст сообщения для входящих и исходящих запросов.
Если вы хотите изменить входящий HTTP-запрос или исходящий ответ, можно использовать несколько различных политик. Чтобы добавить элементы в существующий ответ или заголовок запроса, используйте политику Задать HTTP-заголовок. Если вам нужно изменить строки запросов, которые отображаются после вопросительного знака в URL-адресе, используйте политику Параметр строки запроса. Если общедоступный URL-адрес, который запросил пользователь, должен сопоставляться с другим внутренним назначением, политика Перезапись URL-адреса может выполнить преобразование входящего и исходящего трафика.
Расширенные политики
Эти политики целесообразно использовать в сценариях, когда требуется нестандартное поведение.
Например, если вы хотите применить политику только в том случае, когда ответ передает определенный тест, используйте политику Поток управления.
Используйте политику Перенаправляющий запрос для перенаправления запросов к внутреннему серверу.
Для управления тем, что происходит, когда действие завершается неудачей, используйте политику повтора. Операторы политики, заключенные в повторе, будут постоянно выполнять свои функции, пока условие не будет удовлетворено. Выполнение будет повторяться через определенные промежутки времени и до указанного количества повторных попыток.
Политика Отправка одностороннего запроса отправляет запрос на указанный URL-адрес и не ожидает ответа.
Если вы хотите сохранить значение для использования в последующих вычислениях или тесте, используйте политику Задание переменной, чтобы сохранить значение в именованной переменной.