Compartir vía

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 determinadas API, API Management configura automáticamente el back-end de API. Por ejemplo, API Management configura el servicio web back-end al importar:

Para otras API, como las API de los servicios de Azure, se importa un recurso de Azure sin especificar explícitamente el servicio back-end. Algunos ejemplos son:

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

Para este backend, puede crear una entidad de backend en API Management y referenciarla en sus API.

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

Configure y administre entidades de back-end en Azure Portal o mediante las API o herramientas de Azure.

Crear un backend

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

Nota:

Al importar determinadas API, como las API de Microsoft Foundry u otros servicios de inteligencia artificial, API Management configura automáticamente una entidad de back-end.

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 , complete los pasos siguientes:
    1. Escriba un nombre para el back-end y una descripción opcional.
    2. Seleccione un tipo de hospedaje back-end, como un recurso de Azure para aplicaciones como Function App o Logic App, 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, puede agregar una regla de disyuntor, cambiar la dirección URL del entorno de ejecución o agregar 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, complete los pasos siguientes:

  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 que configuró 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. Por ejemplo, escriba 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.

Nota:

Asigne también a la identidad administrada los permisos adecuados o un rol RBAC para acceder al servicio back-end. Por ejemplo, si el back-end es un servicio de Azure OpenAI, asigne la identidad administrada al Cognitive Services User rol.

Configuración de certificados para credenciales de autorización

Puede proteger el acceso de puerta de enlace al servicio back-end mediante la autenticación TLS mutua con certificados de cliente o certificados de entidad de certificación (CA) personalizados.

Configuración del certificado de cliente

Si el servicio back-end está protegido con un certificado emitido por una entidad de certificación conocida, puede agregar un certificado de cliente en la entidad back-end:

  1. Agregue el certificado a la instancia de API Management. Puede hacer referencia a un certificado administrado en Azure Key Vault o cargar un archivo PFX.
  2. En la sección Credenciales de autorización de la configuración de back-end, seleccione la pestaña Certificados de cliente .
  3. En la lista desplegable, seleccione el certificado de cliente que desea usar.
  4. Selecciona Crear.

Configuración del certificado de ENTIDAD de certificación

Si el servicio backend utiliza un certificado de autoridad certificadora (CA) personalizado, puede hacer referencia a dicho certificado personalizado en la entidad backend. Es posible que tenga que realizar este paso para establecer la confianza para el certificado de servidor back-end, por ejemplo, con certificados autofirmados, certificados raíz que no son de confianza o cadenas de certificados parciales.

Nota:

Actualmente, solo puede configurar los detalles del certificado CA en una entidad de backend en los niveles v2.

Para agregar información del certificado de entidad de certificación, siga estos pasos:

  1. En la sección Credenciales de autorización de la configuración de back-end, seleccione Certificados de Autoridad de Certificación.
  2. Seleccione + Agregar detalles del certificado CA.
  3. En el panel Agregar certificado de CA , seleccione una de las siguientes opciones:
    • Huella digital del certificado - escriba la huella digital (un hash SHA-1, SHA-256 o SHA-512) de un certificado de autoridad de certificación personalizado.
    • Nombre del sujeto y huella digital del emisor : escriba el nombre del sujeto que identifica de forma única la CA y la huella digital de la CA.
  4. Selecciona Agregar.
  5. Selecciona Crear.

Captura de pantalla de la configuración de los detalles del certificado de CA para un back-end en el portal.

Nota:

Al configurar los detalles de un certificado de entidad de certificación personalizado en la entidad de backend, API Management siempre valida el nombre del certificado y la cadena de certificados, independientemente de que las configuraciones de validación estén habilitadas o deshabilitadas en el backendTlsProperties del backend.

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

Nota:

Como alternativa, puede usar base-url. Por lo general, el formato es https://backend.com/api. No agregue una barra diagonal al final para evitar configuraciones incorrectas. Normalmente, el valor de punto de conexión de base-url y HTTP(S) en el back-end debe coincidir para habilitar una integración perfecta entre front-end y back-end. Tenga en cuenta que las instancias de API Management anexan el nombre del servicio back-end a la base-url.

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

Sugerencia

API Management también detecta y usa automáticamente entidades de back-end cuando recibe solicitudes de API. En tiempo de ejecución, si hay una entidad de back-end que coincide con la dirección URL de un servicio back-end al que API Management envía una solicitud, usa la entidad back-end. No tiene que usar set-backend-serviceexplícitamente .

Disyuntor

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.

Nota:

  • Actualmente, el disyuntor de back-end no se admite en el nivel Consumo de API Management.
  • Debido a la naturaleza distribuida de la arquitectura de API Management, las reglas de recorrido del disyuntor son aproximadas. Las distintas instancias de la puerta de enlace no se sincronizan y aplican reglas de disyuntor en función de la información de la misma instancia.
  • Actualmente, solo puede configurar una regla para un disyuntor del sistema back-end.

Precaución

Si configura un servicio de Azure OpenAI como back-end y el servicio recibe demasiadas solicitudes, devuelve un 429 Too Many Requests código de estado de respuesta y un Retry-After encabezado con un valor que puede ser grande (por ejemplo, 1 día). Con los backends de Azure OpenAI, implemente reglas de disyuntor para gestionar las respuestas de 429 y aceptar la duración de Retry-After.

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.

  1. En Azure Portal, vaya a la instancia de API Management.
  2. En el menú de la izquierda, seleccione APIs>Backends> su backend.
  3. En la página back-end, seleccione Configuración >Configuración del disyuntor>Agregar nuevo.
  4. En la página Crear nuevo disyuntor , configure la regla:
    • Nombre de regla: escriba un nombre para la regla, como myBackend.
    • Recuento de errores: escriba 3.
    • Intervalo de error: deje el valor predeterminado de 1 hora.
    • Intervalo de códigos de estado de error: seleccione 500 - 599.
    • Duración del viaje: deje el valor predeterminado de 1 hora.
    • Compruebe el encabezado "Retry-After" en respuesta HTTP: Seleccione True (Accept).

Grupo de carga equilibrada

API Management admite grupos de backend cuando desea implementar múltiples backend para una API y distribuir las solicitudes de manera equilibrada entre 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 trabajo de un conjunto de back-ends a otro conjunto para la actualización (implementación azul-verde).

Nota:

  • Puede incluir hasta 30 back-end en un grupo.
  • Debido a la naturaleza distribuida de la arquitectura de API Management, el equilibrio de carga de back-end es aproximado. Las distintas instancias de la puerta de enlace no sincronizan ni equilibran la carga en función de la información de la misma instancia.

Opciones de equilibrio de carga

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

Opción de equilibrio de carga Descripción
Round robin De manera predeterminada, las solicitudes se distribuyen uniformemente entre los back-end del grupo.
Ponderado Asigne pesos a los backend del grupo y distribuya las peticiones en función del peso relativo de cada backend. Resulta útil para escenarios como implementaciones azul-verde.
Basado en prioridades Organice los back-end en grupos de prioridad. En primer lugar, envíe solicitudes a grupos de mayor prioridad; dentro de un grupo, distribuya las solicitudes uniformemente o según los pesos asignados.

Nota:

El servicio API Management usa back-end en grupos de prioridad baja solo cuando todos los backend de grupos de mayor prioridad no están disponibles porque las reglas del disyuntor se tripan.

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 asegurar que todas las solicitudes de un usuario específico durante una sesión vayan al mismo backend del grupo. 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.

Nota:

El reconocimiento de la sesión en grupos de carga equilibrada se publica primero en el grupo de actualizacionesanticipadas de la puerta de enlace de IA.

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 de asistentes (una característica de Azure OpenAI en Microsoft Foundry Models), el cliente debe mantener el identificador de sesión, extraer el identificador de subproceso del cuerpo y mantener el par y 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.

  1. En Azure Portal, vaya a la instancia de API Management.
  2. En el menú de la izquierda, seleccione APIs>Backends> su backend.
  3. En la página Back-ends, seleccione la pestaña Equilibrador de carga.
  4. Seleccione + Crear nuevo grupo.
  5. En la página Crear nuevo grupo de carga equilibrada , escriba la siguiente información:
    • Nombre: escriba un nombre para el grupo, como myBackendPool.
    • Descripción: opcionalmente, escriba una descripción.
    • Agregar back-end al grupo: seleccione uno o varios back-end para agregar al grupo.
    • Peso y prioridad del backend: Seleccione Personalizar peso y prioridad para configurar el peso y la prioridad de cada backend del grupo. Por ejemplo, si ha agregado dos backends llamados backend-1 y backend-2, establezca el peso de backend-1 en 3 y el peso de backend-2 a 1, y establezca la prioridad de ambos backends en 1.
    • Selecciona Crear.

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 puede configurar una regla para un disyuntor del sistema back-end.

Contenido relacionado

  • Last updated on