API REST de movimiento de base de datos de LCS

Aquí puedes leer mi guía completa sobre Dynamics 365 for Finance and Operations y Azure DevOps.

Desde el pasado octubre hemos podido probar la preview de la Database Movement API que nos permite listar y descargar copias de las DBs que tenemos en LCS y lanzar refrescos de datos usando una API REST.

Si queréis uniros a la preview primero necesitáis ser parte del Insider Program donde podéis uniros al «Dynamics 365 for Finance and Operations Insider Community«. Una vez invitados a la organización de Yammer podéis pedir acceso al grupo «Self-Service Database Movement / DataALM» donde recibiréis toda la info necesaria para uniros a la preview y activar la funcionalidad en LCS.

La API

De momento sólo podemos hacer estas operationes a través de la API REST:

• Listar las copias de la DB de un proyecto de LCS.
• Lanzar un refresco de datos entre dos entornos (sólo Prod y Sandbox, igual que desde LCS).
• Obtener el estado de una operacion.

¡Se espera añadir más operaciones en 2020! Ah, y existe un límite de 3 peticiones de refresco por objetivo cada 24 horas, si sobrepasamos este límite obtendremos la siguiente respuesta:

{
"IsSuccess": false,
"OperationActivityId": "55eb4327-9346-4c7b-82bd-fe8ef15112c6",
"ErrorMessage": "Maximum allowed API operations are 3 from 2019-09-30T04:01:01.9999999",
"VersionEOL": "9999-12-31T23:59:59.9999999"
}

Vamos a ver como podemos hacer las llamadas usando Postman.

Autenticación

El primer paso que tenemos que realizar es registrar una nueva App en AAD. Simplemente seguid la documentación o leed este post y guardad el Application Id y el secret para más tarde.

Ahora necesitamos obtener un token usando la identity platform de Microsoft haciendo una llamada GET a la url https://login.microsoftonline.com/common/oauth2/token. He probado a usar el token generado con el tenant de mi organización y también funciona, podéis probar a usar ambos.

La petición para obtener el token debería ser así:

Podéis ver que el parámetro grant_type es de tipo password en vez de client_credentials como cuando pedimos un token para llamar a la API de OData de Dynamics 365. Usaremos el appId y secret de la app de AAD que hemos creado al principio y la url https://lcsapi.lcs.dynamics.com en resource.

Necesitamos especificar un usuario y contraseña que tienen que existir en el proyecto de LCS que vayamos a usar y tener la clave de preview activada.

Y si todo va bien obtendremos el token:

Con el valor de access_token podremos hacer las llamadas a la API de LCS.

Peticiones

Listar backups

Una vez tenemos el token podemos hacer las peticiones. Por ejemplo, para listar las DBs llamaremos al endpoint https://lcsapi.lcs.dynamics.com/databasemovement/v1/databases/project/LCS_PROJECT_ID. La llamada de Postman será así

:

En el parámetro Authorization pondremos Bearer seguido del token.

Y obtendremos un JSON con la lista de las copias de la DB que haya en la Asset Library de LCS:

{
    "DatabaseAssets": [
        {
            "Id": "00c82737-5734-4de4-81cf-163ca7c76119",
            "ProjectId": LCS_PROJECT_ID
            "OrganizationId": ORG_ID,
            "Name": "DBbackup",
            "FileName": "DBbackup.bacpac",
            "FileDescription": null,
            "FileLocation": "https://bacpackurlatablob.com",
            "ModifiedDateTime": "2019-10-23T11:55:43.033",
            "CreatedDateTime": "2019-10-23T11:55:43.033",
            "CreatedByName": null,
            "ModifiedByName": null
        }
    ],
    "IsSuccess": true,
    "OperationActivityId": "3c66eab9-b2e5-468e-a72f-ac980d859c05",
    "ErrorMessage": null,
    "VersionEOL": "9999-12-31T23:59:59.9999999"
}

En la respuesta tendremos un link válido para descargar el backup y otra información, como la propiedad IsSuccess que nos permite comprobar si la operación ha ido bien.

Refresco de datos

Para lanzar un refresco de datos desde la API necesitamos hacer una llamada POST al la url https://lcsapi.lcs.dynamics.com/databasemovement/v1/databases/project/source/{sourceEnvironmentId}/target/{targetEnvironmentId}. Usando el valor del campo environment Id del entorno en LCS.

La llamada tendrá los mismos header que el de listar y no necesitamos pasarle ningún body. Al ejecutar la petición recibiremos esta respuesta:

{
    "IsSuccess": true,
    "OperationActivityId": "55eb4327-9346-4c7b-82bd-fe8ef15112c6",
    "ErrorMessage": null,
    "VersionEOL": "9999-12-31T23:59:59.9999999"
}

Como podemos ver la propiedad IsSuccess nos dice si la operación ha ido bien o no.

Obtener estado de operación

Y el último servicio de la API que, de momento, tenemos disponible nos ayuda a ver qué estado tiene una operación en curso. Llamando a la siguiente url: https://lcsapi.lcs.dynamics.com/databasemovement/v1/fetchstatus/project/{projectId}/environment/{environmentId}/operationactivity/{operationactivityId}.

El valor de operationactivityId es el que obtenemos en la respuesta de la llamada de refresco de la DB. La respuesta a esta parte de la API será:

{
    "IsSuccess": true,
    "OperationActivityId": "6a90b45f-1764-4077-b924-3f4671540237",
    "ErrorMessage": null,
    "VersionEOL": "9999-12-31T23:59:59.9999999",
    "ProjectId": "12345",
    "EnvironmentId": "5362377c-bc37-4f92-b30e-fe0c1e664cc0",
    "ActivityId": "55eb4327-9346-4c7b-82bd-fe8ef15112c6",
    "CompletionDate": null,
    "OperationStatus": "InProgress"
}

¿Para qué podemos usar esto?

Depende de ti y de tus necesidades, pero por ejemplo podríamos crear una Power App en la que seleccionaramos el campo origen y destino y lanzaramos un refresco de datos usando un Flow. O llamar a la API para refrescar un entorno de UAT desde prod en nuestro release diario/semanal para tener datos frescos de un día para otro.

En los primeros días de Dynamics 365 FnO, antes de tener las herramientas de self-service para datos en LCS, creé un par de scripts en PowerShell que se ejecutaban cada noche usando el programador de tareas de Windows. El primero se ejecutaba en un entorno Tier2 de UAT en el que creaba un bacpac de la DB y lo subía a una cuenta de almacenamiento de Azure. El segundo se descargaba el bacpac en una VM de desarrollo y restauraba el bacpac para que pudieramos tener el BAK listo por la mañana. La API hubiera sido bastante útil porque esos scripts que hice eran los primeros PowerShell que tocaba y fueron muy feos (pero funcionaban perfectos!).

Es genial ver como el producto está evolucionando y cada día nos ofrece nuevas herramientas para solucionar nuestras necesidades y problemas!