Elección de la directiva adecuada de API Management
Puede usar las directivas de API Management para controlar el comportamiento de una API implementada sin volver a escribir su código.
En la compañía de juegos de mesa, tiene un conjunto de API que permiten a las organizaciones asociadas obtener estimaciones de precios; a los miembros del personal, comprobar los niveles de existencias; y a los clientes, realizar pedidos. Quiere solucionar un problema en particular relacionado con el rendimiento e investigar qué más se puede hacer mediante las directivas.
Primero, echemos un vistazo a qué puede hacer mediante directivas.
¿Qué son las directivas?
En Azure API Management, los administradores pueden usar directivas para modificar el comportamiento de las API mediante la configuración. La funcionalidad y el comportamiento principales de una API están diseñados por los desarrolladores que escriben el código. Aun así, los administradores pueden usar directivas para establecer límites, convertir formatos de respuesta o aplicar requisitos de seguridad. En este módulo nos concentraremos en el uso de las directivas para configurar y controlar una caché.
Las directivas se componen de instrucciones individuales que se ejecutan en orden. Los documentos de directiva son estructuras XML que contienen elementos que puede usar para controlar el comportamiento de la API.
¿Cuándo se ejecutan las directivas?
En Azure API Management, las directivas se ejecutan en cuatro momentos diferentes:
- Entrada: estas directivas se ejecutan cuando se recibe una solicitud de un cliente.
- Back-end: estas directivas se ejecutan antes de que se reenvíe una solicitud a una API administrada.
- Salida: estas directivas se ejecutan antes de enviar una respuesta a un cliente.
- En caso de error: estas directivas se ejecutan cuando se genera una excepción.
En la directiva XML, hay una etiqueta independiente para cada uno de estos entornos de ejecución:
<policies>
<inbound>
<base />
<check-header name="Authorization" failed-check-httpcode="401" failed-check-error-message="Not authorized" ignore-case="false">
</check-header>
</inbound>
<backend>
<base />
</backend>
<outbound>
<base />
<json-to-xml apply="always" consider-accept-header="false" parse-date="false" />
</outbound>
<on-error>
<base />
</on-error>
</policies>
En este ejemplo, puede ver que la directiva comprueba si las solicitudes de entrada tienen un encabezado denominado Autorización. Si ese encabezado no está presente, la directiva muestra un mensaje de error.
Esta directiva también convierte las respuestas de salida en formato JSON a XML.
Ámbitos de la directiva
El ámbito de una directiva determina en qué medida se aplicará. Estos son los ámbitos de directiva entre los que puede elegir:
- Global
- Producto
- API
- Operación
Global
Las directivas aplicadas en el ámbito global afectan a todas las API dentro de la instancia de API Management.
Para usar el ámbito global, en el panel de servicio API Management, en el panel de menús izquierdo, en API Management, seleccione API y, a continuación, Todas las API en el panel de menú central. Seleccione + Agregar directiva en la sección Procesamiento de entrada o Procesamiento de salida para ver las directivas que puede agregar en ese ámbito.
De las opciones disponibles, seleccione una para iniciar un asistente que le guiará para agregar la directiva con la sintaxis correcta:
Puede abrir el editor XML directamente seleccionando el símbolo de la etiqueta </> en las secciones Procesamiento de entrada, Procesamiento de salida o Back-end. El editor de directivas que aparece incluye contenido XML predeterminado. A la derecha, seleccione Mostrar fragmentos de código para buscar accesos directos que agreguen directivas:
Producto
En API Management, puede ensamblar una o varias API en un solo producto y, a continuación, administrar el acceso a ese producto como una sola entidad. Las directivas aplicadas en el ámbito del producto afectan a todas las API de ese producto. Las API de otros productos no se ven afectadas. Al administrar un producto en Azure Portal, seleccione el panel Directivas para agregar directivas a través de un asistente guiado o mediante el editor de directivas XML:
API
Las directivas aplicadas en el ámbito de la API afectan solo a una única API. Para establecer una directiva en el ámbito de la API, en la página principal de API Management, seleccione API y, luego, la API que quiera administrar. Por último, en la pestaña Diseño, seleccione Todas las operaciones. Puede establecer directivas de entrada, salida o back-end que se aplican a todas las operaciones de esa API:
Operación
Las directivas aplicadas en el ámbito de la operación afectan a una única operación dentro de la API. En el ejemplo siguiente, el administrador ha seleccionado la operación GetSpeaker dentro de la API Demo Conference API y puede establecer directivas de entrada, de salida o de back-end que se aplican solo a esa operación:
¿En qué orden se aplican las directivas?
Puede usar la etiqueta <base /> para determinar cuándo se aplican las directivas de un ámbito superior. Por ejemplo, en esta directiva, aplicada en el ámbito de la API:
<policies>
<inbound>
<base />
<find-and-replace from="game" to="board game" />
</inbound>
</policies>
Dado que la etiqueta <base> aparece encima de la etiqueta <find-and-replace>, Azure API Management aplica en primer lugar las directivas de los ámbitos global y del producto y, a continuación, ejecuta la directiva de buscar y reemplazar.
Directivas de uso frecuente
Vamos a examinar algunas acciones que puede hacer con las directivas en API Management. Presentaremos algunas de las directivas más usadas, y puede visitar la documentación de API Management para obtener una lista completa y ejemplos.
Directivas de restricción del acceso
Hay varias directivas que puede usar para impedir o limitar el acceso a una API o a sus operaciones. Por ejemplo:
Use la directiva Comprobar encabezado HTTP para comprobar si una propiedad está presente en un encabezado HTTP. Si la propiedad no se encuentra, Azure API Management anula la solicitud.
La directiva Limitar la frecuencia de llamadas por suscripción restringe el número de llamadas que pueden proceder de una sola suscripción de API. Esta directiva puede garantizar que los usuarios de una suscripción no usen todo el ancho de banda.
Si quiere restringir el número de llamadas que llegan con una misma clave de acceso, utilice la directiva Limitar la frecuencia de llamadas por clave.
Para permitir o denegar las llamadas desde direcciones IP o intervalos de direcciones IP específicos, use la directiva Restringir las direcciones IP de autor de llamada. Esta forma de restringir el acceso se comporta como las restricciones de direcciones IP que se pueden aplicar en un firewall.
Directivas de autenticación
Hay varias directivas que le permiten controlar la autenticación. Por ejemplo:
Use la directiva Autenticar con básico para habilitar la autenticación en texto sin formato. Esta forma de autenticación se admite ampliamente, pero recuerde que debe protegerla con el cifrado SSL. De lo contrario, un ataque malintencionado podría interceptar las credenciales al cruzar la red.
Use la directiva Autenticar con certificado de cliente para permitir que los clientes se autentiquen proporcionando un certificado de cliente.
Directivas entre dominios
Las solicitudes entre dominios se consideran una amenaza de seguridad y los exploradores y las API las rechazan. Aun así, pueden resultar útiles para determinadas operaciones, y las directivas de API Management le permiten habilitarlas de manera segura.
Use la directiva Permitir llamadas entre dominios para permitir las llamadas de Adobe Flash y Silverlight. Si la API o las aplicaciones cliente se basan en el uso compartido de recursos entre orígenes (CORS), use la directiva CORS para permitirlas.
Algún código de AJAX, que se ejecuta en el explorador, usa JSON con relleno para realizar llamadas entre dominios de forma segura. Utilice la directiva JSONP para permitir que los clientes usen esta técnica.
Directivas de transformación
A menudo resulta útil cambiar el formato o el contenido de una respuesta de una API administrada. Puede hacerlo con varias directivas. Por ejemplo:
Para convertir entre JSON y XML, utilice las directivas Convertir JSON a XML y Convertir XML a JSON. A menudo, estas directivas ayudan a mantener la coherencia entre varias API de un producto. También puede eliminar la necesidad de volver a codificar una API cuando una aplicación espera una respuesta en un formato específico.
A veces es posible que quiera mantener una respuesta en XML, pero modificar su esquema. En tales casos, utilice la directiva Transformar XML para aplicar una plantilla XSLT.
Use Buscar y reemplazar cadena en el cuerpo para ejecutar una sustitución de cadenas. Por ejemplo, si ha cambiado un nombre de marca, podría usar esta directiva para asegurarse de que el cambio se refleja en todas las respuestas, incluso en el caso de que los datos subyacentes todavía incluyan referencias al nombre anterior.
La directiva Enmascarar URL en el contenido puede volver a escribir los vínculos en el cuerpo de la respuesta para que apunten a otra ubicación. Esta directiva resulta útil cuando se ha movido una API web o un sitio web.
Utilice la directiva Establecer cuerpo para establecer el texto del mensaje para las solicitudes entrantes y salientes.
Si quiere modificar una solicitud HTTP de entrada o una respuesta de salida, puede usar varias directivas diferentes. Para agregar elementos a un encabezado de solicitud o respuesta existente, use la directiva Establecer encabezado HTTP. Si tiene que modificar las cadenas de consulta, que aparecen después del signo de interrogación en la dirección URL, use la directiva Establecer parámetro de cadena de consulta. Si una dirección URL pública, que un usuario ha solicitado, debe asignarse a un destino interno diferente, la directiva Reescribir URL puede realizar la conversión tanto de entrada como de salida.
Directivas avanzadas
Estas directivas pueden emplearse en escenarios en los que quiera un comportamiento no estándar.
Por ejemplo, si quiere aplicar una directiva solo cuando la respuesta supere una prueba concreta, use la directiva Flujo de control.
Use la directiva Reenviar solicitud para reenviar una solicitud a un servidor back-end.
Para controlar lo que sucede cuando se produce un error en una acción, use la directiva Reintentar. Las instrucciones de directiva incluidas en Reintentar se ejecutarán de forma repetida hasta que se cumpla una condición. La ejecución se repetirá en los intervalos de tiempo especificados hasta que se alcance el valor de recuento de reintentos.
La directiva Enviar solicitud unidireccional puede enviar una solicitud a una dirección URL sin tener que esperar una respuesta.
Si quiere almacenar un valor para su uso en un cálculo o una prueba posteriores, use la directiva Establecer variable para conservar un valor de una variable con nombre.