Trabajar con flujos de escritorio mediante código

Los desarrolladores pueden agregar la funcionalidad de flujos de escritorio a sus aplicaciones, incluida la activación y cancelación programática de flujos de escritorio. La plataforma Microsoft Dataverse ofrece estas funcionalidades.

Requisitos previos

Conocimientos de la API web de Dataverse, la autenticación con Dataverse y el uso de OAuth con Dataverse.
Conocimientos sobre los conceptos del entorno y la organización de Dataverse y cómo recuperar la dirección URL de la organización manualmente o mediante programación.
Conocimientos de los conceptos de flujos de escritorio y de qué son las conexiones y cómo crearlas.

Importante

En este artículo, reemplace todos los corchetes [...] en direcciones URL y datos de entrada/salida por valores específicos de su escenario.

Lista de flujos de escritorio disponibles

Dataverse almacena todos los scripts de flujo de escritorio como parte de la entidad de flujo de trabajo.

Filtre la lista de flujos de trabajo según la categoría para identificar los flujos de escritorio.

Solicitud para obtener flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1

Nota

De forma predeterminada, esta solicitud devuelve solo los flujos de escritorio publicados. Para incluir flujos de escritorio no publicados (Borrador) en la respuesta, agregue el encabezado de solicitud MSCRM.IncludeUnpublished con el valor true.

Solicitud para obtener flujos de escritorio, incluidos flujos no publicados (borrador)

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
MSCRM.IncludeUnpublished: true

GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1

Respuesta a la solicitud para obtener flujos de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
    "value": [
        {
            "@odata.etag": "W1069462",
            "name": "Desktop flow 1",
            "workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
        },
        {
            "@odata.etag": "W1028555",
            "name": "Desktop flow 2",
            "workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
        }
    ]
}

Obtenga el esquema para los flujos de escritorio

Si necesita recuperar el esquema de flujo para entradas o salidas, use el clientData campo para el flujo de trabajo de destino.

Solicitar el esquema de entradas para los flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/inputs/$value HTTP/1.1

Respuesta a la solicitud para obtener el esquema de entradas de flujos de escritorio

{
    "schema": {
        "properties": {
            "inputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputText",
                "type": "string",
                "value": ""
            },
            "inputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "inputInteger",
                "type": "number",
                "value": "0"
            }
        },
        "type": "object"
    }
}

Solicitar el esquema de salidas para los flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/outputs/$value HTTP/1.1

Respuesta a la solicitud para obtener el esquema de salidas de flujos de escritorio

{
    "schema": {
        "properties": {
            "outputText": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputText",
                "type": "string",
                "value": null
            },
            "outputInteger": {
                "default": "",
                "description": "",
                "format": null,
                "title": "outputInteger",
                "type": "number",
                "value": null
            }
        },
        "type": "object"
    }
}

Obtener el estado de una ejecución de flujo de escritorio

Dataverse almacena todas las ejecuciones de flujos de escritorio en la entidad flowsession.

Solicitar el estado de una ejecución de flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1

Respuesta para el estado de una ejecución de flujo de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
    "@odata.etag": "W1276122",
    "statuscode": 8,
    "statecode": 0,
    "startedon": "2022-06-16T12:54:40Z",
    "completedon": "2022-06-16T12:57:46Z",
}

Obtener salidas de flujo de escritorio

Si el flujo de escritorio tiene salidas, consulte el outputs campo para recuperarlos.

Solicitar las salidas de flujos de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1

Respuesta a la solicitud de resultados de flujos de escritorio

{
    "Output1": "My output value"
}

Desencadenar una ejecución de flujo de escritorio

Al usar Dataverse, puede agregar la funcionalidad de activar un flujo de escritorio a través de su aplicación. Para implementar esta funcionalidad, use la acción RunDesktopFlow.

Para llamar a la acción, necesita la siguiente información.

El ID del flujo de escritorio que desea ejecutar. Obtenga este identificador a través de la API, como se indica anteriormente en este artículo en la sección Enumerar los flujos de escritorio disponibles.

Propina

Como alternativa, obtenga el identificador manualmente desde la URL de detalles del flujo de escritorio en Power Automate. El formato de URL es: https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Para obtener más información, consulte Administrar flujos de escritorio.
De name la conexión de flujo de escritorio (dirigida a un equipo o grupo de máquinas) que se va a usar para ejecutar el flujo. Obtenga el nombre de la URL de la misma página de conexión en Power Automate. El formato de URL es:
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Nota

Para más información, consulte Crear conexiones de flujo de escritorio.

Propina

Como alternativa, use el nombre lógico de una referencia de conexión como entrada de la conexión en lugar del nombre de conexión (ejemplo de uso descrito en la sección siguiente). Las referencias de conexión se almacenan en la tabla connectionreference dataverse y puede enumerarlas mediante programación de la misma manera que los flujos de escritorio detallados en la sección Lista de flujos de escritorio disponibles .

Para más información, consulte Usar una referencia de conexión en una solución y tabla de referencia de conexión/referencia de entidad.

Solicitud para activar un flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Name]",
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Solicitud para desencadenar un flujo de escritorio con una referencia de conexión

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1  
{
    "runMode": "attended",
    "runPriority": "normal",
    "connectionName": "[Connection Reference Logical Name]",
    "connectionType": 2,
    "timeout": 7200,
    "inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}

Respuesta a la solicitud para activar un flujo de escritorio

{
    "@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
    "flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Puede ver las entradas del script en la página de detalles de ejecución en el portal de Power Automate (en versión preliminar).

Advertencia

Al usar la API, tenga en cuenta estas limitaciones:

Desencadene una ejecución de flujo de escritorio mediante una cuenta con privilegios de usuario . Para cancelar la ejecución o consultar el estado, necesita privilegios de propietario .
No se admite la suplantación de Dataverse.
El tamaño del contenido del campo de entrada está limitado a 2 MB.

Recibir notificación sobre la finalización del script

Un parámetro opcional "callbackUrl" está disponible en el cuerpo de la acción RunDesktopFlow. Puede usarlo si desea que se le notifique la finalización de su script. Se enviará una solicitud POST a la URL proporcionada cuando se complete el script.

Solicitud recibida en el extremo de devolución de llamada

User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]

POST [yourCallbackURL]

{
    "statuscode": 4,
    "statecode": 0,
    "startedon": "2022-09-05T08:04:11Z",
    "completedon": "2022-09-05T08:04:41Z",
    "flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}

Si no se proporciona ningún parámetro de URL de retrollamada, el estado de la sesión del flujo debe consultarse periódicamente en Dataverse (consulte Obtener el estado de una ejecución de flujo de escritorio).

Nota

Todavía puede usar el sondeo de estado como un mecanismo alternativo incluso si proporciona un parámetro de URL de devolución de llamada.
La operación de su endpoint de callback debe ser idempotente.
La solicitud POST se volverá a intentar tres veces con un intervalo de un segundo si su punto de conexión responde con una respuesta de Error del servidor (código 500 y superior) o una respuesta de "Tiempo de espera de solicitud" (código 408).

Requisitos para el parámetro de dirección URL de devolución de llamada

El servidor debe tener la versión actual de TLS y conjuntos de cifrado.
Solo se permite el protocolo HTTPS.
El acceso a localhost (bucle invertido) no está permitido.
Las direcciones IP no se pueden usar. Debe usar una dirección web con nombre que requiera resolución de nombres DNS.
Su servidor debe permitir las conexiones procedentes de las direcciones IP de los servicios de Power Platform y Dynamics 365 especificados en la etiqueta de servicio AzureCloud.

Propina

Como la llamada de retorno no está autenticada, deben tomarse ciertas precauciones

Compruebe la validez del identificador de la sesión de flujo cuando se reciba la notificación de callback. Dataverse es la fuente de la verdad.
Implemente una estrategia de límite de tasa en su lado del servidor.
Intente limitar el uso compartido de URL de devolución de llamada entre varias organizaciones.

Cancelar una ejecución de flujo de escritorio

Al igual que la funcionalidad Trigger, también puede cancelar un flujo de escritorio en cola o en ejecución. Para cancelar un flujo de escritorio, utilice la acción CancelDesktopFlowRun.

Solicitud para cancelar una ejecución de flujo de escritorio

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json

POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1

Respuesta a una solicitud para cancelar un flujo de escritorio

HTTP/1.1 204 No Content

Errores

Cuando ocurre un error, la respuesta tiene un formato diferente que coincide con los mensajes de error de Dataverse. El código de error HTTP y el mensaje proporcionan suficiente información para comprender el problema.

HTTP/1.1 403 Forbidden

{
    "error": {
        "code": "0x80040220",
        "message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
    }
}

Limitaciones conocidas

Puede ejecutar hasta 70 ejecuciones de flujo de escritorio por minuto para cada conexión.

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-09-01