Directivas de Azure API Management

  • Artículo

SE APLICA A: todos los niveles de API Management

En Azure API Management, los publicadores de API pueden cambiar el comportamiento de la API a través de la configuración mediante directivas. Las directivas son una colección de declaraciones que se ejecutan secuencialmente en la solicitud o respuesta de una API. API Management proporciona más de 50 directivas listas para usar para abordar escenarios comunes de API, como la autenticación, la limitación de velocidad, el almacenamiento en caché y la transformación de solicitudes o respuestas. Para obtener una lista completa, consulte Referencia de directivas de API Management.

Entre las directivas populares se incluyen:

  • Conversión de formato de XML a JSON
  • Limitación de la frecuencia de llamadas para restringir el número de llamadas entrantes de un desarrollador.
  • Filtrado de solicitudes procedentes de determinadas direcciones IP

Las directivas se aplican en la puerta de enlace entre el consumidor de la API y la API administrada. Mientras que la puerta de enlace recibe solicitudes y las reenvía, sin modificaciones, a la API subyacente, una directiva puede aplicar cambios tanto en la solicitud entrante como en la respuesta saliente.

Descripción de la configuración de directivas

Las definiciones de directiva son documentos XML simples que describen una secuencia de instrucciones que se aplicarán a las solicitudes y respuestas. Para ayudarle a configurar definiciones de directiva, el portal proporciona estas opciones:

  • Un editor guiado basado en formularios para simplificar la configuración de directivas populares sin codificar el XML.
  • Un editor de código donde puede insertar fragmentos de XML o editar XML directamente.

Para obtener más información sobre la configuración de directivas, consulte Establecimiento o edición de directivas.

La configuración XML de directiva se divide en las secciones inbound, backend, outbound y on-error. Esta serie de instrucciones de una directiva determinada se ejecuta en orden para una solicitud y una respuesta.

<policies>
  <inbound>
    <!-- statements to be applied to the request go here -->
  </inbound>
  <backend>
    <!-- statements to be applied before the request is forwarded to 
         the backend service go here -->
  </backend>
  <outbound>
    <!-- statements to be applied to the response go here -->
  </outbound>
  <on-error>
    <!-- statements to be applied if there is an error condition go here -->
  </on-error>
</policies>

Para obtener ejemplos de la directiva XML, consulte Repositorio de fragmentos de código de directiva de API Management.

Control de errores

Si se produce un error durante el procesamiento de una solicitud:

  • Los pasos restantes de las secciones inbound, backend o outbound se omiten.
  • La ejecución salta a las instrucciones de la sección on-error.

Al colocar instrucciones de directiva en la sección on-error, puede hacer lo siguiente:

  • Revise el error mediante la propiedad context.LastError.
  • Inspeccione y personalice la respuesta del error mediante la directiva set-body.
  • Configure lo que sucede si se produce un error.

Para más información, consulte Control de errores en las directivas de administración de API.

Expresiones de directiva

Salvo que la directiva especifique lo contrario, las expresiones de directiva pueden utilizarse como valores de atributo o valores de texto en cualquiera de las directivas de API Management. Una expresión de directiva es:

  • una sola instrucción de C# incluida en @(expression), o
  • un bloque de código de C# de varias instrucciones incluido en @{expression}, que devuelve un valor.

Cada expresión tiene acceso a la variable de context proporcionada de forma implícita y a un subconjunto permitido de tipos de .NET Framework.

Las expresiones de directiva proporcionan un medio sofisticado para controlar el tráfico y modificar el comportamiento de la API sin necesidad de escribir código especializado ni modificar servicios back-end. Algunas directivas como Flujo de control y Establecer variable se basan en expresiones de directiva.

Ámbitos

API Management le permite definir directivas en los siguientes ámbitos, desde el más amplio al más estrecho:

  • Global (todas las API)
  • Área de trabajo (todas las API asociadas a un área de trabajo seleccionada)
  • Producto (todas las API asociadas a un producto seleccionado)
  • API (todas las operaciones de una API)
  • Operación (operación única en una API)

Al configurar una directiva, debe seleccionar en primer lugar el ámbito en el que se debe aplicar.

Ámbitos de la directiva

Cosas que debe saber

  • Para obtener un control específico para distintos consumidores de API, puede configurar definiciones de directiva en más de un ámbito.

  • No todas las directivas se admiten en todos los ámbitos y secciones de directivas.

  • Al configurar definiciones de directiva en más de un ámbito, se controla la herencia de la directiva de control y el orden de evaluación de las directivas en cada sección de directiva mediante la selección de la ubicación del elemento base.

  • Las directivas aplicadas a las solicitudes de API también se ven afectadas por el contexto de solicitud, incluida la presencia o ausencia de una clave de suscripción usada en la solicitud, la API o el ámbito del producto de la clave de suscripción y si la API o el producto requieren una suscripción.

    Nota:

    Si usa una suscripción con ámbito de API, una suscripción a todas las API o la suscripción integrada de acceso completo, las directivas configuradas en el ámbito del producto no se aplican a las solicitudes de esa suscripción.

Para más información, consulte:

Directivas de resolución de GraphQL

En API Management, un solucionador de GraphQL se configura mediante directivas cuyo ámbito son un tipo de operación y un campo específicos en un esquema GraphQL.

  • Actualmente, API Management admite resoluciones de GraphQL que especifican orígenes de datos HTTP API, Cosmos DB o Azure SQL. Por ejemplo, configura una sola directiva http-data-source con elementos para especificar una solicitud a (y opcionalmente una respuesta de) una fuente de datos HTTP.
  • No se puede incluir una directiva de solucionador en definiciones de directiva en otros ámbitos, como API, producto o todas las API. Tampoco hereda las directivas configuradas en otros ámbitos.
  • La puerta de enlace evalúa una directiva con ámbito de solucionador después de las directivas inbound y backend configuradas en la canalización de ejecución de directivas.

Para obtener más información, consulte Configuración de una resolución de GraphQL.

Obtenga ayuda para crear directivas mediante Microsoft Copilot para Azure (versión preliminar)

Microsoft Copilot para Azure (versión preliminar) proporciona funcionalidades de creación de directivas para Azure API Management. Use Copilot para Azure en el contexto del editor de directivas de API Management para crear directivas que se ajusten a los requisitos específicos sin necesidad de conocer la sintaxis ni de que le expliquen directivas ya configuradas.

Puede pedir a Copilot que Azure genere definiciones de directiva y, a continuación, copie los resultados en el editor de directivas y realice los ajustes necesarios. Haga preguntas para obtener información sobre diferentes opciones, modifique la directiva proporcionada o aclare la directiva que ya tiene. Más información

Importante

Microsoft Copilot para Azure (versión preliminar) necesita registro y actualmente solo está disponible para asociados y clientes empresariales aprobados. Para más información, consulte Acceso limitado a Microsoft Copilot para Azure (versión preliminar).

Ejemplos

Aplicación de las directivas especificadas en distintos ámbitos

Si tiene una directiva en el nivel global y una directiva configurada para una API, cuando se use esa API en concreto, se aplicarán ambas directivas. API Management permite el orden determinista de las instrucciones de directiva combinadas mediante el elemento base.

Definición de la directiva de ejemplo en el ámbito de la API:

<policies>
    <inbound>
        <cross-domain />
        <base />
        <find-and-replace from="xyz" to="abc" />
    </inbound>
</policies>

En la definición de directiva de ejemplo anterior:

  • La instrucción cross-domain se ejecuta primero.
  • La directiva find-and-replace se ejecuta después de cualquier directiva en un ámbito más amplio.

Nota

Si quita el elemento base del ámbito de la API, solo se aplicarán las directivas configuradas en el ámbito de la API. No se aplicarán las directivas de producto ni las de ámbito global.

Uso de expresiones de directiva para modificar solicitudes

En el ejemplo siguiente se usan expresiones de directiva y la directiva set-header para agregar datos de usuario a la solicitud entrante. El encabezado agregado incluye el identificador de usuario asociado a la clave de suscripción en la solicitud y la región donde se hospeda la puerta de enlace que procesa la solicitud.

<policies>
    <inbound>
        <base />
        <set-header name="x-request-context-data" exists-action="override">
            <value>@(context.User.Id)</value>
            <value>@(context.Deployment.Region)</value>
      </set-header>
    </inbound>
</policies>

Contenido relacionado

Para más información sobre el trabajo con directivas, vea: