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 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
ooutbound
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.
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
ybackend
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 en Azure (versión preliminar)
Microsoft Copilot en Azure (versión preliminar) proporciona funcionalidades de creación de directivas para Azure API Management. Use Copilot en 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 en Azure que genere definiciones de directivas y, luego, copiar los resultados en el editor de directivas y hacer 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
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:
- Tutorial: Transformación y protección de una API
- Referencia de directivas para una lista completa de instrucciones de directivas y su configuración
- Expresiones de directiva
- Establecimiento o edición de directivas
- Reutilización de configuraciones de directivas
- Repositorio de fragmentos de código de directiva
- Kit de herramientas de directivas de Azure API Management
- Creación de directivas mediante Microsoft Copilot en Azure