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

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

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

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

• Спецификация OpenAPI.
• A SOAP API.
• Ресурсы Azure, такие как API Azure OpenAI, приложение-функция Azure с триггером HTTP или приложение логики.

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

• Кластер Service Fabric.
• Индивидуальная услуга.

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

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

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

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

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

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

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

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

1. Войдите на портал и перейдите к экземпляру службы "Управление API".
2. В меню слева выберите API>Backends>.
3. На странице серверной части сделайте следующее:
   1. Введите имя серверной части и необязательное описание.
   2. Выберите тип размещения серверной части, например ресурс Azure для ресурса Azure, например приложения-функции или приложения логики, настраиваемый 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. Выберите Создать.

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

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

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

Вы можете использовать условную логику с 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 Management перестает отправлять запросы на серверную службу на определенное время и возвращает клиенту ответ 503 Service Unavailable.
• После настроенного времени путешествия контур сбрасывается и трафик снова направляется к серверу.

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

Пример

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

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

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackend'
  properties: {
    url: 'https://mybackend.com'
    protocol: 'http'
    circuitBreaker: {
      rules: [
        {
          failureCondition: {
            count: 3
            errorReasons: [
              'Server errors'
            ]
            interval: 'PT1H' 
            statusCodeRanges: [
              {
                min: 500
                max: 599
              }
            ]
          }
          name: 'myBreakerRule'
          tripDuration: 'PT1H'  
          acceptRetryAfter: true
        }
      ]
    }
   }
 }

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackend",
  "properties": {
    "url": "https://mybackend.com",
    "protocol": "http",
    "circuitBreaker": {
      "rules": [
        {
          "failureCondition": {
            "count": "3",
            "errorReasons": [ "Server errors" ],
            "interval": "PT1H",
            "statusCodeRanges": [
              {
                "min": "500",
                "max": "599"
              }
            ]
          },
          "name": "myBreakerRule",
          "tripDuration": "PT1H",
          "acceptRetryAfter": true
        }
      ]
    }
  }
}

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

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

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

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

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

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

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

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

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

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

Политики управления API можно использовать для настройки файлов cookie для учета сеанса. Например, в случае с API Помощников (функция Azure OpenAI в Azure AI 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.

resource symbolicname 'Microsoft.ApiManagement/service/backends@2023-09-01-preview' = {
  name: 'myAPIM/myBackendPool'
  properties: {
    description: 'Load balancer for multiple backends'
    type: 'Pool'
    pool: {
      services: [
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1'
          priority: 1
          weight: 3
        }
        {
          id: '/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2'
          priority: 1
          weight: 1
        }
      ],
      "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

{
  "type": "Microsoft.ApiManagement/service/backends",
  "apiVersion": "2023-09-01-preview",
  "name": "myAPIM/myBackendPool",
  "properties": {
    "description": "Load balancer for multiple backends",
    "type": "Pool",
    "pool": {
      "services": [
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-1",
          "priority": "1", 
          "weight": "3" 
        },
        {
          "id": "/subscriptions/<subscriptionID>/resourceGroups/<resourceGroupName>/providers/Microsoft.ApiManagement/service/<APIManagementName>/backends/backend-2",
          "priority": "1",
          "weight": "1"    
        }
      ],
        "sessionAffinity": { 
        "sessionId": { 
          "source": "Cookie", 
          "name": "SessionId" 
        } 
      } 
    }
  }
}

Ограничения

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

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

• Блог: Использование функции прерывателя цепи и балансировки нагрузки Azure API Management с помощью службы Azure OpenAI
• Настройте серверную часть Service Fabric с помощью портала Azure.
• Краткое руководство. Создание пула серверов в Azure API Management с помощью Bicep для балансировки нагрузки запросов OpenAI
• Сведения о событиях, создаваемых Событийной сеткой при срабатывании или сбросе автоматического выключателя шлюзом, см. в разделе "Управление API Azure" в качестве источника событийной сетки. Используйте эти события для выполнения действий перед эскалацией проблем с серверной частью.