Utiliser des flux de bureau à l’aide de code

Article
02/19/2024

Les développeurs peuvent ajouter une fonctionnalité flux de bureau à leurs applications, y compris le déclenchement et l’annulation par programme des flux de bureau. Ces fonctionnalités sont proposées dans le cadre de la plateforme Microsoft Dataverse.

Conditions préalables

Connaissance de l’API Web Dataverse, authentification avec Dataverse et utilisation de OAuth avec Dataverse.
Connaissance des notions d’environnement et d’organisation Dataverse, et comment récupérer l’URL de l’organisation manuellement ou par programmation.
Connaissance des notions de flux de bureau et de ce que sont les connexions et comment les créer.

Important

Dans cet article, vous devez remplacer tous les crochets [...] dans les URL et les données d’entrée/sortie par les valeurs spécifiques à votre scénario.

Répertorier les flux de bureau disponibles

Tous les scripts de flux de bureau sont dans Dataverse comme appartenant à l’entité de flux de travail.

Filtrez la liste des flux de travail en fonction de la catégorie pour identifier les flux de bureau.

Requête de récupération des flux de bureau

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

Réponse à la demande d’obtention de flux de bureau

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

Obtenir le schéma pour les flux de bureau

Si vous avez besoin de récupérer le schéma de flux pour les entrées et/ou les sorties, vous pouvez utiliser le champ clientData pour le workflow cible.

Demander le schéma d’entrées pour les flux de bureau

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

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

Réponse à la demande d’obtention du schéma d’entrées du flux de bureau

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

Demander le schéma de sorties pour les flux de bureau

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

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

Réponse à la demande d’obtention du schéma de sorties de flux de bureau

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

Obtenir le statut d’exécution d’un flux de bureau

Dataverse stocke toutes les exécutions de flux de bureau dans l’entité flowsession.

Demander le statut d’exécution d’un flux de bureau

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

Réponse pour le statut d’exécution d’un flux de bureau

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

Obtenir les sorties d’un flux de bureau

Si le flux de bureau a des sorties, vous pouvez interroger le champ des sorties pour les récupérer.

Demander les sorties pour un flux de bureau

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

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

Réponse à la demande d’obtention des sorties d’un flux de bureau

{
    "Output1": "My output value"
}

Déclencher une exécution de flux de bureau

En utilisant Dataverse, vous pouvez ajouter la fonctionnalité de déclenchement d’un flux de bureau via votre application. Pour implémenter cette fonctionnalité, vous devez utiliser l’action RunDesktopFlow.

Pour appeler l’action, vous aurez besoin des informations suivantes.

LID du flux de bureau que vous souhaitez exécuter. Vous pouvez obtenir cet ID via l’API de la manière décrite dans la section Répertorier les flux de bureau disponibles, plus haut dans cet article.

Pourboire

Vous pouvez également récupérer l’ID manuellement à partir de l’URL des détails du flux de bureau dans Power Automate. Le format de l’URL est : https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Pour en savoir plus, voir Gérer les flux de bureau.
Le name de la connexion de flux de bureau (ciblant une machine ou un groupe de machines) à utiliser pour exécuter votre flux. Le nom peut être récupéré à partir de l’URL de la même page de connexion au format Power Automate. Le format de l’URL est :
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Note

Pour plus d’informations, consultez Créer des connexions de flux de bureau.

Pourboire

Vous pouvez également utiliser le nom logique d’une référence de connexion comme entrée de la connexion au lieu du nom de la connexion (exemple d’utilisation décrit ci-dessous). Les références de connexion sont stockées dans la table connectionreference Dataverse et peuvent être répertoriées par programme de la même manière que les flux de bureau détaillés dans la section Répertorier les flux de bureau disponibles.

Pour en savoir plus, voir Utiliser une référence de connexion dans une solution et Référence d’entité/de table connectionreference.

Demande de déclenchement d’un flux de bureau

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

Demande de déclenchement d’un flux de bureau avec une référence de connexion

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

Réponse à la demande de déclenchement d'un flux de bureau

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

Les entrées du script sont visibles dans la page des détails de l’exécution sur le portail Power Automate (dans la version préliminaire).

Avertissement

Lors de l’utilisation de l’API, certaines limitations doivent être prises en compte :

Le déclenchement d’une exécution de flux de bureau avec un compte disposant des privilèges « Utilisateur » fonctionnera. Cependant, l’annulation de l’exécution et l’interrogation du statut nécessitent des privilèges « Propriétaire ».
L’emprunt d’identité Dataverse n’est pas pris en charge.
La taille du contenu du champ d’entrée est limitée à 2 Mo.

Recevoir une notification à la fin du script

Un paramètre optionnel « callbackUrl » est disponible dans le corps de l’action RunDesktopFlow. Vous pouvez l’utiliser si vous souhaitez être averti de l’achèvement de votre script. Une requête POST sera envoyée à l’URL fournie lorsque le script sera terminé.

Requête reçue par le point de terminaison de rappel

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 aucun paramètre d’URL de rappel n’est fourni, le statut de la session de flux doit être interrogé à partir de Dataverse (fait référence à Obtenir le statut d’une exécution de flux de bureau).

Note

Vous pouvez toujours utiliser l’interrogation de statut comme mécanisme de secours même si vous fournissez un paramètre d’URL de rappel.
Votre opération de point de terminaison de rappel doit être idempotente.
La requête POST sera réessayée trois fois avec un intervalle d’une seconde si votre point de terminaison répond avec une réponse d’erreur de serveur (code 500 et supérieur) ou une réponse « Délai d’expiration » (code 408).

Conditions requises pour le paramètre d’URL de rappel

Votre serveur doit utiliser les suites de chiffrement et TLS actuelles.
Seul le protocole HTTPS est autorisé.
L’accès à localhost (bouclage) n’est pas autorisé.
Les adresses IP ne peuvent pas être utilisées. Vous devez utiliser une adresse Web nommée qui requiert la résolution de noms DNS.
Votre serveur doit autoriser les connexions depuis Power Platform et les valeurs d’adresse IP des services Dynamics 365 spécifiées sous la balise de service AzureCloud.

Pourboire

L’appel de rappel n’étant pas authentifié, quelques précautions doivent être prises

Vérifiez la validité de l’ID de session de flux lorsque la notification de rappel est reçue. Dataverse est la source de vérité.
Implémentez une stratégie de limite de débit côté serveur.
Essayez de limiter le partage d’URL de rappel entre plusieurs organisations.

Annuler une exécution du flux de bureau

Comme pour la fonctionnalité Déclencheur, vous pouvez également annuler un flux de bureau en file d’attente/en cours d’exécution. Pour annuler un flux de bureau, utilisez l’action CancelDesktopFlowRun.

Demande d’annulation de l’exécution d’un flux de bureau

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

Réponse à une demande d’annulation d’un flux de bureau

HTTP/1.1 204 No Content

Erreurs

Lorsqu’une erreur se produit, la réponse a un format différent qui correspond au message d’erreur de Dataverse. Le code d’erreur HTTP et le message doivent fournir suffisamment d’informations pour comprendre le problème.

HTTP/1.1 403 Forbidden

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

Limitations connues

Nous prenons actuellement en charge jusqu’à 70 exécutions de flux de bureau par minute pour chaque connexion.