Compartir a través de

Directivas de Azure API Management

SE APLICA A: Todos los niveles de API Management

En Azure API Management, los publicadores de API pueden cambiar el comportamiento de la API configurando directivas. En este artículo se describe cómo usar 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 75 directivas listas para configurar 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 velocidad 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. Aunque la puerta de enlace recibe solicitudes y las reenvía, sin modificar, a la API subyacente, una directiva puede aplicar cambios tanto a la solicitud entrante como a 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. Así es como se ve:

<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's an error condition go here -->
  </on-error>
</policies>

Para ver ejemplos XML de directiva, 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 context.LastError propiedad .
  • Inspeccione y personalice la respuesta de error mediante la política set-body.
  • Configure lo que sucede si se produce un error.

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

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 de las siguientes:

  • Una sola instrucción de C# incluida en @(expression)
  • 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 ámbitos siguientes, que se presentan aquí de más amplia a más estrecha:

  • 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 (una sola operación en una API)

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

Diagrama que muestra los cinco ámbitos de directiva.

Cosas que debe saber

  • Puede configurar definiciones de políticas en más de un ámbito para un control detallado para distintos consumidores de API.

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

  • Al configurar definiciones de políticas en más de un ámbito, se controla la herencia de políticas y el orden de evaluación de las políticas en cada sección de políticas colocando el 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 resolver de GraphQL se configura con directivas limitadas a un tipo de operación y a un campo específicos en un esquema GraphQL.

  • Actualmente, API Management admite solucionadores de GraphQL que especifican orígenes de datos de API HTTP, Azure Cosmos DB o Azure SQL. Por ejemplo, puede configurar una sola http-data-source directiva con elementos para especificar una solicitud a (y, opcionalmente, responder desde) un origen de datos HTTP.
  • No puede incluir una directiva de resolución en definiciones de directivas en otros ámbitos, como API, producto o todas las API. La directiva 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 más información, consulte Configuración de una resolución de GraphQL.

Obtener ayuda de Copilot

Puede obtener ayuda de inteligencia artificial de Copilot para crear y editar las definiciones de directivas de API Management. Puede usar Copilot para crear y actualizar directivas que coincidan con sus requisitos específicos sin necesidad de conocer la sintaxis XML. También puede obtener explicaciones de las directivas existentes. Y Copilot puede ayudarle a traducir las directivas que podría haber configurado en otras soluciones de API Management.

Mensaje de ejemplo:

Generate a policy that adds an Authorization header to the request with a Bearer token.

Copilot se basa en la inteligencia artificial, por lo que son posibles sorpresas y errores. Para obtener más información, consulte Preguntas más frecuentes sobre el uso general de Copilot.

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 cross-domain instrucción 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. Las directivas configuradas en ámbitos más amplios y de producto no se aplicarán.

Uso de expresiones de directiva para modificar solicitudes

En el ejemplo siguiente se usan expresiones de directiva y la directiva para agregar datos de usuario a las solicitudes set-header. 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, consulte: