Power Automate-Web-API

In Zukunft werden alle Flows in Dataverse gespeichert, und dabei wird die umfangreiche Web-API genutzt.

Dieser Inhalt umfasst die Verwaltung der Flows auf der Registerkarte Lösungen in Power Automate. Flows unter Meine Flows werden von diesen APIs derzeit nicht unterstützt.

Erstellen von HTTP-Anforderungen

Um mit dem Erstellen von Anforderungen zu beginnen, müssen Sie zunächst die URL erstellen. Das Format für die Basis-URL der Web-API für Power Automate lautet: https://{Organization ID}.{Regional Subdomain}.dynamics.com/api/data/v9.1/. Die zwei Parameter lauten:

• Die Organisations-ID ist ein eindeutiger Name für die Umgebung, in dem die Flows gespeichert werden.

• Die regionale Unterdomäne hängt vom Ort Ihrer Umgebung ab.

Um diese beiden Parameter zu erhalten.

1. Navigieren Sie zum Power Platform Admin Center.
2. Wählen Sie die Umgebung aus, in der Sie Ihre Flows erstellen.

1. Kopieren Sie die Organisations-ID und die Regions-Subdomain von der Umgebungs-URL.

Sie können die Liste der Ihnen zur Verfügung stehenden Instanzen auch mit der Methode zum Abrufen von Instanzen in der Online Management-API programmgesteuert abrufen.

In jeder Anforderung an die Web-API müssen der Accept-Header und der Content-type-Header auf application/json festgelegt sein.

Füllen Sie abschließend den Authorization-Header mit einem Azure AD-Bearertoken auf. Sie können lernen, wie Sie ein Azure AD-Bearertoken für Dataverse erhalten. Betrachten Sie beispielsweise die folgende Anforderung:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...

Die Antwort enthält die Liste der Flows aus dieser Umgebung:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#workflows",
    "value": [{
        "@odata.etag": "W/\"12116760\"",
        "category": 5,
        "statecode": 0,
        "workflowidunique": "00000000-0000-0000-0000-000000000001",
        "workflowid" : "00000000-0000-0000-0000-000000000002",
        "createdon": "2018-11-15T19:45:51Z",
        "_ownerid_value": "00000000-0000-0000-0000-000000000003",
        "modifiedon": "2018-11-15T19:45:51Z",
        "ismanaged": false,
        "name": "Sample flow",
        "_modifiedby_value": "00000000-0000-0000-0000-000000000003",
        "_createdby_value": "00000000-0000-0000-0000-000000000003",
        "type": 1,
        "description": "This flow updates some data in Dataverse.",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"source\":\"NotSpecified\",\"id\":\"/providers/Microsoft.PowerApps/apis/shared_commondataservice\",\"tier\":\"NotSpecified\"}},\"definition\":{...}},\"schemaVersion\":\"1.0.0.0\"}"
    }]
}

Flows auflisten

Wie oben bereits gezeigt, können Sie die Liste der Workflows abrufen, indem Sie GET für workflows aufrufen. Jeder Workflow verfügt über zahlreiche Eigenschaften. Die wichtigsten von diesen lauten:

Eigenschaftsname	Beschreibung
category	Die Kategorie des Flows. Hier sind die verschiedenen Kategorien. 0 - Klassische Dataverse-Workflows. 1 Klassische Dataverse-Dialoge. 2. Geschäftsregeln. 3. Klassische Dataverse-Aktionen. 4. Geschäftsprozessflüsse. 5 – Automatisierte, sofortige oder geplante Abläufe. 6. Desktop-Flows.
statecode	Der Status des Flows. Der Status kann 0 (deaktiviert) oder 1 (aktiviert) lauten.
workflowidunique	Der eindeutige Bezeichner für die Installation des Flows.
workflowid	Der eindeutige Bezeichner eines Cloud-Flows für alle Importe.
createdon	Das Erstellungsdatum des Flows.
_ownerid_value	Der eindeutige Bezeichner des Benutzers oder Teams, der bzw. das den Flow besitzt. Dies ist eine ID aus der Tabelle systemusers in Dataverse.
modifiedon	Der Zeitpunkt der letzten Aktualisierung des Flows.
ismanaged	Gibt an, ob der Flow durch eine verwaltete Lösung installiert wurde.
name	Der Anzeigename, mit dem Sie den Flow versehen haben.
_modifiedby_value	Der letzte Benutzer, der den Flow aktualisiert hat. Dies ist eine ID aus der Tabelle systemusers in Dataverse.
_createdby_value	Der Benutzer, der den Flow erstellt hat. Dies ist eine ID aus der Tabelle systemusers in Dataverse.
type	Gibt an, ob der Flow ausgeführt wird oder eine Vorlage ist, die zum Erstellen weiterer Flows verwendet werden kann. 1: Flow, 2: Aktivierung oder 3: Vorlage.
description	Die vom Benutzer bereitgestellte Beschreibung des Flows.
clientdata	String-codiertes JSON eines Objekts, das die „connectionReferences“ und die „definition“ des Flows enthält.

Die Dokumentation für den Dataverse-Workflow hat zusätzliche Informationen über Eigenschaften/Felder und deren Verwendung.

Sie können auch bestimmte Eigenschaften anfordern, die Liste der Flows filtern und viele weitere Aktionen ausführen, wie in der Dataverse-API-Dokumentation zur Datenabfrage beschrieben. Die folgende Abfrage gibt beispielsweise nur automatisierte, sofortige oder geplante Flows zurück, die derzeit aktiviert sind:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows?$filter=category eq 5 and statecode eq 1
Accept: application/json
Authorization: Bearer ey...

Einen Cloud-Flow erstellen

Rufen Sie POST für die Sammlung workflows auf, um einen Cloud-Flow zu erstellen. Die erforderlichen Eigenschaften für automatisierte, sofortige und geplante Flows lauten: „category“, „name“, „type“, „primaryentity“ und „clientdata“. Verwenden Sie für diese Typen von Flows none als „primaryentity“.

Sie können auch „description“ und „statecode“ angeben.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
        "category": 5,
        "statecode": 0,
        "name": "Sample flow name",
        "type": 1,
        "description": "This flow reads some data from Dataverse.",
        "primaryentity":"none",
        "clientdata": "{\"properties\":{\"connectionReferences\":{\"shared_commondataservice\":{\"connectionName\":\"shared-commondataser-00000000-0000-0000-0000-000000000004\",\"source\":\"Invoker\",\"id\":\"/providers/Microsoft.Power Apps/apis/shared_commondataservice\"}},\"definition\":{\"$schema\": \"https:\/\/schema.management.azure.com\/providers\/Microsoft.Logic\/schemas\/2016-06-01\/workflowdefinition.json#\",\"contentVersion\": \"1.0.0.0\",\"parameters\": {\"$connections\": {\"defaultValue\": {},\"type\": \"Object\"},\"$authentication\": {\"defaultValue\": {},\"type\": \"SecureObject\"}},\"triggers\": {\"Recurrence\": {\"recurrence\": {\"frequency\": \"Minute\",\"interval\": 1},\"type\": \"Recurrence\"}},\"actions\": {\"List_records\": {\"runAfter\": {},\"metadata\": {\"flowSystemMetadata\": {\"swaggerOperationId\": \"GetItems_V2\"}},\"type\": \"ApiConnection\",\"inputs\": {\"host\": {\"api\": {\"runtimeUrl\": \"https:\/\/firstrelease-001.azure-apim.net\/apim\/commondataservice\"},\"connection\": {\"name\": \"@parameters('$connections')['shared_commondataservice']['connectionId']\"}},\"method\": \"get\",\"path\": \"\/v2\/datasets\/@{encodeURIComponent(encodeURIComponent('default.cds'))}\/tables\/@{encodeURIComponent(encodeURIComponent('accounts'))}\/items\",\"queries\": {\"$top\": 1},\"authentication\": \"@parameters('$authentication')\"}}},\"outputs\": {}}},\"schemaVersion\":\"1.0.0.0\"}"
}

Der wichtigste Abschnitt ist clientdata. Dieser enthält die „connectionReferences“, die der Flow verwendet, und die „definition“ des Flows. Die „connectionReferences“ sind die Zuordnungen zu jeder Verbindung, die vom Flow verwendet wird.

Es gibt drei Eigenschaften:

Eigenschaftsname	Beschreibung
connectionName	Gibt die Verbindung an. Sie können den „connectionName“ anzeigen, indem Sie die Seite Verbindungen öffnen und ihn aus der URL der Verbindung kopieren.
source	Entweder Embedded oder Invoker. Invoker ist nur für sofortige Flows (Flows, bei denen ein Benutzer eine Schaltfläche auswählt, um den Flow auszuführen) gültig und gibt an, dass der Endbenutzer die Verbindung bereitstellt. In diesem Fall wird der „connectionName“ nur zur Entwurfszeit verwendet. Wenn die Verbindung Embedded ist, bedeutet dies, dass der von Ihnen angegebene „connectionName“ immer verwendet wird.
id	Der Bezeichner des Connectors. Die „id“ beginnt immer mit /providers/Microsoft.PowerApps/apis/, gefolgt vom Connectornamen. Sie können diesen aus der URL der Verbindung kopieren oder auf der Seite Connectors auswählen.

Nachdem Sie die POST-Anforderung ausgeführt haben, erhalten Sie den OData-EntityId-Header, der die workflowid für den neuen Flow enthält.

Einen Cloud-Flow aktualisieren

Sie können PATCH für den Workflow aufrufen, um einen Cloud-Flow zu aktualisieren, zu aktivieren oder zu deaktivieren. Verwenden Sie für diese Aufrufe die workflowid-Eigenschaft. Beispielsweise können Sie mit dem folgenden Aufruf die Beschreibung und den Besitzer des Flows aktualisieren:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "description" : "This flow will ensure consistency across systems.",
    "ownerid@odata.bind": "systemusers(00000000-0000-0000-0000-000000000005)"
}

Note

In der Syntax zum Ändern des Besitzers wird das odata.bind-Format verwendet. Dies bedeutet, dass Sie @odata.bind an den Eigenschaftsnamen anfügen und dann die ID mit systemusers() umschließen, statt das Feld _ownerid_value direkt zu patchen.

In einem weiteren Beispiel können Sie mit dem folgenden Aufruf einen Cloud-Flow aktivieren:

PATCH https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "statecode" : 1
}

Cloud-Flow löschen

Löschen Sie einen Cloud-Flow mit einem einfachen Aufruf von DELETE:

DELETE https://org00000000.crm0.dynamics.com/api/data/v9.1/workflows(00000000-0000-0000-0000-000000000002)
Accept: application/json
Authorization: Bearer ey...

Note

Sie können keinen Cloud-Flow löschen, der aktiviert ist. Sie müssen zunächst den Flow deaktivieren (siehe Aktualisieren eines Cloud-Flow weiter oben). Andernfalls wird folgender Fehler angezeigt: Cannot delete an active workflow definition.

Abrufen aller Benutzer, für die ein Cloud-Flow freigegeben ist

Für das Auflisten der Benutzer mit Zugriff wird eine Funktion in Dataverse verwendet. Diese Funktion akzeptiert einen Target-Parameter:

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/RetrieveSharedPrincipalsAndAccess(Target=@tid)?@tid={'@odata.id':'workflows(00000000-0000-0000-0000-000000000002)'}
Accept: application/json
Authorization: Bearer ey...

Der Target-Parameter ist eine JSON-ähnliche Zeichenfolge mit einer einzelnen Eigenschaft, deren Name @odata.id lautet. Ersetzen Sie die Workflow-ID im vorherigen Beispiel. Rückgabe:

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.RetrieveSharedPrincipalsAndAccessResponse",
    "PrincipalAccesses": [
        {
            "AccessMask": "ReadAccess",
            "Principal": {
                "@odata.type": "#Microsoft.Dynamics.CRM.systemuser",
                "ownerid": "00000000-0000-0000-0000-000000000005"
            }
        }
    ]
}

Freigeben oder Aufheben der Freigabe eines Cloud-Flow

Sie können einen Cloud-Flow mit der Aktion GrantAccess freigeben.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/GrantAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "PrincipalAccess": {
        "Principal": {
            "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
            "ownerid" : "00000000-0000-0000-0000-000000000005"
        },
        "AccessMask": "ReadAccess"
    }
}

Der AccessMask-Parameter ist ein Feld mit den folgenden Werten für unterschiedliche Berechtigungsstufen:

Name	Beschreibung
keine	Kein Zugriff.
Lesezugriff	Das Recht zum Lesen des Flows.
WriteAccess	Das Recht zum Aktualisieren des Flows.
DeleteAccess	Das Recht zum Löschen des Flows.
ShareAccess	Das Recht zum Freigeben des Flows.
AssignAccess	Das Recht zum Ändern des Besitzers des Flows.

Sie können Berechtigungen mit einem Komma kombinieren. Beispielsweise können Sie ReadAccess,WriteAccess übergeben, um das Lesen und Aktualisieren eines Cloud-Flow zu ermöglichen.

Mit der Aktion RevokeAccess können Sie die Freigabe eines Cloud-Flows aufheben. Im Folgenden finden Sie ein Beispiel:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/RevokeAccess
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "Target" : {
        "@odata.type": "Microsoft.Dynamics.CRM.workflow",
        "workflowid" : "00000000-0000-0000-0000-000000000002"
    },
    "Revokee": {
        "@odata.type" : "Microsoft.Dynamics.CRM.systemuser",
        "ownerid" : "00000000-0000-0000-0000-000000000005"
    }
}

Mit RevokeAccess werden alle in der AccessMask erteilten Berechtigungen entfernt.

Exportieren von Flows

Verwenden Sie die Aktion ExportSolution, um Flows in eine ZIP-Datei zu exportieren. Fügen Sie zunächst die gewünschten Flows einer Lösung hinzu.

Sobald sich der Flow in einer Lösung befindet, rufen Sie die folgende Aktion auf:

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ExportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "SolutionName" : "Awesome solution 1",
    "Managed": false
}

ExportSolution gibt eine Base-64-codierte Zeichenfolge in der ExportSoutionFile-Eigenschaft zurück.

{
    "@odata.context": "https://org00000000.crm0.dynamics.com/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ExportSolutionResponse",
    "ExportSolutionFile": "UEsDBBQAAgAI..."
}

Anschließend können Sie diese Datei in der Quellcodeverwaltung speichern und/oder ein beliebiges Versionsverwaltungs- oder Verteilungssystem verwenden.

Importieren von Flows

Rufen Sie die Aktion ImportSolution auf, um eine Lösung zu importieren.

Eigenschaftsname	Beschreibung
OverwriteUnmanagedCustomizations	Wenn in Dataverse Instanzen dieser Flows vorhanden sind, muss dieses Flag auf true festgelegt werden, um sie zu importieren. Andernfalls werden sie nicht überschrieben.
PublishWorkflows	Gibt an, ob beim Import klassische Dataverse-Workflows aktiviert werden. Diese Einstellung gilt nicht für andere Typen von Flows.
ImportJobId	Stellt eine neue, eindeutige GUID zum Nachverfolgen des Importauftrags bereit.
CustomizationFile	Eine Base-64-codierte ZIP-Datei, die die Lösung enthält.

POST https://org00000000.crm0.dynamics.com/api/data/v9.1/ImportSolution
Accept: application/json
Authorization: Bearer ey...
Content-type: application/json
{
    "OverwriteUnmanagedCustomizations": false,
    "PublishWorkflows" : true,
    "ImportJobId" : "00000000-0000-0000-0000-000000000006",
    "CustomizationFile" : "UEsDBBQAAgAI..."
}

Da der Import länger dauert, lautet die Antwort auf die Aktion „ImportSolution“ 204 No content. Um den Fortschritt nachzuverfolgen, rufen Sie GET für das importjobs-Objekt auf, und geben Sie dabei die ImportJobId an, die Sie in die ursprüngliche Aktion ImportSolution eingeschlossen haben.

GET https://org00000000.crm0.dynamics.com/api/data/v9.1/importjobs(00000000-0000-0000-0000-000000000006)
Accept: application/json
Authorization: Bearer ey...

Dieser Aufruf gibt den Status des Importvorgangs, einschließlich progress (der Fortschritt in Prozent), startedon und completedon (wenn der Import abgeschlossen wurde), zurück.

Nachdem der Import erfolgreich abgeschlossen wurde, müssen Sie die Verbindungen des Flows einrichten, da die connectionNames in der Zielumgebung wahrscheinlich unterschiedlich sind (sofern die Verbindungen überhaupt vorhanden sind). Wenn Sie in der Zielumgebung neue Verbindungen einrichten, muss der Besitzer der Flows sie im Power Automate-Designer erstellen. Wenn die Verbindungen in der neuen Umgebung bereits eingerichtet sind, können Sie mit PATCH die clientData des Flows mit den Namen der Verbindungen patchen.

Note

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).