Mit Desktopflows mittels Code arbeiten

Artikel
02/19/2024

Entwickler können Desktop-Flows Funktionalität für ihre Anwendungen hinzufügen, einschließlich programmgesteuertem Auslösen und Abbrechen von Desktop-Flows. Diese Funktionen werden im Rahmen von Microsoft Dataverse Plattform angeboten.

Anforderungen

Wissen über Dataverse Web-API, Authentifizierung mit Dataverse und Verwenden von OAuth mit Dataverse.
Wissen über Dataverse Umgebung und Organisationskonzepte und so rufen Sie die Organisations-URL ab manuell oder programmgesteuert.
Wissen über Desktop-Flow-Begriffe und wovon Verbindungen sind und wie man sie erstellt.

Wichtig

In diesem Artikel müssen Sie alle eckigen Klammern [...] in URLs und Eingabe-/Ausgabedaten durch für Ihr Szenario spezifische Werte ersetzen.

Liste verfügbarer Desktop-Flows

Alle Desktop-Flows-Skripte sind in Dataverse Im Rahmen der Workflow-Entität enthalten.

Filtern Sie die Liste der Workflows basierend auf der Kategorie, um Desktop-Flows zu identifizieren.

Anfrage zum Abrufen von Desktop-Flows

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

Antwort auf die Anfrage zum Abrufen von Desktop-Flows

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

Schema für Desktop-Flow abrufen

Wenn Sie das Flussschema für Eingaben und/oder Ausgaben abrufen müssen, können Sie das Feld clientData für den Zielworkflow verwenden.

EinhabeSchema für Desktop-Flow anfordern

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

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

Antwort auf die Anfrage zum Abrufen des Desktop-Flow-Eingabe-Schemas

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

Ausgabe-Schema für Desktop-Flow anfordern

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

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

Antwort auf die Anfrage zum Abrufen des Desktop-Flow-Ausgabe-Schemas

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

Status einer Desktop-Flow-Ausfühurung abrufen

Dataverse speichert alle Desktop-Flow-Ausführungen in der flowsession-Entität.

Status einer Desktop-Flow-Ausfühurung anfordern

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

Antwort für den Status einer Desktop-Flow-Ausfühurung anfordern

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

Desktop-Flow-Ausgaben anzeigen

Wenn der Desktop-Flow Ausgaben hat, können Sie das Ausgabefeld abfragen, um sie abzurufen.

Anforderung für Desktop-Flow-Ausgaben

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

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

Antwort auf die Anfrage zum Abrufen von Desktop-Flow-Ausgaben

{
    "Output1": "My output value"
}

Desktop-Flow-Ausführung auslösen

Durch die Nutzung von Dataverse können Sie die Funktionalität zum Auslösen eines Desktop-Flows über Ihre Anwendung hinzufügen. Umm diese Funktion zu implementieren, müssen Sie die RunDesktopFlow-Aktion verwenden.

Sie müssen auch die folgenden Informationen angeben, um die Aktion aufzurufen.

Die ID des Desktop-Flows, den Sie ausführen möchten. Sie können diese ID über die API als Verfügbare Desktop-Flows auflisten Abschnitt skizziert weiter oben in diesem Artikel.

Tipp

Alternativ können Sie die ID manuell über die URL der Desktop-Flow-Details in Power Automate abrufen. Das URL-Format lautet: https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details.

Weitere Informationen finden Sie unter Desktop-Flows verwalten.
Der name der Desktop-Flow-Verbindung (Ziel ist ein Computer oder eine Computergruppe), die zum Ausführen Ihres Flows verwendet werden soll. Der Name kann aus der URL der gleichen Verbindungsseite in Power Automate abgerufen werden. Das URL-Format lautet:
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name].

Notiz

Weitere Informationen finden Sie unter Erstellen oder Bearbeiten einer Desktop-Flow-Verbindung.

Tipp

Alternativ können Sie anstelle der Verbindungsreferenz den logischen Namen einer Verbindung als Eingabe der Verbindung verwenden (Anwendungsbeispiel unten beschrieben). Die Verbindungsreferenzen werden in der Dataverse Tabellenverbindungsreferenz gespeichert und können programmgesteuert auf die gleiche Weise aufgelistet werden wie Desktop-Flows, die im Abschnitt Verfügbare Desktop-Flows auflisten beschrieben werden.

Weitere Informationen finden Sie unter Verwenden Sie eine Verbindungsreferenz in einer Lösung und Verbindungsreferenztabelle/Entität-Referenz.

Anfrage zum Auslösen eines Desktop-Flows

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

Anfrage zum Auslösen eines Desktop-Flows mit einer Verbindungsreferenz

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

Antwort von Anfrage zum Auslösen eines Desktop-Flows

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

Die Eingaben des Skripts sind auf der Ausführungsdetailseite im Power Automate Portal (in der Vorschauversion) sichtbar.

Warnung

Bei der Verwendung der API sind einige Einschränkungen zu beachten:

Das Auslösen einer Desktop-Flow-Ausführung mit einem Konto mit „Benutzer“-Berechtigungen funktioniert. Das Abbrechen der Ausführung und das Abfragen des Status erfordert jedoch Besitzerrechte.
Dataverse Identitätswechsel wird nicht unterstützt.
Die Größe des Eingabefeldinhalts ist auf 2 MB begrenzt.

Erhalten Sie eine Benachrichtigung über den Abschluss des Skripts

Ein optionaler Parameter „callbackUrl“ ist im Hauptteil der RunDesktopFlow-Aktion verfügbar. Sie können es verwenden, wenn Sie über die Fertigstellung Ihres Skripts benachrichtigt werden möchten. Nach Abschluss des Skripts wird eine POST-Anforderung an die angegebene URL gesendet.

Anfrage empfangen durch den Rückruf Endpunkt

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

Wenn kein Rückruf-URL-Parameter bereitgestellt wird, sollte der Flow-Sitzungsstatus aus Dataverse abgefragt werden (bezieht sich auf Den Status einer Desktop-Flow-Ausführung abrufen).

Notiz

Sie können die Statusabfrage weiterhin als Fallback-Mechanismus verwenden, selbst wenn Sie einen Rückruf-URL-Parameter angeben.
Ihre Callback-Operation Endpunkt sollte idempotent sein.
Die POST-Anforderung wird dreimal im Abstand von einer Sekunde wiederholt, wenn Ihr Endpunkt mit einer Serverfehlerantwort (Code 500 und höher) oder einer „Request Timeout“-Antwort (Code 408) antwortet.

Anforderungen für den Rückruf-URL-Parameter

Ihr Server muss über die aktuellen TLS und verschlüsselten Suiten verfügen.
Nur das HTTPS-Protokoll ist erlaubt.
Der Zugriff auf localhost (Loopback) ist nicht erlaubt.
IP-Adressen können nicht verwendet werden. Sie müssen eine benannte Internetadresse verwenden, die die DNS-Namensauflösung erfordert.
Ihr Server muss Verbindungen von IP-Adresswerten von Power Platform- und Dynamics 365-Diensten, die unter dem AzureCloud-Diensttag angegeben sind, zulassen.

Tipp

Da der Rückruf nicht authentifiziert wird, sollten einige Vorsichtsmaßnahmen getroffen werden

Überprüfen Sie die Gültigkeit der Flow-Sitzungs-ID, wenn die Rückrufbenachrichtigung empfangen wird. Dataverse ist die Quelle der Wahrheit.
Implementieren Sie eine Ratenbegrenzungsstrategie auf Ihrer Serverseite.
Versuchen Sie, die Rückruf-URL-Freigabe zwischen mehreren Organisationen einzuschränken.

Desktop-Flow-Ausführung abbrechen

Ähnlich wie bei der Funktion Trigger können Sie auch einen in der Warteschlange befindlichen/ausgeführten Desktop-Flow abbrechen. Um einen Desktop-Flow abzubrechen, verwenden Sie die CancelDesktopFlowRun-Aktion.

Anfrage zum Abbrechen einer Desktop-Flow-Ausführung

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

Antwort von Anfrage zum Abbrechen eines Desktop-Flows

HTTP/1.1 204 No Content

Fehler

Wenn ein Fehler auftritt, hat die Antwort ein anderes Format, das zu Dataverse Fehlermeldungen passt. Der HTTP-Fehlercode und die Meldung sollten genügend Informationen liefern, um das Problem zu verstehen.

HTTP/1.1 403 Forbidden

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

Bekannte Einschränkungen

Wir unterstützen derzeit für jede Verbindung bis zu 70 Desktop-Flow-Ausführungen pro Minute.