Back-ends de API Management

SE APLICA A: todos los niveles de API Management

Un back-end (o back-end de API) de API Management es un servicio HTTP que implementa la API de front-end y sus operaciones.

Al importar ciertas API, API Management configura el back-end de la API automáticamente. Por ejemplo, API Management configura el servicio web back-end al importar:

• Una especificación de OpenAPI.
• Una API de SOAP.
• Recursos de Azure, como una API de Azure OpenAI, una aplicación de funciones de Azure desencadenada por HTTP o una aplicación lógica.

API Management también admite el uso de otros recursos de Azure como back-end de API, por ejemplo:

• Un Clúster de Service Fabric.
• Un servicio personalizado.

Ventajas de los back-ends

API Management admite entidades de back-end para que pueda administrar los servicios back-end de la API. Una entidad de back-end encapsula información sobre el servicio back-end y promueve la reutilización entre API y una gobernanza mejorada.

Use back-ends para uno o varios de los siguientes elementos:

• Autorizar las credenciales de las solicitudes al servicio back-end
• Aproveche la funcionalidad de API Management para mantener secretos en Azure Key Vault si los valores con nombre están configurados para la autenticación de parámetros de consulta o encabezado.
• Definir reglas de disyuntor para proteger el back-end de demasiadas solicitudes
• Enrutar o equilibrar la carga de solicitudes a varios back-ends

Las entidades de back-end se configuran y administran en Azure Portal o mediante las API o las herramientas de Azure.

Crear un backend

Puede crear un back-end en Azure Portal o mediante las API o herramientas de Azure.

Para crear un back-end en el portal:

1. Inicie sesión en el portal y vaya a la instancia de API Management.
2. En el menú de la izquierda, seleccione API>Backends>+ Create new backend (Crear nuevo back-end).
3. En la página Back-end , haga lo siguiente:
   1. Escriba un nombre para el back-end y una descripción opcional.
   2. Seleccione un tipo de hospedaje back-end, por ejemplo, recurso de Azure para un recurso de Azure, como una aplicación de funciones o aplicación lógica, una dirección URL personalizada para un servicio personalizado o un clúster de Service Fabric .
   3. En URL de tiempo de ejecución, escriba la dirección URL del servicio back-end a la que se reenvían las solicitudes de API.
   4. En Opciones avanzadas, deshabilite opcionalmente la cadena de certificados o la validación de nombres de certificado para el back-end.
   5. En Agregar este servicio back-end a un grupo de back-end, seleccione o cree un grupo con equilibrio de carga para el back-end.
   6. En Regla de disyuntor, opcionalmente configure un disyuntor para el back-end.
   7. En Credenciales de autorización, puede configurar las credenciales para autorizar el acceso al back-end. Las opciones incluyen un encabezado de solicitud, un parámetro de consulta, un certificado de cliente o una identidad administrada asignada por el sistema o asignada por el usuario configurada en la instancia de API Management.
   8. Selecciona Crear.

Después de crear un back-end, puede actualizar la configuración de back-end en cualquier momento. Por ejemplo, agregue una regla de disyuntor, cambie la dirección URL del entorno de ejecución o agregue credenciales de autorización.

Configuración de la identidad administrada para las credenciales de autorización

Puede usar una identidad administrada asignada por el sistema o asignada por el usuario configurada en la instancia de API Management para autorizar el acceso al servicio back-end. Para configurar una identidad administrada para las credenciales de autorización, haga lo siguiente:

1. En la sección Credenciales de autorización de la configuración de back-end, seleccione la pestaña Identidad administrada y seleccione Habilitar.

2. En Identidad de cliente, seleccione Identidad asignada por el sistema o una identidad asignada por el usuario configurada en la instancia.

3. En Resource ID (Identificador de recurso), escriba un servicio de Azure de destino o el identificador de aplicación de su propia aplicación de Microsoft Entra que represente el back-end. Ejemplo: https://cognitiveservices.azure.com para el servicio Azure OpenAI.

   Para obtener más ejemplos, consulte la referencia de la política de autenticación gestionada por identidad.

4. Selecciona Crear.

Hacer referencia al back-end mediante la directiva set-backend-service

Después de crear un back-end, puede hacer referencia al identificador de back-end (nombre) en las API. Use la directiva set-backend-service para dirigir una solicitud de API entrante al back-end. Si ya configuró un servicio web de back-end para una API, puede usar la directiva set-backend-service para redirigir la solicitud a una entidad de back-end en su lugar. Por ejemplo:

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

Puede usar la lógica condicional con la directiva set-backend-service para cambiar el back-end efectivo en función de la ubicación, la puerta de enlace a la que se llamó u otras expresiones.

Por ejemplo, esta es una directiva para enrutar el tráfico a otro back-end en función de la puerta de enlace a la que se llamó:

<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/>

Interruptor automático

API Management expone un propiedadinterruptor de circuito en el recurso backend para proteger un servicio backend de ser abrumado por demasiadas solicitudes.

• La propiedad disyuntor define reglas para disparar el disyuntor, como el número o el porcentaje de condiciones de error durante un intervalo de tiempo definido y un intervalo de códigos de estado que indican errores.
• Cuando el disyuntor se dispara, API Management deja de enviar solicitudes al servicio back-end durante un tiempo definido y devuelve una respuesta "503 Servicio no disponible" al cliente.
• Después de la duración de disparo configurada, el circuito se restablece y el tráfico se reanuda hacia el back-end.

El disyuntor del back-end es una implementación del patrón de disyuntor que permite que el back-end se recupere de situaciones de sobrecarga. Aumenta las directivas generales de limitación de velocidad y limitación de simultaneidad que puede implementar para proteger la puerta de enlace de API Management y los servicios back-end.

Ejemplo

Usar Azure Portal, API Management API de RESTo una plantilla de Bicep o ARM para configurar un disyuntor en un back-end. En el ejemplo siguiente, el interruptor de circuito de myBackend en la instancia de API Management myAPIM recorridos cuando hay tres o más códigos de estado 5xx que indican errores de servidor en 1 hora.

El disyuntor de este ejemplo se restablece después de 1 hora. Si un encabezado de Retry-After está presente en la respuesta, el interruptor acepta el valor y espera el tiempo especificado antes de volver a enviar solicitudes al back-end.

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
        }
      ]
    }
  }
}

Grupo de carga equilibrada

API Management admite grupos de backend, cuando desea implementar varios backend para una API y solicitudes de equilibrio de carga en esos backend. Un grupo es una colección de back-end que se tratan como una sola entidad para el equilibrio de carga.

Use un grupo de back-end para escenarios como los siguientes:

• Extienda la carga a varios back-ends, que pueden tener disyuntores de back-end individuales.
• Cambie la carga de un conjunto de back-ends a otro para su actualización (implementación azul-verde).

Opciones de equilibrio de carga

API Management admite las siguientes opciones de equilibrio de carga para los grupos de backend:

Reconocimiento de la sesión

Con cualquiera de las opciones de equilibrio de carga anteriores, puede habilitar el reconocimiento de sesión (afinidad de sesión) para asegurarse de que todas las solicitudes de un usuario específico durante una sesión se dirigen al mismo back-end del conjunto. API Management establece una cookie de identificador de sesión para mantener el estado de la sesión. Esta opción es útil, por ejemplo, en escenarios con backends, como asistentes de chat de IA, u otros agentes de conversación, para enrutar las solicitudes de la misma sesión al mismo endpoint.

Administración de cookies para el reconocimiento de sesiones

Al usar el reconocimiento de la sesión, el cliente debe controlar las cookies correctamente. El cliente debe almacenar el valor del Set-Cookie encabezado y enviarlo con solicitudes posteriores para mantener el estado de sesión.

Puede usar directivas de API Management para ayudar a establecer cookies para el reconocimiento de la sesión. Por ejemplo, en el caso de la API Assistants (una característica de Azure OpenAI en Azure AI Foundry Models), el cliente debe mantener el identificador de sesión, extraer el identificador de subproceso del cuerpo y conservar el par, además de enviar la cookie adecuada para cada llamada. Además, el cliente debe saber cuándo enviar una cookie o cuándo no enviar un encabezado de cookie. Estos requisitos se pueden controlar correctamente mediante la definición de las siguientes directivas de ejemplo:

<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>

Ejemplo

Use el portal API Management API de REST, o una plantilla de Bicep o ARM para configurar un grupo de back-end. En el ejemplo siguiente, el back-end myBackendPool en la instancia de API Management myAPIM está configurado con un grupo de back-end. Los back-end de ejemplo del grupo se denominan backend-1 y backend-2. Ambos back-end están en el grupo de prioridad más alta; dentro del grupo, backend-1 tiene un peso mayor que backend-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" 
        } 
      } 
    }
  }
}

Limitaciones

• Para los niveles Desarrollador y Prémium, una instancia de API Management implementada en una red virtual interna puede producir errores HTTP 500 BackendConnectionFailure cuando la dirección URL del punto de conexión de la puerta de enlace y la dirección URL de back-end son la misma. Si encuentra esta limitación, siga las instrucciones del artículo Limitación de solicitudes de API Management autoencadenadas en modo de red virtual interna en el blog de nuestra comunidad tecnológica.
• Actualmente, solo se puede configurar una regla para un disyuntor back-end.

Contenido relacionado

• Blog: Uso del disyuntor de Azure API Management y el equilibrio de carga con Azure OpenAI Service
• Configuración de un back-end de Service Fabric mediante Azure Portal.
• Inicio rápido: Creación de un grupo de back-end en Azure API Management mediante Bicep para equilibrar la carga de solicitudes de OpenAI
• Consulte Azure API Management como origen de Event Grid para obtener información sobre los eventos de Event Grid generados por la puerta de enlace cuando se realiza una interrupción del circuito o se restablece. Use estos eventos para tomar medidas antes de que se escalen los problemas de back-end.