Trabalhar com fluxos de ambiente de trabalho que utilizam código
Os programadores podem adicionar a funcionalidade de fluxos de ambiente de trabalho às aplicações, incluindo o acionamento programático e o cancelamento de fluxos de ambiente de trabalho. Estas capacidades são oferecidas como parte da plataforma do Microsoft Dataverse.
Pré-requisitos
- Conhecimento da API Web do Dataverse, autenticação com o Dataverse e utilização do OAuth com o Dataverse.
- Conhecimento de noções do ambiente e organização do Dataverse e como obter o URL da organização manual ou programaticamente.
- Conhecimento de noções de fluxos de ambiente de trabalho e do que são ligações e como criá-las.
Important
Neste artigo, tem de substituir todos os parênteses retos [...] em URLs e dados de entrada/saída por valores específicos para o seu cenário.
Listar fluxos de ambiente de trabalho disponíveis
Todos os scripts de fluxos de ambiente 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 fluxos de ambiente de trabalho.
Pedir para obter fluxos de ambiente 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 ao pedido para obter fluxos de ambiente 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 de ambiente de trabalho
Se precisar de obter o esquema do fluxo para entradas e/ou saídas, pode utilizar o campo clientData para o fluxo de trabalho de destino.
Pedir esquema para fluxos de ambiente 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 ao pedido para obter o esquema de fluxos de ambiente 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 estado de uma execução de fluxo de ambiente de trabalho
O Dataverse armazena todas as execuções de fluxos de ambiente de trabalho na entidade flowsession.
Pedir o estado de uma execução de fluxo de ambiente 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 estado de uma execução de fluxo de ambiente 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 de fluxo de ambiente de trabalho
Se o fluxo de ambiente de trabalho tiver saídas, pode consultar o campo de saídas para os obter.
Pedir saídas de fluxo de ambiente 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 ao pedido para saídas de fluxo de ambiente de trabalho
{
"Output1": "My output value"
}
Acionar uma execução de fluxo de ambiente de trabalho
Ao utilizar o Dataverse, pode adicionar a funcionalidade de acionar um fluxo de ambiente de trabalho através da aplicação. Para implementar esta funcionalidade, tem de utilizar a ação RunDesktopFlow.
Para chamar a ação, terá de fornecer as seguintes informações.
O
IDdo fluxo de ambiente de trabalho que pretende executar. Pode obter este ID através da API, como a secção Listar fluxos de ambiente de trabalho disponíveis descreve anteriormente neste artigo.Tip
Em alternativa, poderá obter o ID manualmente a partir do URL dos detalhes do fluxo de ambiente de trabalho no Power Automate. O formato do URL é:
https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.Para obter mais informações, consulte Gerir fluxos de ambiente de trabalho.
O
nameda ligação ao fluxo de ambiente de trabalho (direcionado a um computador/grupo de computadores) a utilizar para executar o fluxo. O nome pode ser obtido a partir do URL da mesma página de ligação no Power Automate. O formato do URL é:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].Note
Para mais informações, consulte Criar ligações de fluxos de ambiente de trabalho.
Tip
Em alternativa, pode utilizar o nome lógico de uma referência de ligação como a entrada da ligação, em vez do nome da ligação (exemplo de utilização descrito abaixo). As referências de ligação são armazenadas na connectionreference da tabela do Dataverse e podem ser listadas programaticamente da mesma forma que os fluxos de ambiente de trabalho detalhados na secção Listar fluxos de ambiente de trabalho disponíveis.
Para obter mais informações, consulte Utilizar uma referência de ligação numa solução e tabela connectionreference/referência de entidade.
Pedir para acionar um fluxo de ambiente 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\"}"
}
Pedir para acionar um fluxo de ambiente de trabalho com uma referência de ligaçã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 ao pedido para acionar um fluxo de ambiente de trabalho
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
"flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}
Warning
Ao utilizar a API, há algumas limitações a ter em conta:
Quando aciona um fluxo de ambiente de trabalho executado utilizando a API, as entradas do script não são visualizáveis na página de detalhes da execução no portal do Power Automate.
O proprietário da sessão do fluxo que representa a execução é mapeado para o proprietário da entidade do fluxo de trabalho que representa o fluxo de ambiente de trabalho. Existem algumas limitações ao chamar a API num fluxo de trabalho com um privilégio "Utilizador": cancelar a execução e consultar o estado poderá estar bloqueado por privilégios em falta na sessão do fluxo.
A representação do Dataverse não é suportada.
Receber notificações após a conclusão do script
Está disponível um parâmetro opcional "callbackUrl" no corpo da ação RunDesktopFlow. Pode utilizá-lo se pretender ser notificado da conclusão do seu script. Será enviado um pedido POST para o URL fornecido quando o script for concluído.
Pedido recebido pelo ponto final de chamada de retorno
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 não for fornecido nenhum parâmetro do URL de retorno, o estado da sessão de fluxo deve ser consultado a partir do Dataverse (refere-se a Obter o estado de uma execução de fluxo de ambiente de trabalho).
Note
- Ainda pode utilizar a consulta de estado como um mecanismo de contingência, mesmo que forneça um parâmetro de URL de retorno.
- A sua operação de ponto final de chamada de retorno deverá ser idempotente.
- O pedido POST será tentado novamente três vezes com intervalo de um segundo se o seu ponto final responder com uma resposta de Erro de Servidor (código 500 e superior) ou uma resposta "Tempo Limite do Pedido" (código 408).
Requisitos para o parâmetro de URL de retorno
O seu servidor tem de ter TLS e conjuntos de cifras atuais.
Só é permitido o protocolo HTTPS.
Não é permitido o acesso a localhost (loopback).
Não é possível utilizar endereços IP. Tem de utilizar um endereço Web nomeado que requeira a resolução de nomes DNS.
O seu servidor tem de permitir ligações de valores de endereço IP do Power Platform e do Dynamics 365 especificados sob a etiqueta de serviço do AzureCloud.
Tip
Dado que a chamada de retorno não é autenticada, devem ser tomadas algumas precauções
- Verifique a validade do ID da sessão de fluxo quando for recebida a notificação de chamada de retorno. O Dataverse é a origem da verdade.
- Implemente uma estratégia de limite de taxas no lado do servidor.
- Tente limitar a partilha do URL da chamada de retorno entre as várias organizações.
Cancelar uma execução de fluxo de ambiente de trabalho
À semelhança da funcionalidade Acionar, também pode cancelar um fluxo de ambiente de trabalho em fila/execução. Para cancelar um fluxo de ambiente de trabalho, utilize a ação CancelDesktopFlowRun.
Pedir para cancelar uma execução do fluxo de ambiente 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 um pedido para cancelar um fluxo de ambiente de trabalho
HTTP/1.1 204 No Content
Erros
Quando um erro ocorre, a resposta tem um formato diferente que corresponde às mensagens de erro do Dataverse. O código de erro http e a mensagem deverão fornecer informações suficientes para compreender o problema.
HTTP/1.1 403 Forbidden
{
"error": {
"code": "0x80040220",
"message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
}
}
Note
Pode indicar-nos as suas preferências no que se refere ao idioma da documentação? Responda a um breve inquérito. (tenha em atenção que o inquérito está em inglês)
O inquérito irá demorar cerca de sete minutos. Não são recolhidos dados pessoais (declaração de privacidade).
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários