Mit Desktopflows mittels Code arbeiten

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

Anforderungen

Kenntnisse der Dataverse-Web-API, Authentifizierung mit Dataverse und Verwenden von OAuth mit Dataverse.
Wissen über Dataverse-Umgebungs- und Organisationskonzepte und wie Sie die Organisations-URL manuell oder programmgesteuert abrufen.
Kenntnisse über Desktopflusskonzepte und darüber, was Verbindungen sind und wie sie erstellt werden.

Wichtig

Ersetzen Sie in diesem Artikel alle eckigen Klammern [...] in URLs und Eingabe-/Ausgabedaten durch werte, die für Ihr Szenario spezifisch sind.

Liste verfügbarer Desktop-Flows

Dataverse speichert alle Desktopflussskripts als Teil der Workflowentität.

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

Notiz

Standardmäßig gibt diese Anforderung nur veröffentlichte Desktopflüsse zurück. Fügen Sie den MSCRM.IncludeUnpublished Anforderungsheader mit dem Wert truehinzu, um nicht veröffentlichte Desktopflüsse (Entwurf) in die Antwort einzuschließen.

Anforderung zum Abrufen von Desktopflüssen einschließlich unveröffentlichter Flüsse (Entwurf)

Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
MSCRM.IncludeUnpublished: true

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 oder Ausgaben abrufen müssen, verwenden Sie das clientData Feld für den Zielworkflow.

Eingabeschema für Desktop-Flows 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"
    }
}

Ausgabeschema für Desktop-Flows 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, das Ausgabeschema der Desktop-Flows abzurufen

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

Den Status einer Desktop-Flow-Ausführung abrufen

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

Status einer Desktop-Flow-Ausführung abrufen

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 zum Status einer Desktop-Flow-Ausführung

{
    "@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 abrufen

Wenn der Desktopfluss Ausgaben enthält, fragen Sie das outputs Feld ab, um sie abzurufen.

Anfrage zu 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. Verwenden Sie die RunDesktopFlow-Aktion, um diese Funktionalität zu implementieren.

Um die Aktion aufzurufen, benötigen Sie die folgenden Informationen.

Die ID des Desktop-Flows, den Sie ausführen möchten. Rufen Sie diese ID über die API ab, da der Abschnitt " Verfügbare Desktopflüsse auflisten " weiter oben in diesem Artikel beschrieben wird.

Tipp

Alternativ können Sie die ID manuell aus der Desktopflussdetails-URL 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.
Die name der Verbindung für den Desktopfluss (mit Ziel auf einen Computer oder eine Computergruppe), die zum Ausführen Ihres Flusses verwendet werden soll. Rufen Sie den Namen aus der URL derselben Verbindungsseite in Power Automate ab. 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 Desktop-Flow-Verbindungen erstellen.

Tipp

Alternativ können Sie den logischen Namen eines Verbindungsverweises als Eingabe der Verbindung anstelle des Verbindungsnamens verwenden (Verwendungsbeispiel im folgenden Abschnitt beschrieben). Die Verbindungsverweise werden in der Dataverse-Tabelle connectionreference gespeichert, und Sie können sie programmgesteuert auf die gleiche Weise auflisten wie Desktopflüsse, die im Abschnitt "Verfügbare Desktopflüsse auflisten " beschrieben sind.

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 aus einer Anforderung 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"
}

Sie können die Skripteingaben auf der Seite mit den Ausführungsdetails im Power Automate-Portal (in der Vorschau) anzeigen.

Warnung

Beachten Sie bei der Verwendung der API die folgenden Einschränkungen:

Auslösen eines Desktopablaufs, der mithilfe eines Kontos mit Benutzerrechten ausgeführt wird. Um die Ausführung abzubrechen oder den Status abzufragen, benötigen Sie Besitzerberechtigungen .
Der 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 vom Callback-Endpunkt empfangen

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 Callback-URL-Parameter angegeben wird, sollte der Status der Flowsitzung in Dataverse abgefragt werden (siehe 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.
Die Operation Ihres Callback-Endpunkts 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 Trigger-Funktion können Sie auch einen Desktopflow abbrechen, der sich in der Warteschlange befindet oder gerade ausgeführt wird. 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 auf eine Anfrage zum Abbruch 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 Nachricht stellen genügend Informationen bereit, 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

Sie können bis zu 70 Desktopflussläufe pro Minute für jede Verbindung ausführen.

Feedback

War diese Seite hilfreich?

Last updated on 2026-09-01