Utilizzare i flussi cloud con il codice

  • Articolo

Tutti i flussi sono memorizzati in Dataverse e puoi usare sia l'SDK Dataverse per .NET o API Web per gestirli.

Questo articolo illustra la gestione dei flussi inclusi nella scheda Soluzioni in Power Automate. Attualmente, la gestione dei flussi in Flussi personali non sono supportati con codice.

Interagire con API Dataverse

Dataverse fornisce funzionalità equivalenti utilizzando l'SDK Dataverse per .NET o API Web.

Quale metodo è opportuno usare?

Il metodo migliore dipende dalla tecnologia del progetto e dalle competenze che possiedi.

Se il tuo progetto usa .NET, ti consigliamo di usare l'SDK. L'SDK semplifica l'esperienza di sviluppo fornendo un modello a oggetti tipizzato e metodi per l'autenticazione.

Maggiori informazioni: Utilizza il servizio Organizzazione

Istruzioni per la connessione

La modalità di connessione dipende dal fatto che tu stia utilizzando l'SDK Dataverse per .NET o API Web.

Con l'SDK, devi connetterti a un'applicazione client per ottenere l'accesso a un'istanza IOrganizationService. IOrganizationService è un'interfaccia che fornisce metodi con cui è possibile interagire con Dataverse.

Ulteriori informazioni:

Tabella flusso di lavoro

I flussi cloud sono memorizzati nella tabella Processo (flusso di lavoro) rappresentata nell'API Web come EntityType del flusso di lavoro

Nella tabella seguente vengono descritti le colonne importanti della tabella del flusso di lavoro:

Nome logico Type Description
category Choice Categoria del flusso. Ecco le diverse categorie.
0: flussi di lavoro Dataverse classici.
1: finestre di dialogo di Dataverse classiche.
2: regole di business.
3: azioni di Dataverse classiche.
4: processi aziendali.
5: flusso moderno (flussi automatizzati, istantanei o pianificati).
6: flussi desktop.
clientdata String Un JSON codificato come stringa della definizione del flusso e i relativi connectionReferences.
createdby Cerca Utente che ha creato il flusso.
createdon Data/Ora Data di creazione del flusso.
description String Descrizione del flusso fornita dall'utente.
ismanaged Bool Indica se il flusso è stato installato tramite una soluzione gestita.
modifiedby Cerca Ultimo utente che ha aggiornato il flusso.
modifiedon Data/Ora Ora dell'ultimo aggiornamento del flusso.
name String Nome visualizzato assegnato al flusso.
ownerid Cerca L'utente o il team a cui appartiene il flusso.
statecode Choice Stato del flusso. Lo stato può essere:
0: bozza (Off)
1: Attivato (On)
2: sospeso.
type Choice Indica se il flusso è in esecuzione o è un modello che può essere usato per creare più flussi.
1: definizione,
2: attivazione
3: modello.
workflowid GUID Identificatore univoco per un flusso cloud tra tutte le importazioni.
workflowidunique GUID Identificatore univoco per l'installazione del flusso.

Nota

Con l'API Web, i valori di ricerca sono proprietà di navigazione a valore singolo che possono essere espanse per ottenere dettagli dal record correlato.

Le colonne di ricerca hanno anche proprietà di ricerca GUID corrispondenti che possono essere utilizzate nelle query. Le proprietà di ricerca hanno questa convenzione di denominazione: _<logical name>_value. Per entitytype del flusso di lavoro nell'API Web puoi fare riferimento a queste proprietà di ricerca: _createdby_value, _modifiedby_value e _ownerid_value.

Elenca flussi

Per recuperare un elenco di flussi cloud, puoi eseguire una query sulla tabella del flusso di lavoro. La seguente query restituisce i primi flussi automatizzati, istantanei o pianificati attualmente attivi:

Questo metodo OutputFirstActiveFlow statico richiede un client autenticato che implementi IOrganizationService. Utilizza il metodo IOrganizationService.RetrieveMultiple.

/// <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"]}");
}

Per recuperare più record, rimuovi il limite 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

Ulteriori informazioni:

Creare un flusso cloud

Le proprietà richieste per i flussi automatizzati, immediati e pianificati sono: category, name, type, primaryentity e clientdata. Usa none per la proprietà primaryentity per questi tipi di flussi.

Questo metodo statico richiede un client autenticato che implementi IOrganizationService. Utilizza il metodo IOrganizationService.Create.

/// <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);
}

Ulteriori informazioni: Crea righe di tabella utilizzando il servizio Organizzazione

statecode di tutti i flussi creati in questo modo sono impostati su 0 (Bozza o Disattivato). Il flusso deve essere abilitato prima di poter essere utilizzato.

La proprietà più importante è clientdata, che contiene connectionReferences usati dal flusso e la definizione del flusso. I connectionReferences sono i mapping per ogni connessione usata dal flusso.

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

Agggiornare un flusso cloud

Per aggiornare un flusso, imposta solo le proprietà che desideri modificare.

Questo metodo statico richiede un client autenticato che implementi IOrganizationService. Utilizza il metodo IOrganizationService.Update per aggiornare una descrizione del flusso e impostare il proprietario.

/// <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);
}

Ulteriori informazioni: Aggiorna ed elimina le righe della tabella utilizzando il servizio di organizzazione > Aggiornamento di base

Eliminare un flusso cloud

Gli esempi seguenti mostrano come eliminare il record del flusso di lavoro che rappresenta un flusso cloud.

Il metodo statico DeleteCloudFlow elimina un record del flusso di lavoro.

/// <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);

}

Altre informazioni: Eliminare un record usando l'SDK

Recuperare tutti gli utenti con cui è stato condiviso un flusso cloud

Utilizza il messaggio RetrieveSharedPrincipalsAndAccess per ottenere un elenco di tutti gli utenti con cui è condiviso un flusso cloud.

Con l'SDK, utilizza RetrieveSharedPrincipalsAndAccessRequest Class e con l'API Web utilizza RetrieveSharedPrincipalsAndAccess Function.

Ulteriori informazioni: Ottieni entità di sicurezza con accesso a un record

Condividere un flusso cloud o annullarne la condivisione

Condividi un flusso cloud come qualsiasi altro record Dataverse utilizzando il messaggio GrantAccess. Con l'SDK, utilizza la classe GrantAccessRequest e con l'API Web utilizza l'azione GrantAccess. Ulteriori informazioni: Esempio GrantAccess

Se desideri modificare i diritti di accesso che concedi quando condividi un record, utilizza il messaggio ModifyAccess. Con l'SDK, utilizza la classe ModifyAccessRequest e con l'API Web utilizza l'azione ModifyAccess. Ulteriori informazioni: Esempio ModifyAccess

Per annullare la condivisione di un record, utilizza il messaggio RevokeAccess. Con l'SDK, utilizza la classe RevokeAccessRequest e con l'API Web utilizza l'azione RevokeAccess. Altre informazioni: Revoca accesso

Esportare flussi

Quando un flusso fa parte di una soluzione, puoi esportarlo esportando la soluzione che contiene il flusso utilizzando il messaggio ExportSolution.

Il ExportSolution metodo di esempio statico seguente utilizza ExportSolutionRequest per recuperare un byte[] contenente il file ZIP della soluzione non gestita con l'oggetto UniqueName specificato.

/// <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;
}

Importare flussi

Quando disponi di un file ZIP della soluzione, puoi importarlo utilizzando il messaggio ImportSolution.

Quando importi i flussi, devi impostare i seguenti parametri:

Nome proprietà Description
OverwriteUnmanagedCustomizations Se sono presenti istanze esistenti di questi flussi in Dataverse, questo flag deve essere impostato su true per importarli. In caso contrario, non verranno sovrascritti.
PublishWorkflows Indica se i flussi classici di Dataverse verranno attivati al momento dell'importazione. Questa impostazione non si applica ad altri tipi di flussi.
CustomizationFile File ZIP con codifica in base 64 che contiene la soluzione.

Il metodo statico ImportSolution di esempio mostra come importare un file di soluzione utilizzando la classe ImportSolutionRequest

/// <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);
}

Vedi anche

Operazioni di classi di entità che utilizzano il servizio Organizzazione
Eseguire operazioni utilizzando l'API Web
Condivisione e assegnazione
Verifica dell'accesso nel codice
Utilizzare soluzioni tramite SDK Dataverse