Azure API Management y Dynamics 365 F&O

Azure API Management es una plataforma de gestión híbrida y multi-nube para APIs en todos los entornos. Esto significa que, después de desplegar una cuenta de APIM, puedes crear una API que puede servir servicios de un sistema o de varios.

¿Por qué iba a poner Azure API Management delante de los servicios/OData de D365?

Esa es una pregunta legítima y excelente. Ya tenemos OData y servicios web personalizados, y se puede acceder a ambos fácilmente.

Bueno, por supuesto que OData y WS están perfectamente bien, pero usando Azure API Management podemos añadir una capa extra de varias cosas:

Añadir seguridad extra y desacoplar tu API APIM de la del backend. Olvídate de pasar el Azure AD App ID y el secreto a un proveedor externo, puedes gestionar eso dentro de APIM y darle una API Key a quien vaya a consumir tu API.
Añade limites en las llamadas, o cuotas de uso.
Validar el cuerpo de la solicitud o de la respuesta.
Validar parámetros.
Políticas y respuestas personalizadas.

Y por supuesto, puedes tener varios backends en una sola API. Esto significa que podría tener los puntos finales de CRM WebAPI y ERP OData en la misma URL. Y también desplegar una puerta de enlace autoalojada para conectarse para soportar entornos híbridos y multi-nube.

Y muchas más funcionalidades, sólo he arañado la superficie de Azure API Management.

Úsalo con Dynamics 365 F&O

Crea una cuenta de API Management

Ve a tu cuenta de Azure y busca «API Management services» en la barra de búsqueda superior. Selecciona crear y rellena todos los campos.

En cuanto al precio, yo me decantaría por el tier de «Consumption» que nos da un millón de llamadas por suscripción, y a partir de ahí son como 3 céntimos/10K de llamadas. Ten en cuenta que si deseas tener un portal para desarrolladores con la documentación de tu API, tendrás que seleccionar cualquiera de los otros tiers.

Al crear la API Management, también puedes habilitar Application Insights y seleccionar varios protocolos. Todo esto puede habilitarse o cambiarse después de generar la APIM.

Dependiendo del tier que hayas seleccionado, el APIM tardará entre minutos y una hora en desplegarse. Si el nivel incluye un portal para desarrolladores, tardará más tiempo.

Crear una API

Ahora es el momento de crear una nueva API, así que dirígete al menú API de la izquierda. Tienes varias opciones:

Pantalla de nueva API en Azure APIM Management

Puedes importar definiciones OpenAPI, WSDL para servicios SOAP, etc. pero nosotros elegiremos HTTP. Dale un nombre e introduce la URL de tu entorno Dynamics 365, incluyendo el /data en este caso porque lo mostraré usando OData.

Si estuvieras creando un API Management para servicios web personalizados añadirías el sufijo /api/services.

El diseñador

No voy a entrar mucho en detalles, pero esto es algo que vale la pena explicar un poco. El diseñador nos da una pista de cómo funciona API Management:

Puedes ver un «Frontend» que es la URL de nuestra API de APIM y donde el usuario hará una solicitud.

A continuación, un cuadro de «Inbound processing» donde se pueden establecer algunas reglas antes de que se apliquen a la solicitud entrante y se pasen a la API «Backend».

Y finalmente una caja de «Outbound processing» donde la API de backend envía la petición y donde podemos cambiar algunas cosas antes de devolverlas al «Frontend» y mostrarlas al cliente que llamó a la API de APIM.

Crear una nueva operación

Ahora tenemos que crear una nueva operación, así que haz clic en «Add operation» y rellena los campos:

Haz clic en Guardar y vamos a probarla. Ve a la pestaña Test, copia la URL de la solicitud y pégala en otra pestaña y ¡deja que ocurra la magia!

¡Demasiado rápido! Ve a la pestaña de configuración, y verás una sección de Suscripción:

Y ahora puedes hacer dos cosas

Desmarcar la casilla de suscripción obligatoria.
Añadir un parámetro de cabecera a la URL con el valor de tu clave de suscripción, que se encuentra en el menú «Suscripciones» de la izquierda. Eso dejaría nuestra URL como https://apimd365.azure-api.net/CustomerGroups?subscription-key=YOUR_SUBSCRIPTION_KEY.

Pero espera, falta una cosa más, y te estarás preguntando cómo podría acceder a un endpoint OData sin obtener el bearer token primero. Tienes toda la razón.

Obtener el token

Cada vez que llamamos a un endpoint OData de Dynamics 365 o a un servicio web, necesitamos autenticarnos con el bearer token. Esto lo solucionaremos gracias a las políticas. Volvamos a la pestaña de diseño y hagamos clic en el símbolo de código en la sección «Inbound processing» mientras que «All operations» está seleccionado:

Aparecerá un editor XML, y aquí hay que añadir el Azure App ID y el secreto para obtener el token y autenticar:

<!--
    IMPORTANT:
    - Policy elements can appear only within the <inbound>, <outbound>, <backend> section elements.
    - To apply a policy to the incoming request (before it is forwarded to the backend service), place a corresponding policy element within the <inbound> section element.
    - To apply a policy to the outgoing response (before it is sent back to the caller), place a corresponding policy element within the <outbound> section element.
    - To add a policy, place the cursor at the desired insertion point and select a policy from the sidebar.
    - To remove a policy, delete the corresponding policy statement from the policy document.
    - Position the <base> element within a section element to inherit all policies from the corresponding section element in the enclosing scope.
    - Remove the <base> element to prevent inheriting policies from the corresponding section element in the enclosing scope.
    - Policies are applied in the order of their appearance, from the top down.
    - Comments within policy elements are not supported and may disappear. Place your comments between policy elements or at a higher level scope.
-->
<policies>
    <inbound>
        <base />
        <send-request mode="new" response-variable-name="bearerToken" timeout="20" ignore-error="true">
            <set-url>https://login.microsoftonline.com/YOUR_TENANT/oauth2/token</set-url>
            <set-method>POST</set-method>
            <set-header name="Content-Type" exists-action="override">
                <value>application/x-www-form-urlencoded</value>
            </set-header>
            <set-body>@{ return "client_id=YOUR_CLIENT_ID&resource=ENVIRONMENT_URL&client_secret=YOUR_SECRET&grant_type=client_credentials"; }</set-body>
        </send-request>
        <set-header name="Authorization" exists-action="override">
            <value>@("Bearer " + (String)((IResponse)context.Variables["bearerToken"]).Body.As<JObject>()["access_token"])</value>
        </set-header>
        <retry condition="@(context.Response.StatusCode == 429)" count="3" interval="20" max-interval="60" delta="20" first-fast-retry="false" />
    </inbound>
    <backend>
        <base />
    </backend>
    <outbound>
        <base />        
    </outbound>
    <on-error>
        <base />
    </on-error>
</policies>

Puedes copiar esto y simplemente cambiar los valores YOUR_TENANT, YOUR_CLIENT_ID, ENVIRONMENT_URL y YOUR_SECRET. Y ahora podemos volver al navegador, pegar nuestra URL de APIM y la clave de suscripción si la has dejado activada y:

Customer groups in APIM — Grupos de clientes en APIM

¡Hemos recuperado con éxito los grupos de clientes a través de nuestro endpoint de API Management!

Más cosas buenas

Como todos sabéis, Dynamics 365 F&O tiene habilitado el throttling, y en caso de que haya una operación que falle debido a ello, obtendremos una respuesta 429. Podemos implementar políticas de reintento en nuestra API Management y quien esté usando nuestra API de APIM puede olvidarse de hacerlo.

Vuelve a la pestaña de Diseño y haz clic en cualquiera de los editores de código para las políticas, luego en el nodo de backend añade:

<retry
    condition="@(context.Response.StatusCode == 429)"
    count="10"
    interval="10"
    max-interval="100"
    delta="10"
    first-fast-retry="false">
</retry>

Esto hará hasta 10 reintentos. ¿No es genial?

Casos de uso

Yo no pondría una API Management delante de cada implementación de Dynamics 365, por supuesto, pero puede haber algunos escenarios en los que hay terceras partes accediendo a los datos, y quieres mantener algún control sobre quién está accediendo a qué.

Poder habilitar Application Insights también puede darnos más detalles sobre el uso y los errores que LCS también.

Y hay un montón de otras políticas que se pueden establecer a nivel de entrada, backend o salida. Como he dicho sólo he probado esto un poco, pero tiene un montón de usos potenciales para Dynamics, ¡ahora es tu turno de probarlo!