Compartilhar via

Trabalhar com fluxos da área de trabalho usando código

  • Artigo

Os desenvolvedores podem adicionar a funcionalidade fluxos da área de trabalho aos seus aplicativos, incluindo o desencadeamento e o cancelamento de fluxos da área de trabalho de forma programática. Esses recursos são oferecidos como parte da plataforma Microsoft Dataverse.

Pré-requisitos

  1. Conhecimento da API Web do Dataverse, da autenticação com o Dataverse e do uso do OAuth com o Dataverse.
  2. Conhecimento do ambiente do Dataverse e noções de organização, e como recuperar a URL da organização de forma manual ou programática.
  3. Conhecimento de noções de fluxos da área de trabalho e do que são conexões e como criá-las.

Important

Neste artigo, você deve substituir todos os colchetes [...] nas URLs e nos dados de entrada/saída por valores específicos para seu cenário.

Listar fluxos da área de trabalho disponíveis

Todos os scripts de fluxos da área de trabalho estão no Dataverse como parte da entidade do fluxo de trabalho.

Filtre a lista de fluxos de trabalho com base na categoria para identificar os fluxos da área de trabalho.

Solicitação para obter fluxos da área de trabalho

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

Resposta à solicitação para obter fluxos da área de trabalho

{
    "@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",
        }
    ]
}

Obter o esquema para fluxos da área de trabalho

Se precisar recuperar o esquema do fluxo para entradas e/ou saídas, você poderá usar o campo clientData para o fluxo de trabalho de destino.

Solicitar esquema para fluxos da área de trabalho

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

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

Resposta à solicitação para obter o esquema dos fluxos da área de trabalho

{
    "clientversion": "2.19.00170.22097",
    "properties": {
        "definition": {
            "dependencies": [],
            "isvalid": true,
            "name": "Desktop Flow 1",
            "package": "UEsDBBQAAAAIAIqZlF...",
            "$schema": "https://schema.management.azure.com/providers/Microsoft.Logic/schemas/2016-06-01/workflowdefinition.json#"
        },
        "inputs": {
            "schema": {
                "properties": {
                    "Input1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input 1",
                        "type": "string",
                        "value": "0"
                    },
                    "Input2": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Input2",
                        "type": "string",
                        "value": ""
                    }
                },
                "type": "object"
            }
        },
        "outputs": {
            "schema": {
                "properties": {
                    "Output1": {
                        "default": "",
                        "description": "",
                        "format": null,
                        "title": "Output",
                        "type": "string",
                        "value": null
                    }
                },
                "type": "object"
            }
        }
    },
    "schemaversion": "ROBIN_20211012",
    "targets": {
        "schema": {
            "properties": {},
            "type": "object"
        }
    }
}

Obter o status da execução de um fluxo da área de trabalho

O Dataverse armazena todas as execuções de fluxo da área de trabalho na entidade flowsession.

Solicitar o status da execução de um fluxo da área de trabalho

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

Resposta para o status da execução de um fluxo da área de trabalho

{
    "@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",
}

Obter saídas do fluxo da área de trabalho

Se o fluxo da área de trabalho tiver saídas, você poderá consultar o campo de saídas para recuperá-las.

Solicitação para saídas do fluxo da área de trabalho

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

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

Resposta à solicitação para saídas do fluxo da área de trabalho

{
    "Output1": "My output value"
}

Disparar uma execução de fluxo da área de trabalho

Usando o Dataverse, você pode adicionar a funcionalidade de desencadeamento de um fluxo da área de trabalho por meio de seu aplicativo. Para implementar essa funcionalidade, você precisa usar a ação RunDesktopFlow.

Para chamar essa ação, você precisará das seguintes informações:

  • A ID do fluxo da área de trabalho que você deseja executar. Você pode obter essa ID por meio da API como a seção Listar fluxos da área de trabalho disponíveis descreve anteriormente neste artigo.

    Tip

    Como alternativa, você pode recuperar a ID manualmente a partir da URL de detalhes do fluxo da área de trabalho no Power Automate. O formato da URL é: https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

    Para obter mais informações, consulte Gerenciar fluxos da área de trabalho.

  • O name da conexão do fluxo da área de trabalho (direcionado a um computador/grupo de computadores) a ser usado para executar seu fluxo. O nome pode ser recuperado a partir da URL da mesma página de conexão no Power Automate. O formato da URL é:
    https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

    Note

    Para obter mais informações, consulte Criar conexões de fluxos da área de trabalho.

    Tip

    Como alternativa, é possível usar o nome lógico de uma referência de conexão como entrada da conexão em vez do nome da conexão (exemplo de uso descrito abaixo). As referências de conexão são armazenadas na referência de conexão da tabela Dataverse e podem ser listadas programaticamente da mesma forma que os fluxos da área de trabalho detalhados na seção Listar fluxos de área de trabalho disponíveis.

    Para obter mais informações, consulte Usar uma referência de conexão em uma solução e tabela de referência de conexão/referência de entidade.

Solicitação para disparar um fluxo da área de trabalho

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\"}"
}

Solicitação para acionar um fluxo da área de trabalho com uma referência de conexão

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\"}"
}

Resposta à solicitação para desencadear um fluxo da área de trabalho

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

Warning

Ao usar a API, há algumas limitações a serem observadas:

  • Ao acionar uma execução de fluxo da área de trabalho usando a API, as entradas do script não podem ser visualizadas na página de detalhes da execução no portal do Power Automate.

  • O proprietário da sessão de fluxo que representa a execução é mapeado para o proprietário da entidade de fluxo de trabalho que representa o fluxo da área de trabalho. Haverá algumas limitações ao chamar a API em um fluxo de trabalho com um privilégio de "Usuário": cancelar a execução e consultar o status podem estar bloqueados devido a privilégios ausentes na sessão de fluxo.

  • Não há suporte para a representação do Dataverse.

Receber notificação sobre a conclusão do script

Um parâmetro opcional "callbackUrl" está disponível no corpo da ação RunDesktopFlow. Você pode usá-lo se quiser ser notificado sobre a conclusão do script. Uma solicitação POST será enviada para a URL fornecida quando o script for concluído.

Solicitação recebida pelo ponto de extremidade de retorno de chamada

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

Se nenhum parâmetro de URL de retorno de chamada for fornecido, o status da sessão de fluxo deverá ser pesquisado no Dataverse (consulte Obter o status de uma execução de fluxo da área de trabalho).

Note

  • Você ainda pode usar a sondagem de status como um mecanismo de fallback mesmo se fornecer um parâmetro de URL de retorno de chamada.
  • Sua operação de ponto de extremidade de retorno de chamada deve ser idempotente.
  • A solicitação POST será repetida três vezes com intervalo de um segundo se o ponto de extremidade responder com uma resposta de erro do servidor (código 500 e superior) ou uma resposta "Request Timeout" (código 408).

Requisitos para o parâmetro de URL de retorno de chamada

  • Seu servidor deve ter o TLS e conjuntos de criptografia atuais.

  • Apenas o protocolo HTTPS é permitido.

  • O acesso ao localhost (loopback) não é permitido.

  • Os endereços IP não podem ser usados. Você deve usar um endereço web nomeado que exija a resolução de nomes DNS.

  • O seu servidor deve permitir conexões dos valores do endereço IP dos serviços do Power Platform e do Dynamics 365 especificados na marca de serviço do AzureCloud.

    Tip

    Como a chamada de retorno não é autenticada, alguns cuidados devem ser tomados

    • Verifique a validade do ID da sessão de fluxo quando a notificação de retorno de chamada for recebida. O Dataverse é a fonte da verdade.
    • Implemente uma estratégia de limite de taxa no lado do servidor.
    • Tente limitar o compartilhamento de URL de retorno de chamada entre várias organizações.

Cancelar uma execução de fluxo da área de trabalho

Semelhante à funcionalidade de Gatilho, você também pode cancelar um fluxo da área de trabalho enfileirado/em execução. Para cancelar um fluxo da área de trabalho, use a ação CancelDesktopFlowRun.

Solicitação para cancelar uma execução do fluxo da área de trabalho

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

Resposta a uma solicitação para cancelar um fluxo da área de trabalho

HTTP/1.1 204 No Content

Erros

Quando ocorre um erro, a resposta tem um formato diferente que corresponde às mensagens de erro do Dataverse. O código de erro http e a mensagem devem fornecer informações suficientes para entender o problema.

HTTP/1.1 403 Forbidden

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

Note

Você pode nos falar mais sobre suas preferências de idioma para documentação? Faça uma pesquisa rápida. (Observe que esta pesquisa está em inglês)

A pesquisa levará cerca de sete minutos. Nenhum dado pessoal é coletado (política de privacidade).