Поделиться через

Серверные компоненты в Управлении API

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

Серверная часть (или серверная часть API) в Управлении API — это служба HTTP, которая реализует внешний API и его операции.

При импорте определенных API управление API автоматически настраивает серверную часть API. Например, Управление API настраивает серверную веб-службу при импорте:

Для других API, таких как API из служб Azure, вы импортируете ресурс Azure без явного указания серверной службы. Вот некоторые примеры.

Управление API также поддерживает использование других ресурсов в качестве серверной части API, например:

Для этих серверных компонентов можно создать серверную сущность в службе управления API и ссылаться на нее в API.

Преимущества серверных компонентов

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

Используйте серверы для одного или нескольких из следующих элементов.

  • Авторизация учетных данных запросов в серверную службу
  • Воспользуйтесь функционалом управления API для хранения секретов в Azure Key Vault, если именованные значения настроены для аутентификации через параметры заголовка или запроса.
  • Определение правил разбиения цепи для защиты серверной части от слишком большого количества запросов
  • Маршрутизация или балансировка нагрузки запросов к нескольким серверным службам

Настройте и управляйте сущностями серверной части на портале Azure или с помощью API или средств Azure.

Создание серверной части

Серверную часть можно создать на портале Azure или с помощью API или средств Azure.

Примечание.

При импорте определенных API, таких как API из Microsoft Foundry или других служб ИИ, управление API автоматически настраивает серверную сущность.

Чтобы создать серверную часть на портале, выполните следующие действия.

  1. Войдите на портал и перейдите к вашей службе управления API.
  2. В меню слева выберите API>Backends>.
  3. На странице серверной части выполните следующие действия.
    1. Введите имя серверной части и необязательное описание.
    2. Выберите тип размещения серверной части, например ресурс Azure для Azure ресурсов, таких как Function App или Logic App, настраиваемый URL-адрес для пользовательской службы или кластер Service Fabric.
    3. В URL-адресе среды выполнения введите URL-адрес серверной службы, в которую пересылаются запросы API.
    4. В разделе "Дополнительно" при необходимости отключите проверку цепочки сертификатов или имени сертификата для серверной части.
    5. В разделе "Добавление этой серверной службы в внутренний пул" при необходимости выберите или создайте пул с балансировкой нагрузки для серверной части.
    6. В разделе правило разбиения цепи при необходимости настройте средство разбиения цепи для серверной части.
    7. В разделе учетные данные авторизации при необходимости настройте учетные данные для авторизации доступа к серверной части. Параметры включают заголовок запроса, параметр запроса, сертификат клиента или назначаемое системой или назначаемое пользователем управляемое удостоверение , настроенное в экземпляре управления API.
    8. Выберите Создать.

После создания серверной части можно в любое время обновить параметры серверной части. Например, можно добавить правило разбиения цепи, изменить URL-адрес среды выполнения или добавить учетные данные авторизации.

Настройка управляемого удостоверения для учетных данных авторизации

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

  1. В разделе учетных данных авторизации конфигурации серверной части выберите вкладку "Управляемое удостоверение " и нажмите кнопку "Включить".

  2. В идентификации клиента выберите либо системную идентификацию, либо назначаемую пользователем идентификацию, которую вы настроили в экземпляре.

  3. В поле "Идентификатор ресурса" введите целевую службу Azure или идентификатор приложения microsoft Entra, представляющего серверную часть. Например, введите https://cognitiveservices.azure.com для службы Azure OpenAI.

    Дополнительные примеры см. в справочнике по политике идентификации, управляемой проверкой подлинности .

  4. Выберите Создать.

Примечание.

Также назначьте управляемому удостоверению соответствующие разрешения или роль RBAC для доступа к службе бекэнда. Например, если серверная часть является службой Azure OpenAI, назначьте управляемому удостоверению роль Cognitive Services User.

Настройка сертификатов для учетных данных авторизации

Вы можете защитить доступ шлюза к серверной службе с помощью взаимной проверки подлинности TLS с сертификатами клиента или пользовательскими сертификатами центра сертификации (ЦС).

Настройка сертификата клиента

Если серверная служба защищена сертификатом, выданным хорошо известным ЦС, можно добавить сертификат клиента в серверную сущность:

  1. Добавьте сертификат в экземпляр системы управления API. Вы можете ссылаться на сертификат, управляемый в Azure Key Vault, или отправить PFX-файл.
  2. В разделе учетных данных авторизации конфигурации серверной части выберите вкладку "Сертификаты клиента ".
  3. В раскрывающемся списке выберите сертификат клиента, который требуется использовать.
  4. Выберите Создать.

Настройка сертификата центра сертификации

Если серверная служба использует пользовательский сертификат ЦС, можно ссылаться на пользовательский сертификат ЦС в серверной сущности. Для установления доверия к сертификату серверной части может потребоваться выполнение данного шага, например, в случае использования самозаверяющих сертификатов, ненадежных корневых сертификатов или частичных цепочек сертификатов.

Примечание.

В настоящее время можно настроить только сведения о сертификате ЦС в бэкэнд-объекте на уровнях v2.

Чтобы добавить сведения о сертификате ЦС, выполните следующие действия.

  1. В разделе учетных данных авторизации конфигурации серверной части выберите сертификаты ЦС.
  2. Выберите + Добавить сведения о сертификате ЦС.
  3. В области добавления сертификата ЦС выберите один из следующих вариантов:
    • Отпечаток сертификата — введите отпечаток (хэш SHA-1, SHA-256 или SHA-512) пользовательского сертификата УЦ.
    • Имя субъекта и отпечаток ЦС - Введите имя субъекта, которое однозначно идентифицирует ЦС, а также отпечаток данного ЦС.
  4. Нажмите кнопку "Добавить".
  5. Выберите Создать.

Снимок экрана: настройка сведений о сертификате удостоверяющего центра для бэкенда на портале.

Примечание.

При настройке сведений о пользовательском сертификате ЦС в серверной сущности управление API всегда проверяет имя сертификата и цепочку сертификатов независимо от того, включите или отключите параметры проверки в серверной части backendTlsProperties.

Подсказка

Вы также можете программно настроить сведения о сертификате ЦС с помощью API управления REST. Установите backendTlsProperties в серверной сущности.

Ссылка на серверную часть с помощью политики set-backend-service

После создания серверной части можно ссылаться на идентификатор серверной части (имя) в API. Используйте политику set-backend-service, чтобы направить входящий запрос API на серверную часть. Если вы уже настроили серверную веб-службу для API, можно использовать set-backend-service политику для перенаправления запроса на серверную сущность. Рассмотрим пример.

<policies>
    <inbound>
        <base />
        <set-backend-service backend-id="myBackend" />
    </inbound>
    [...]
<policies/>

Примечание.

Кроме того, можно использовать base-url. Как правило, формат равен https://backend.com/api. Избегайте добавления косой черты в конце, чтобы предотвратить неправильные настройки. Как правило, значение конечной точки base-url и HTTP(S) в серверной части должно совпадать для обеспечения бесперебойной интеграции между фронтендом и бэкендом. Обратите внимание, что экземпляры управления API добавляют имя серверной службы к base-url.

Вы можете использовать условную логику с set-backend-service политикой для изменения эффективной серверной части в зависимости от расположения, вызываемого шлюза или других выражений.

Например, вот политика маршрутизации трафика в другую серверную часть на основе вызываемого шлюза:

<policies>
    <inbound>
        <base />
        <choose>
            <when condition="@(context.Deployment.Gateway.Id == "factory-gateway")">
                <set-backend-service backend-id="backend-on-prem" />
            </when>
            <when condition="@(context.Deployment.Gateway.IsManaged == false)">
                <set-backend-service backend-id="self-hosted-backend" />
            </when>
            <otherwise />
        </choose>
    </inbound>
    [...]
<policies/>

Подсказка

Управление API также автоматически обнаруживает и использует внутренние сущности при получении запросов API. Во время выполнения, если есть серверная сущность, соответствующая URL-адресу серверной службы, в которую служба управления API отправляет запрос, она использует серверную сущность. Вам не нужно явно использовать set-backend-service.

Средство разбиения цепи

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

  • Свойство автоматического выключателя определяет правила для срабатывания автоматического выключателя, такие как количество или процент отказов в течение определенного интервала времени и диапазон кодов состояний, указывающих на отказы.
  • Когда срабатывает автоматический выключатель, API Management перестает отправлять запросы на серверную службу на определенное время и возвращает клиенту ответ 503 Service Unavailable.
  • После настроенного времени путешествия контур сбрасывается и трафик снова направляется к серверу.

Серверный выключатель — это реализация шаблона разбиения цепи, позволяющего серверной части восстановиться после перегруженных ситуаций. Он расширяет общие политики ограничения скорости и ограничения параллелизма, которые можно реализовать для защиты шлюза Управление API и внутренних служб.

Примечание.

  • В настоящее время серверный выключатель не поддерживается на уровне потребления Управление API.
  • Из-за распределенной природы архитектуры управления API правила размыкания цепи являются приблизительными. Разные экземпляры шлюза не синхронизируются и применяют правила разбиения цепи на основе сведений об одном экземпляре.
  • В настоящее время можно настроить только одно правило для внутреннего разбиения цепи.

Осторожность

Если вы настраиваете службу Azure OpenAI в качестве серверной части, а служба получает слишком много запросов, она возвращает 429 Too Many Requests код состояния ответа и Retry-After заголовок со значением, которое может быть большим (например, 1 день). С помощью серверной части Azure OpenAI реализуйте правила разбиения цепи для обработки 429 ответов и принятия Retry-After длительности.

Пример

Используйте портал Azure, REST API Management, или шаблон Bicep или ARM для настройки предохранителя в серверной части. В следующем примере средство разбиения цепи в myBackend в Управление API экземпляре myAPIM выполняется при наличии трех или более 5xx кодов состояния, указывающих на ошибки сервера в течение 1 часа.

Автоматический выключатель в этом примере сбрасывается через 1 час. Retry-After Если заголовок присутствует в ответе, средство разбиения цепи принимает значение и ожидает указанного времени, прежде чем отправлять запросы в серверную часть снова.

  1. На портале Azure откройте экземпляр API Management.
  2. В меню слева выберите API, >, вашу серверную часть.
  3. На странице администрирования выберите Настройки>Настройки автомата отключения цепи>Добавить новый.
  4. На странице создания нового разбиения цепи настройте правило:
    • Имя правила: введите имя правила, например myBackend.
    • Число сбоев: введите 3.
    • Интервал сбоя: оставьте значение по умолчанию 1 час.
    • Диапазон кода состояния сбоя: выберите 500 – 599.
    • Длительность поездки: оставьте значение по умолчанию 1 час.
    • Проверьте заголовок Retry-After в http-ответе: нажмите кнопку True (Принять).

Пул с балансировкой нагрузки

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

Используйте внутренний пул для таких сценариев, как следующие сценарии:

  • Распределите нагрузку на несколько бекендов, которые могут иметь отдельные аварийные прерыватели.
  • Переместите нагрузку из одного набора серверных компонентов в другой набор для обновления (сине-зеленое развертывание).

Примечание.

  • Вы можете включить в пул до 30 бэкэндов.
  • Благодаря распределенной природе архитектуры управления API балансировка нагрузки на серверной стороне является приблизительной. Разные экземпляры шлюза не синхронизируются и не балансируют нагрузку на основе информации о том же экземпляре.

Параметры балансировки нагрузки

Управление API поддерживает следующие параметры балансировки нагрузки для серверных пулов:

Параметр балансировки нагрузки Описание
Циклическое распределение Запросы по умолчанию распределяются равномерно между серверами в пуле.
весовой Назначьте вес серверной части пула и распределяйте запросы на основе относительного веса каждой серверной части. Полезно для таких сценариев, как сине-зеленые развертывания.
На основе приоритета Упорядочение внутренних серверов в группы приоритетов. Сначала отправлять запросы в группы с более высоким приоритетом; в группе распределяйте запросы равномерно или в соответствии с назначенными весами.

Примечание.

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

Осведомленность о сеансах

Используя любой из предыдущих вариантов балансировки нагрузки, вы можете включить осведомленность о сеансах (сходство сеансов), чтобы убедиться, что все запросы от конкретного пользователя во время сеанса переходят в одну и ту же серверную часть в пуле. Управление API задает файл cookie идентификатора сеанса для поддержания состояния сеанса. Этот параметр полезен, например, в сценариях с бэкендами, такими как чат-ассистенты ИИ или другие разговорные агенты для маршрутизации запросов одного сеанса на один и тот же конечный адрес.

Примечание.

Осведомленность о сеансах в пулах с балансировкой нагрузки выпускается сначала в группу ранних обновленийшлюза ИИ.

Управление файлами cookie для осведомленности о сеансе

При использовании осведомленности о сеансе клиент должен соответствующим образом обрабатывать файлы cookie. Клиент должен сохранить значение заголовка Set-Cookie и отправить его с последующими запросами для поддержания состояния сеанса.

Политики управления API можно использовать для настройки файлов cookie для учета сеанса. Например, в случае API Помощников (функция Azure OpenAI в Microsoft Foundry Models) клиент должен сохранить идентификатор сеанса, извлечь идентификатор потока из тела сообщения, сохранить эту пару значений и отправить правильный файл cookie для каждого вызова. Кроме того, клиент должен знать, когда отправлять файл cookie или когда не отправлять заголовок файла cookie. Эти требования можно обрабатывать соответствующим образом, определив следующие примеры политик:

<policies>
  <inbound>
    <base />
    <set-backend-service backend-id="APIMBackend" />
  </inbound>
  <backend>
    <base />
  </backend>
  <outbound>
    <base />
    <set-variable name="gwSetCookie" value="@{
      var payload = context.Response.Body.As<JObject>();
      var threadId = payload["id"];
      var gwSetCookieHeaderValue = context.Request.Headers.GetValueOrDefault("SetCookie", string.Empty);
      if(!string.IsNullOrEmpty(gwSetCookieHeaderValue))
      {
        gwSetCookieHeaderValue = gwSetCookieHeaderValue + $";Path=/threads/{threadId};";
      }
      return gwSetCookieHeaderValue;
    }" />
    <set-header name="Set-Cookie" exists-action="override">
      <value>Cookie=gwSetCookieHeaderValue</value>
    </set-header>
  </outbound>
  <on-error>
    <base />
  </on-error>
</policies>

Пример

Используйте портал, REST API управления API или шаблон Bicep или ARM для настройки внутреннего пула. В следующем примере серверная часть myBackendPool в экземпляре Система управления API myAPIM настроена на использование серверного пула. Примеры серверов в пуле называются backend-1 и backend-2. Обе серверные части находятся в группе с наивысшим приоритетом; в группе серверная часть-1 имеет больший вес, чем серверная часть-2.

  1. На портале Azure откройте экземпляр API Management.
  2. В меню слева выберите API, >, вашу серверную часть.
  3. На странице серверных частей выберите вкладку Подсистема балансировки нагрузки .
  4. Нажмите кнопку "+ Создать пул".
  5. На странице создания пула с балансировкой нагрузки введите следующие сведения:
    • Имя: введите имя пула, например myBackendPool.
    • Описание. При необходимости введите описание.
    • Добавьте серверные серверы в пул: выберите одну или несколько серверных серверов, чтобы добавить в пул.
    • Внутренний вес и приоритет: выберите "Настроить вес и приоритет ", чтобы настроить вес и приоритет каждой серверной части в пуле. Например, если вы добавили две внутренние серверные части с именем backend-1 и backend-2, установите для внутреннего сервера значение 1 до 3 и вес серверной части-2 до 1, а приоритет обоих серверных компонентов — 1.
    • Выберите Создать.

Ограничения

  • Для уровней Разработчика и Premium экземпляр Управление API, развернутый во внутренней виртуальной сети, может вызывать ошибки HTTP 500BackendConnectionFailure, если URL-адрес конечной точки шлюза и внутренний URL-адрес совпадают. Если вы столкнулись с этим ограничением, следуйте инструкциям, приведенным в статье об ограничении запросов для цепного управления API в режиме внутренней виртуальной сети, опубликованной в блоге Tech Community.
  • В настоящее время можно настроить только одно правило для внутреннего разбиения цепи.

Связанный контент

  • Last updated on