Mit Cloud-Flows mittels Code arbeiten

  • Artikel

Alle Flows werden in Dataverse gespeichert und Sie können zur Verwaltung entweder das Dataverse SDK für .NET oder Web-API verwenden.

Dieser Artikel beschreibt die Verwaltung der Flows auf der Registerkarte Lösungen in Power Automate. Derzeit wird das Verwalten von Flows mit Code unter Meine Flows nicht unterstützt.

Mit Dataverse APIs interagieren

Die Funktionen, die Dataverse bei Verwendung von Dataverse SDK für .NET oder Web-API bietet, sind gleichwertig.

Welche Methode sollte ich verwenden?

Welche Methode die beste ist, hängt von der Projekttechnologie und Ihrem Können ab.

Wenn Ihr Projekt .NET verwendet, sollten Sie das SDK verwenden. Das SDK vereinfacht Ihre Entwicklungsumgebung, indem es ein typisiertes Objektmodell und Methoden zur Authentifizierung bereitstellt.

Weitere Informationen: Verwenden des Organisationsdienstes

Wie kann ich die Verbindung herstellen?

Wie Sie eine Verbindung herstellen, hängt davon ab, ob Sie das Dataverse SDK für .NET oder Web-API verwenden.

Beim SDK müssen Sie eine Verbindung mit einer Clientanwendung herstellen, um Zugriff auf eine IOrganizationService-Instanz zu erhalten. IOrganizationService ist eine Schnittstelle, die Methoden bereitstellt, mit deren Hilfe Sie mit Dataverse interagieren können.

Weitere Informationen:

Workflow-Tabelle

Cloud-Flows werden in der Prozesstabelle (Workflow) gespeichert, die in der Web-API als Workflow-EntityType dargestellt wird

Die folgende Tabelle beschreibt wichtige Spalten in der Workflowtabelle zusammen:

Logischer Name Type Beschreibung
category Auswahl 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äftsprozessflows.
5 - Moderner Flow (automatisierter, Direkt- oder geplanter Flow).
6- Desktop-Flows.
clientdata String Ein zeichenfolgencodiertes JSON der Flow-Definition und ihrer connectionReferences.
createdby Nachschlagefeld Der Benutzer, der den Flow erstellt hat.
createdon DateTime Das Erstellungsdatum des Flows.
description String Die vom Benutzer bereitgestellte Beschreibung des Flows.
ismanaged Bool Gibt an, ob der Flow durch eine verwaltete Lösung installiert wurde.
modifiedby Nachschlagefeld Der letzte Benutzer, der den Flow aktualisiert hat.
modifiedon DateTime Der Zeitpunkt der letzten Aktualisierung des Flows.
name String Der Anzeigename, mit dem Sie den Flow versehen haben.
ownerid Nachschlagefeld Der Benutzende oder das Team, dem der Flow gehört.
statecode Auswahl Der Status des Flows. Folgende Status sind möglich:
0 - Entwurf (Aus)
1 - Aktiviert (Ein)
2 - Ausgesetzt.
type Auswahl Gibt an, ob der Flow ausgeführt wird oder eine Vorlage ist, die zum Erstellen weiterer Flows verwendet werden kann.
1 - Definition,
2 - Aktivierung
3 - Vorlage.
workflowid GUID Der eindeutige Bezeichner eines Cloud-Flows für alle Importe.
workflowidunique GUID Der eindeutige Bezeichner für die Installation des Flows.

Anmerkung

Bei der Web-API sind die Suchwerte einwertige Navigationseigenschaften, die erweitert werden können, um Details aus dem zugehörigen Datensatz abzurufen.

Suchspalten verfügen auch über entsprechende GUID-Sucheigenschaften, die in Abfragen verwendet werden können. Sucheigenschaften haben diese Namenskonvention: _<logical name>_value. Sie können beim Workflow-Entitätstyp in der Web-API auf die folgenden Sucheigenschaften verweisen: _createdby_value, _modifiedby_value und _ownerid_value.

Flows auflisten

Um eine Liste der Cloud-Flows abzurufen, können Sie die Workflowtabelle abfragen. Die folgende Abfrage gibt den ersten automatisierten, Direkt- oder geplanten Flow zurück, der derzeit aktiviert ist:

Für diese statische OutputFirstActiveFlow Methode brauchen Sie einen authentifizierten Client, der die IOrganizationService implementiert. Es verwendet die IOrganizationService.RetrieveMultiple-Methode.

/// <summary>
/// Outputs the first active flow
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
public static void OutputFirstActiveFlow(IOrganizationService service)
{
   var query = new QueryExpression("workflow")
   {
         ColumnSet = new ColumnSet("category",
                                    "createdby",
                                    "createdon",
                                    "description",
                                    "ismanaged",
                                    "modifiedby",
                                    "modifiedon",
                                    "name",
                                    "ownerid",
                                    "statecode",
                                    "type",
                                    "workflowid",
                                    "workflowidunique"),
         Criteria = new FilterExpression(LogicalOperator.And)
         {
            Conditions = {
            {  new ConditionExpression(
               "category",
                     ConditionOperator.Equal,
                     5) }, // Cloud Flow
            {  new ConditionExpression(
                     "statecode",
                     ConditionOperator.Equal,
                     1) } // Active
         }
         },
         TopCount = 1 // Limit to one record
   };

   EntityCollection workflows = service.RetrieveMultiple(query);

   Entity workflow = workflows.Entities.FirstOrDefault();

   Console.WriteLine($"category: {workflow.FormattedValues["category"]}");
   Console.WriteLine($"createdby: {workflow.FormattedValues["createdby"]}");
   Console.WriteLine($"createdon: {workflow.FormattedValues["createdon"]}");
   // Description may be null
   Console.WriteLine($"description: {workflow.GetAttributeValue<string>("description")}");
   Console.WriteLine($"ismanaged: {workflow.FormattedValues["ismanaged"]}");
   Console.WriteLine($"modifiedby: {workflow.FormattedValues["modifiedby"]}");
   Console.WriteLine($"modifiedon: {workflow.FormattedValues["modifiedon"]}");
   Console.WriteLine($"name: {workflow["name"]}");
   Console.WriteLine($"ownerid: {workflow.FormattedValues["ownerid"]}");
   Console.WriteLine($"statecode: {workflow.FormattedValues["statecode"]}");
   Console.WriteLine($"type: {workflow.FormattedValues["type"]}");
   Console.WriteLine($"workflowid: {workflow["workflowid"]}");
   Console.WriteLine($"workflowidunique: {workflow["workflowidunique"]}");
}

Um weitere Datensätze abzurufen, entfernen Sie die Beschränkung TopCount.

Output

category: Modern Flow
createdby: SYSTEM
createdon: 5/20/2020 9:37 PM
description:
ismanaged: Unmanaged
modifiedby: Kiana Anderson
modifiedon: 5/6/2023 3:37 AM
name: When an account is updated -> Create a new record
ownerid: Monica Thomson
statecode: Activated
type: Definition
workflowid: d9e875bf-1c9b-ea11-a811-000d3a122b89
workflowidunique: c17af45c-10a1-43ca-b816-d9cc352718cf

Weitere Informationen:

Einen Cloud-Flow erstellen

Die erforderlichen Eigenschaften für automatisierte, Direkt- und geplante Flows lauten: category, name, type, primaryentity und clientdata. Verwenden Sie für diese Flowtypen none als primaryentity.

Für diese statische Methode brauchen Sie einen authentifizierten Client, der die IOrganizationService implementiert. Es verwendet die IOrganizationService.Create-Methode.

/// <summary>
/// Creates a cloud flow
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
/// <returns>The workflowid</returns>
public static Guid CreateCloudFlow(IOrganizationService service)
{
   var workflow = new Entity("workflow")
   {
         Attributes = {
            {"category", new OptionSetValue(5) }, // Cloud flow
            {"name", "Sample flow name"},
            {"type", new OptionSetValue(1) }, //Definition
            {"description", "This flow reads some data from Dataverse." },
            {"primaryentity", "none" },
            {"clientdata", "{\"properties\":{\"connectionReferences\":{\"shared_commondataserviceforapps\":{\"impersonation\":{},\"runtimeSource\":\"embedded\",\"connection\":{\"name\":\"shared-commondataser-114efb88-a991-40c7-b75f-2693-b1ca6a0c\",\"connectionReferenceLogicalName\":\"crdcb_sharedcommondataserviceforapps_109ea\"},\"api\":{\"name\":\"shared_commondataserviceforapps\"}}},\"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\":{\"manual\":{\"metadata\":{\"operationMetadataId\":\"76f87a86-89b3-48b4-92a2-1b74539894a6\"},\"type\":\"Request\",\"kind\":\"Button\",\"inputs\":{\"schema\":{\"type\":\"object\",\"properties\":{},\"required\":[]}}}},\"actions\":{\"List_rows\":{\"runAfter\":{},\"metadata\":{\"operationMetadataId\":\"9725b30f-4a8e-4695-b6fd-9a4985808809\"},\"type\":\"OpenApiConnection\",\"inputs\":{\"host\":{\"apiId\":\"/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps\",\"connectionName\":\"shared_commondataserviceforapps\",\"operationId\":\"ListRecords\"},\"parameters\":{\"entityName\":\"accounts\",\"$select\":\"name\",\"$top\":1},\"authentication\":\"@parameters('$authentication')\"}}}}},\"schemaVersion\":\"1.0.0.0\"}" }
         }
   };

   return service.Create(workflow);
}

Weitere Informationen: Erstellen von Tabellenzeilen mit dem Organisationsdienst.

Die statecode aller auf diese Weise erstellten Flows sind auf 0 (Entwurf oder „Aus“) gesetzt. Der Flow muss aktiviert werden, bevor er verwendet werden kann.

Die wichtigste Eigenschaft sind die clientdata, welche die connectionReferences enthalten, die ein Flow verwendet, sowie die Definition des Flows. Bei den connectionReferences handelt es sich um die Zuordnungen zu jeder Verbindung, die vom Flow verwendet wird.

{
  "properties": {
    "connectionReferences": {
      "shared_commondataserviceforapps": {
        "runtimeSource": "embedded",
        "connection": {},
        "api": { 
         "name": "shared_commondataserviceforapps" 
         }
      }
    },
    "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": {
        "manual": {
          "metadata": {},
          "type": "Request",
          "kind": "Button",
          "inputs": {
            "schema": { "type": "object", "properties": {}, "required": [] }
          }
        }
      },
      "actions": {
        "List_rows": {
          "runAfter": {},
          "metadata": {},
          "type": "OpenApiConnection",
          "inputs": {
            "host": {
              "apiId": "/providers/Microsoft.PowerApps/apis/shared_commondataserviceforapps",
              "connectionName": "shared_commondataserviceforapps",
              "operationId": "ListRecords"
            },
            "parameters": {
              "entityName": "accounts",
              "$select": "name",
              "$top": 1
            },
            "authentication": "@parameters('$authentication')"
          }
        }
      }
    }
  },
  "schemaVersion": "1.0.0.0"
}

Einen Cloud-Flow aktualisieren

Um einen Flow zu aktualisieren, legen Sie nur die Eigenschaften fest, die Sie ändern möchten.

Für diese statische Methode brauchen Sie einen authentifizierten Client, der die IOrganizationService implementiert. Sie verwendet die Methode IOrganizationService.Update, um eine Flowbeschreibung zu aktualisieren und den Besitzenden festzulegen.

/// <summary>
/// Updates a cloud flow
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
/// <param name="workflowid">The ID of the flow to update.</param>
/// <param name="systemuserid">The id of the user to assign the flow to.</param>
public static void UpdateCloudFlow(IOrganizationService service, Guid workflowid, Guid systemuserid) {

   var workflow = new Entity("workflow",workflowid)
   {
         Attributes = {

            {"description", "This flow will ensure consistency across systems." },
            {"ownerid", new EntityReference("systemuser",systemuserid)},
            {"statecode", new OptionSetValue(1) } //Turn on the flow.
         }
   };

   service.Update(workflow);
}

Weitere Informationen: Tabellenzeilen über den Organisationsdienst aktualisieren und löschen > Grundlegende Aktualisierung

Cloud-Flow löschen

Die folgenden Beispiele zeigen, wie der Workflow-Datensatz gelöscht wird, der einen Cloud-Flow darstellt.

Die statische DeleteCloudFlow Methode löscht einen Workflow-Datensatz.

/// <summary>
/// Deletes a workflow
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
/// <param name="workflowId">The id of the cloud flow to delete.</param>
public static void DeleteCloudFlow(IOrganizationService service, Guid workflowId) { 

service.Delete(entityName:"workflow",id: workflowId);

}

Weitere Informationen: Einen Datensatz mithilfe des SDK löschen

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

Verwenden Sie die RetrieveSharedPrincipalsAndAccess-Nachricht, um eine Liste aller Benutzenden abzurufen, für die ein Cloud-Flow freigegeben ist.

Verwenden Sie beim SDK die RetrieveSharedPrincipalsAndAccessRequest-Klasse und bei der Web-API die RetrieveSharedPrincipalsAndAccess-Funktion.

Weitere Informationen: Prinzipale mit Zugriff auf einen Datensatz abrufen

Freigeben oder Aufheben der Freigabe eines Cloud-Flow

Teilen Sie einen Cloud-Flow wie jeden anderen Dataverse-Datensatz mit der GrantAccess-Nachricht. Verwenden Sie beim SDK die GrantAccessRequest-Klasse und bei der Web-API die GrantAccess-Aktion. Weitere Informationen: GrantAccess-Beispiel

Wenn Sie die Zugriffsrechte ändern möchten, die Sie beim Teilen eines Datensatzes gewähren, verwenden Sie die ModifyAccess-Nachricht. Verwenden Sie beim SDK die ModifyAccessRequest-Klasse und bei der Web-API die ModifyAccess-Aktion. Weitere Informationen: ModifyAccess-Beispiel

Um die Freigabe eines Datensatzes rückgängig zu machen, verwenden Sie RevokeAccess-Nachricht. Verwenden Sie beim SDK die RevokeAccessRequest-Klasse und bei der Web-API die RevokeAccess-Aktion. Weitere Informationen: Zugriff widerrufen

Exportieren von Flows

Wenn ein Flow Teil einer Lösung ist, können Sie ihn exportieren, indem Sie die Lösung, die den Flow enthält, mithilfe der ExportSolution-Nachricht exportieren.

Die folgende statische ExportSolution Beispielmethode verwendet ExportSolutionRequest, um eine byte[] ZIP-Datei der nicht verwalteten Lösung mit dem angegebenen UniqueName abzurufen.

/// <summary>
/// Exports an unmanaged solution
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
/// <param name="solutionUniqueName">The uniquename of the solution.</param>
/// <returns></returns>
public static byte[] ExportSolution(
   IOrganizationService service, 
   string solutionUniqueName) 
{
   ExportSolutionRequest request = new() { 
         SolutionName = solutionUniqueName,
         Managed = false
   };

   var response = (ExportSolutionResponse)service.Execute(request);

   return response.ExportSolutionFile;
}

Importieren von Flows

Wenn Sie über eine Lösungs-ZIP-Datei verfügen, können Sie diese mit ImportSolution-Meldung importieren.

Wenn Sie Flows importieren, sollten Sie die folgenden Parameter festlegen:

Name der Eigenschaft 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.
CustomizationFile Eine Base-64-codierte ZIP-Datei, die die Lösung enthält.

Die statische ImportSolution Beispielmethode zeigt, wie Sie eine Lösungsdatei mithilfe der ImportSolutionRequest-Klasse importieren

/// <summary>
/// Imports a solution.
/// </summary>
/// <param name="service">Authenticated client implementing the IOrganizationService interface</param>
/// <param name="solutionFile">The byte[] data representing a solution file. </param>
public static void ImportSolution(
   IOrganizationService service, 
   byte[] solutionFile) {

   ImportSolutionRequest request = new() { 
         OverwriteUnmanagedCustomizations = true,
         CustomizationFile = solutionFile
   };

   service.Execute(request);
}

Häufig gestellte Fragen

Was ist mit der API unter api.flow.microsoft.com?

Die API unter api.flow.microsoft.com wird nicht unterstützt. Kunden sollten stattdessen die Dataverse Web-APIs für Power Automate verwenden, die zuvor in diesem Artikel dokumentiert wurden.

Alternativ können Kunden die Management-Konnektoren verwenden: Power Automate-Verwaltung oder Power Automate für Administratoren.

Kunden können die nicht unterstützten APIs auf api.flow.microsoft.com eigenes Risiko verwenden. Diese APIs können sich ändern, sodass es zu Breaking Changes kommen kann.

Entitätsklassen-Operationen unter Verwendung des Dienstes „.Organisation“
Vorgänge mithilfe der Web-API ausführen
Freigeben und Zuweisen
Zugriff im Code verifizieren
Lösungen mit dem Dataverse-SDK verwenden