API web de Power Automate

Los flujos se almacenan ahora en Dataverse y usan la API web enriquecida.

Este contenido cubre la administración de flujos incluidos en la pestaña Soluciones de Power Automate. Actualmente, estas API no admiten los flujos incluidos en Mis flujos.

Redactar solicitudes HTTP

Para empezar a crear las solicitudes, primero deberá crear la dirección URL. El formato de la dirección URL base de la API web de Power Automate es: https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/. Los dos parámetros son:

  • Organization ID es un nombre único del entorno donde se almacenan los flujos.

  • Regional Subdomain depende de la ubicación de su entorno.

Para obtener estos dos parámetros:

  1. Vaya al Centro de administración de Power Platform.

  2. Seleccione el entorno que utiliza para crear sus flujos.

    Captura de pantalla del entorno para sus flujos.

  3. Copie el identificador de la organización y el subdominio de la región de la URL del entorno.

    Captura de pantalla del id. de la organización y la región.

    La lista de instancias disponibles también se puede obtener mediante programación a través del método Obtener instancias de la API de administración en línea.

    Cada solicitud realizada a la API web debe tener los encabezados Aceptar y Tipo de contenido establecido en application/json.

  4. Por último, rellene el encabezado Autorización con un token de portador de Azure AD.

    Para obtener información sobre cómo obtener un token de portador de Azure AD para Dataverse, vaya a Usar autenticación OAuth con Microsoft Dataverse.

El siguiente es un ejemplo de una solicitud:.

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...

La respuesta contiene la lista de flujos desde dentro de ese entorno:

{
	"@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#workflows",
	"value": [{
		"@odata.etag": "W/\"12116760\"",
		"category": 5,
		"statecode": 0,
		"workflowidunique": "00000000-0000-0000-0000-000000000001",
		"workflowid" : "00000000-0000-0000-0000-000000000002",
		"createdon": "2018-11-15T19:45:51Z",
		"_ownerid_value": "00000000-0000-0000-0000-000000000003",
		"modifiedon": "2018-11-15T19:45:51Z",
		"ismanaged": false,
		"name": "Sample flow",
		"_modifiedby_value": "00000000-0000-0000-0000-000000000003",
		"_createdby_value": "00000000-0000-0000-0000-000000000003",
		"type": 1,
		"description": "This flow updates some data in Dataverse.",
		"clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
	}]
}

Enumerar flujos

Tal y como se ha señalado antes, se puede obtener la lista de flujos de trabajo con una llamada a GET en workflows. Cada flujo de trabajo tiene numerosas propiedades, pero las más relevantes son las enumeradas en la siguiente tabla.

Nombre de la propiedad Description
category Categoría del flujo. Aquí están las diferentes categorías.
0 - Flujos de trabajo clásicos de Dataverse.
1 - Diálogos clásicos de Dataverse.
2 - Reglas de negocio.
3 - Acciones clásicas de Dataverse.
4 - Flujos de proceso de negocio.
5 - Flujos automatizados, instantáneos o programados.
6 - Desktop flows.
statecode Estado del flujo. El estado puede ser 0 (desactivado) o 1 (activado).
workflowidunique Identificador único de esta instalación del flujo.
workflowid Identificador único de un flujo de nube en todas las importaciones.
createdon Fecha en que se creó el flujo.
_ownerid_value Identificador único del usuario o el equipo que posee el flujo. Este es un id. de la tabla systemusers en Dataverse.
modifiedon Última vez que se actualizó el flujo.
ismanaged Indica si el flujo se ha instalado a través de una solución administrada.
name Nombre para mostrar que se le ha dado al flujo.
_modifiedby_value Último usuario que actualizó el flujo. Este es un id. de la tabla systemusers en Dataverse.
_createdby_value Usuario que creó el flujo. Este es un id. de la tabla systemusers en Dataverse.
type Indica si el flujo es un flujo en ejecución o una plantilla que se puede usar para crear más flujos. 1 (flujo), 2 (activación) o 3 (plantilla).
Descripción Descripción del flujo proporcionada por el usuario.
clientdata Un JSON con codificación de cadena de la definición de flujo y sus connectionReferences.

Para obtener más información sobre propiedades, campos y su uso, vaya a Referencia de tabla/entidad de procesos (flujo de trabajo).

También puede solicitar propiedades concretas, filtrar la lista de flujos y realizar otras muchas cosas, como se describe en Solicitar datos mediante la API web. Por ejemplo, esta consulta devuelve únicamente los flujos automatizados, instantáneos o programados que están activados actualmente:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows?$filter=category eq 5 and statecode eq 1
Accept: application/json
Authorization: Bearer ey...

Crear de un flujo de nube

Para crear un flujo de nube, llame a POST en la colección workflows. Las propiedades necesarias en los flujos automatizados, instantáneos o programados son category, name, type, primaryentity y clientdata. Use none como primaryentity en estos tipos de flujos.

También puede especificar las propiedades description y statecode.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
		"category": 5,
		"statecode": 0,
		"name": "Sample flow name",
		"type": 1,
		"description": "This flow reads some data from Dataverse.",
		"primaryentity":"none",
		"clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"connectionName\":\"shared-commondataser-00000000-0000-0000-0000-000000000004\",\"source\":\"Invoker\",\"id\":\"/providers/Microsoft.Power Apps/apis/shared_commondataservice\"}},\"definition\":{\"$schema\": \"https:\/\/schema.management.azure.com\/providers\/Microsoft.Logic\/schemas\/2016-06-01\/workflowdefinition.json#\",\"contentVersion\": \"1.0.0.0\",\"parameters\": {\"$connections\": {\"defaultValue\": {},\"type\": \"Object\"},\"$authentication\": {\"defaultValue\": {},\"type\": \"SecureObject\"}},\"triggers\": {\"Recurrence\": {\"recurrence\": {\"frequency\": \"Minute\",\"interval\": 1},\"type\": \"Recurrence\"}},\"actions\": {\"List_records\": {\"runAfter\": {},\"metadata\": {\"flowSystemMetadata\": {\"swaggerOperationId\": \"GetItems_V2\"}},\"type\": \"ApiConnection\",\"inputs\": {\"host\": {\"api\": {\"runtimeUrl\": \"https:\/\/firstrelease-001.azure-apim.net\/apim\/commondataservice\"},\"connection\": {\"name\": \"@parameters('$connections')['shared_commondataservice']['connectionId']\"}},\"method\": \"get\",\"path\": \"\/v2\/datasets\/@{encodeURIComponent(encodeURIComponent('default.cds'))}\/tables\/@{encodeURIComponent(encodeURIComponent('accounts'))}\/items\",\"queries\": {\"$top\": 1},\"authentication\": \"@parameters('$authentication')\"}}},\"outputs\": {}}},\"schemaVersion\":\"1.0.0.0\"}"
}

La sección más importante es clientdata, que contiene el parámetro connectionReferences que el flujo usa y la propiedad definition del flujo. El parámetro connectionReferences son las asignaciones a cada conexión que el flujo utiliza.

Hay tres propiedades:

Nombre de la propiedad Descripción
connectionName Identifica la conexión. Para ver la propiedad connectionName, vaya a la página Conexiones y, después, cópiela desde la dirección URL de la conexión.
source Embedded o Invoker. Invoker solo es válido en los flujos instantáneos (aquellos en los que un usuario selecciona un botón para ejecutar el flujo) e indica que el usuario final proporcionará la conexión. En este caso, la propiedad connectionName solo se utiliza en el momento del diseño. Si la conexión es Embedded, significa que siempre se usa la propiedad connectionName que se especifique.
id Identificador del conector. El identificador siempre comienza por /providers/Microsoft.PowerApps/apis/ y le sigue el nombre del conector, que puede copiar desde la dirección URL de la conexión, o bien seleccionando el conector en la página Conectores.

Una vez ejecutada la solicitud POST, recibirá el encabezado OData-EntityId, que contendrá la propiedad workflowid del nuevo flujo.

Actualizar un flujo de nube

Puede llamar a PATCH en el flujo de trabajo para actualizar, activar o desactivar un flujo de nube. Use la propiedad workflowid para realizar estas llamadas. Por ejemplo, puede actualizar la descripción y el propietario del flujo con la siguiente llamada:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"description" : "This flow will ensure consistency across systems.",
	"ownerid@odata.bind": "systemusers(00000000-0000-0000-0000-000000000005)"
}

Nota

La sintaxis para cambiar el propietario emplea el formato odata.bind. Esto significa que, en lugar de aplicar revisiones al campo ownerid_value directamente, se anexa @odata.bind al nombre de propiedad y, a continuación, se encapsula el identificador con systemusers().

En otro ejemplo, puede activar un flujo de nube con esta llamada:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"statecode" : 1
}

Eliminar un flujo de nube

Elimine un flujo con una sencilla llamada a DELETE:

DELETE https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...

Nota

No se puede eliminar un flujo de nube que está activado. Primero debe apagar el flujo o verá este error: Cannot delete an active workflow definition. Para obtener más información, vaya a Actualizar un flujo de nube en este artículo.

Obtener todos los usuarios con los que se comparte un flujo de nube

Para obtener una lista de los usuarios con acceso al flujo, se usa una característica en Dataverse. Esta característica toma un solo parámetro Target:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/RetrieveSharedPrincipalsAndAccess(Target=@tid)?@tid={'@odata.id':'workflows(00000000-0000-0000-0000-000000000002)'}
Accept: application/json
Authorization: Bearer ey...

El parámetro Target es una cadena similar a JSON con una única propiedad denominada @odata.id. Reemplace el identificador del flujo de trabajo en el ejemplo anterior. Se devuelve lo siguiente:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveSharedPrincipalsAndAccessResponse",
    "PrincipalAccesses": [
        {
            "AccessMask": "ReadAccess",
            "Principal": {
                "@odata.type": "#Microsoft.Dynamics.CRM.systemuser",
                "ownerid": "00000000-0000-0000-0000-000000000005"
            }
        }
    ]
}

Compartir o dejar de compartir un flujo de nube

Puede compartir un flujo de nube mediante la acción GrantAccess.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/GrantAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"Target" : {
		"@odata.type": "Microsoft.Dynamics.CRM.workflow",
		"workflowid" : "00000000-0000-0000-0000-000000000002"
	},
	"PrincipalAccess": {
		"Principal": {
			"@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
			"ownerid" : "00000000-0000-0000-0000-000000000005"
		},
		"AccessMask": "ReadAccess"
	}
}

El parámetro AccessMask es un campo con los siguientes valores relativos a los distintos niveles de permiso:

Nombre Descripción
None Sin acceso.
ReadAccess Derecho a leer el flujo.
WriteAccess Derecho a actualizar el flujo.
DeleteAccess Derecho a eliminar el flujo.
ShareAccess Derecho a compartir el flujo.
AssignAccess Derecho para cambiar el propietario del flujo.

Puede combinar permisos con una coma. Por ejemplo, para proporcionar la capacidad tanto de leer como de actualizar un flujo de nube, se pasaría ReadAccess,WriteAccess.

También puede dejar de compartir un flujo de nube con la acción RevokeAccess. Mostramos ahora un ejemplo:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/RevokeAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"Target" : {
		"@odata.type": "Microsoft.Dynamics.CRM.workflow",
		"workflowid" : "00000000-0000-0000-0000-000000000002"
	},
	"Revokee": {
		"@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
		"ownerid" : "00000000-0000-0000-0000-000000000005"
	}
}

RevokeAccess quita todos los permisos concedidos en AccessMask.

Exportar flujos

Use la acción ExportSolution para exportar flujos a un archivo .zip. Primero, agregue los flujos que quiera a una solución.

Una vez que los flujos están en una solución, llame a la siguiente acción:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ExportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"SolutionName" : "Awesome solution 1",
	"Managed": false
}

ExportSolution devuelve una cadena con codificación en Base64 en la propiedad ExportSoutionFile.

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportSolutionResponse",
    "ExportSolutionFile": "UEsDBBQAAgAI..."
}

Puede guardar este archivo en el control de código fuente o usar el sistema de administración o distribución de versiones que quiera.

Importar flujos

Llame a la acción ImportSolution para importar una solución.

Nombre de la propiedad Descripción
OverwriteUnmanagedCustomizations Si no hay instancias existentes de estos flujos en Dataverse, esta marca se debe establecer en true para importarlos. En caso contrario, no se sobrescribirán.
PublishWorkflows Indica si los flujos de trabajo clásicos de Dataverse se activarán con la importación. Esta configuración no es válida con ningún otro tipo de flujo.
ImportJobId Proporciona un GUID nuevo y único para realizar un seguimiento del trabajo de importación.
CustomizationFile Archivo ZIP con codificación en Base64 que contiene la solución.
POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ImportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
	"OverwriteUnmanagedCustomizations": false,
	"PublishWorkflows" : true,
	"ImportJobId" : "00000000-0000-0000-0000-000000000006",
    "CustomizationFile" : "UEsDBBQAAgAI..."
}

Como la importación es una operación de larga ejecución, la respuesta a la acción ImportSolution será 204 No content. Para llevar un seguimiento del progreso, llame a GET en el objeto importjobs, lo que le proporcionará el ImportJobId que incluyó en la acción ImportSolution original.

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/importjobs(00000000-0000-0000-0000-000000000006)
Accept: application/json
Authorization: Bearer ey...

Esta llamada devuelve el estado de la operación de importación, incluidos progress (porcentaje de finalización), startedon y completedon (si la importación ha finalizado).

Una vez que la importación se haya completado correctamente, deberá configurar las conexiones para el flujo. La razón es que connectionNames probablemente será diferente en el entorno de destino (si las conexiones existen). Si está configurando nuevas conexiones en el entorno de destino, el propietario de los flujos deberá crearlas en el diseñador de Power Automate. Si las conexiones ya están configuradas en el nuevo entorno, puede usar una acción PATCH en el clientData del flujo con los nombres de las conexiones.

Consulte también