Utilizzare i flussi desktop con il codice
Gli sviluppatori possono aggiungere funzionalità di flussi desktop alle loro applicazioni, inclusi l'attivazione e l'annullamento di flussi desktop a livello di codice. Queste funzionalità sono offerte come parte della piattaforma Microsoft Dataverse.
Prerequisiti
- Conoscenza di API Web Dataverse, autenticazione con Dataverse e uso di OAuth con Dataverse.
- Conoscenza di nozioni di ambiente e organizzazione Dataverse, e come recuperare l'URL dell'organizzazione manualmente o a livello di programmazione.
- Conoscenza di nozioni di flussi desktop e di cosa sono le connessioni e come crearle.
Important
In questo articolo, devi sostituire tutte le parentesi quadre [...] negli URL e nei dati di input/output con valori specifici per il tuo scenario.
Elencare i flussi desktop disponibili
Tutti gli script dei flussi desktop sono in Dataverse come parte dell'entità del flusso di lavoro.
Filtra l'elenco dei flussi di lavoro in base alla categoria per identificare i flussi desktop.
Richiedi il recupero dei flussi desktop
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
Rispondi alla richiesta di recupero dei flussi desktop
{
"@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",
}
]
}
Recupera lo schema dei flussi desktop
Se è necessario recuperare lo schema di flusso per input e/o output, è possibile utilizzare il campo clientData per il flusso di lavoro di destinazione.
Richiedi lo schema dei flussi desktop
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/clientdata/$value HTTP/1.1
Rispondi alla richiesta di recupero dello schema dei flussi desktop
{
"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"
}
}
}
Ottieni lo stato di un'esecuzione del flusso desktop
Dataverse archivia tutte le esecuzioni del flusso desktop nell'entità flowsession.
Richiedi lo stato di un'esecuzione del flusso desktop
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
Rispondi per lo stato di un'esecuzione del flusso desktop
{
"@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",
}
Recupera gli output del flusso desktop
Se il flusso desktop ha output, puoi eseguire una query sul campo output per recuperarli.
Richiedi gli output del flusso desktop
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1
Rispondi alla richiesta di output del flusso desktop
{
"Output1": "My output value"
}
Attivare l'esecuzione di un flusso desktop
Usando Dataverse, puoi aggiungere la funzionalità di attivazione di un flusso desktop attraverso la tua applicazione. Per implementare questa funzionalità, devi utilizzare l'azione RunDesktopFlow.
Per chiamare l'azione devi fornire le seguenti informazioni.
IDdel flusso desktop da eseguire. Puoi ottenere questo ID tramite l'API come indicato nella sezione Elencare i flussi desktop disponibili in precedenza in questo articolo.Tip
In alternativa, puoi recuperare l'ID manualmente dall'URL dei dettagli del flusso desktop in Power Automate. Il formato dell'URL è:
https://flow.microsoft.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.Per ulteriori informazioni. vedi Gestire i flussi desktop.
namedella connessione del flusso desktop (macchina di destinazione/gruppo di macchine) da utilizzare per eseguire il flusso. Il nome può essere recuperato dall'URL della stessa pagina di connessione in Power Automate. Il formato dell'URL è:
https://flow.microsoft.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].Note
Per altre informazioni, vedi Creare connessioni per un flusso desktop.
Tip
In alternativa, è possibile utilizzare il nome logico di un riferimento di connessione come input della connessione anziché il nome della connessione (esempio di utilizzo descritto di seguito). I riferimenti di connessione sono memorizzati nel connectionreference della tabella Dataverse e possono essere elencati in modo programmatico allo stesso modo dei flussi desktop descritti in dettaglio nella sezione Elencare i flussi desktop disponibili.
Per ulteriori informazioni, vedi Utilizzare un riferimento di connessione in una soluzione e Tabella connectionreference/riferimento dell'entità.
Richiesta di attivare un flusso desktop
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\"}"
}
Richiesta di attivare un flusso desktop con un riferimento di connessione
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\"}"
}
Risposta della richiesta di attivare un flusso desktop
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
"flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}
Warning
Quando si utilizza l'API, è necessario tenere presente alcune limitazioni:
Quando si attiva un'esecuzione del flusso desktop tramite l'API, gli input dello script non sono visualizzabili nella pagina dei dettagli dell'esecuzione nel portale di Power Automate.
Il proprietario della sessione di flusso che rappresenta l'esecuzione viene mappato al proprietario dell'entità del flusso di lavoro che rappresenta il flusso desktop. Ci saranno alcune limitazioni quando si chiama l'API su un flusso di lavoro con un privilegio "Utente": l'annullamento dell'esecuzione e la query sullo stato potrebbero essere bloccati per i privilegi mancanti nella sessione del flusso.
La rappresentazione Dataverse non è supportata.
Ricevere una notifica al completamento dello script
Un parametro facoltativo "callbackUrl" è disponibile nel corpo dell'azione RunDesktopFlow. Puoi usarlo se vuoi essere informato del completamento dello script. Una richiesta POST verrà inviata all'URL specificato al completamento dello script.
Richiesta ricevuta dall'endpoint di callback
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 non viene fornito alcun parametro URL di callback, è necessario eseguire il polling dello stato della sessione del flusso da Dataverse (si riferisce a Ottieni lo stato di un'esecuzione del flusso desktop).
Note
- Puoi comunque utilizzare il polling dello stato come meccanismo di fallback anche se fornisci un parametro URL di callback.
- L'operazione dell'endpoint di callback deve essere idempotente.
- La richiesta POST verrà ritentata tre volte con un intervallo di un secondo se il tuo endpoint fornisce una risposta "Errore server" (codice 500 e superiore) o una risposta "Timeout richiesta" (codice 408).
Requisiti per il parametro URL di callback
Il tuo server deve disporre delle suite di cifratura e TLS correnti.
È consentito solo il protocollo HTTPS.
L'accesso a localhost (loopback) non è consentito.
Gli indirizzi IP non possono essere utilizzati. Devi utilizzare un indirizzo Web con nome che richiede la risoluzione dei nomi DNS.
Il tuo server deve consentire le connessioni dai valori degli indirizzi IP dei servizi Dynamics 365 e Power Platform specificati sotto il tag del servizio AzureCloud.
Tip
Poiché la richiamata non è autenticata, è necessario adottare alcune precauzioni
- Verifica la validità dell'ID sessione di flusso quando viene ricevuta la notifica di callback. Dataverse è l'origine di riferimento.
- Implementa una strategia di limite di frequenza sul lato server.
- Prova a limitare la condivisione dell'URL di callback tra diverse organizzazioni.
Annullare l'esecuzione di un flusso desktop
Simile alla funzionalità Trigger, puoi inoltre annullare un flusso desktop in coda o in esecuzione. Per annullare un flusso desktop, utilizza l'azione CancelDesktopFlowRun.
Richiesta di annullamento dell'esecuzione di un flusso desktop
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
Risposta da una richiesta di annullamento di un flusso desktop
HTTP/1.1 204 No Content
Errori
Quando si verifica un errore, la risposta ha un formato diverso che corrisponde ai messaggi di errore Dataverse. Il codice di errore http e il messaggio dovrebbero fornire informazioni sufficienti per comprendere il problema.
HTTP/1.1 403 Forbidden
{
"error": {
"code": "0x80040220",
"message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
}
}
Note
Puoi indicarci le tue preferenze di lingua per la documentazione? Partecipa a un breve sondaggio. (il sondaggio è in inglese)
Il sondaggio richiederà circa sette minuti. Non viene raccolto alcun dato personale (Informativa sulla privacy).
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per