API web de Power Automate

Artículo
02/01/2023
Tiempo de lectura: 8 minutos

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:

Vaya al Centro de administración de Power Platform.
Seleccione el entorno que utiliza para crear sus flujos.
Copie el identificador de la organización y el subdominio de la región de la URL del entorno.

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.
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"
            }
        }
    ]
}

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.

API web de Power Automate

Redactar solicitudes HTTP

Enumerar flujos

Crear de un flujo de nube

Actualizar un flujo de nube

Eliminar un flujo de nube

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

Exportar flujos

Importar flujos

Consulte también

Recursos adicionales

Recursos adicionales

API web de Power Automate

Redactar solicitudes HTTP

Enumerar flujos

Crear de un flujo de nube

Actualizar un flujo de nube

Eliminar un flujo de nube

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

Compartir o dejar de compartir un flujo de nube

Exportar flujos

Importar flujos

Consulte también

Recursos adicionales

Recursos adicionales