Integrare Power Automate con siti Web e app

Incorpora Power Automate nell'app o nel sito Web usando i widget di flow per offrire agli utenti un modo semplice per automatizzare le attività personali o professionali.

I widget di Flow sono iframe che si trovano in un documento host. Questo documento punta a una pagina nella finestra di progettazione di Power Automate. Questi widget integrano la funzionalità specifica di Power Automate nell'applicazione di terze parti.

I widget possono essere semplici. Ad esempio, un widget che esegue il rendering di un elenco di modelli senza alcuna comunicazione tra host e iframe. I widget possono essere anche complessi. Ad esempio, un widget che effettua il provisioning di un flusso cloud da un modello e quindi attiva il flusso tramite una comunicazione bidirezionale tra host e widget.

Prerequisiti

• Un account Microsoft oppure
• Un account aziendale o dell'istituto di istruzione

Usare il widget non autenticato

Per usare il widget dei modelli non autenticati, incorporalo direttamente nell'applicazione host usando un iframe. Non è necessario l'SDK JS o un token di accesso.

Visualizzare i modelli per gli scenari

Per iniziare, aggiungere il codice seguente per visualizzare i modelli di Power Automate nel sito Web:

<iframe src="https://flow.microsoft.com/{locale}/widgets/templates/?q={search term}
&pagesize={number of templates}&destination={destination}&category={category}"></iframe>

Se il parametro di destinazione è new, la finestra di progettazione di Power Automate viene aperta quando gli utenti selezionano un modello. Gli utenti possono quindi creare un flusso cloud nella finestra di progettazione. Per l'esperienza completa del widget, vedi la sezione successiva.

Passaggio di parametri aggiuntivi al modello di flusso

Se l'utente è in un contesto specifico nel sito Web o nell'app, è possibile passare il contesto al flusso. Ad esempio, un utente potrebbe aprire un modello per Quando viene creato un elemento mentre osserva un determinato elenco in SharePoint. Per passare l'ID elenco come parametro al flusso, segui questa procedura:

1. Definisci il parametro nel modello di flusso prima della pubblicazione. Un parametro è simile a @{parameters('parameter_name')}.
2. Passa il parametro nella stringa di query dell'iframe src. Ad esempio, aggiungi &parameters.listName={the name of the list} se hai un parametro denominato listName.

Esempio completo

Per visualizzare i primi quattro modelli SharePoint in tedesco e per consentire all'utente di iniziare a usare myCoolList, usa questo codice:

<iframe src="https://flow.microsoft.com/de-de/widgets/templates/?q=sharepoint%20&pagesize=4&destination=details&parameters.listName=myCoolList"></iframe>

Usare i widget di Flow autenticati

La tabella seguente mostra l'elenco dei widget di Power Automate che supportano l'esperienza completa all'interno del widget tramite il token di accesso dell'autenticazione utente. Sarà necessario usare il Software Developer Kit Javascript (SDK JS) di Power Automate per incorporare i widget e fornire il token di accesso utente necessario.

Usa l'SDK di Flow autenticato per consentire agli utenti di creare e gestire flussi direttamente dal sito Web o dall'app senza passare a Power Automate. Per usare l'SDK autenticato, l'utente dovrà accedere con l'account Microsoft o Azure Active Directory.

Architettura dei widget

I widget di Power Automate incorporano un iframe che fa riferimento a Power Automate in un'applicazione host. L'host fornisce il token di accesso richiesto dal widget di Power Automate. L'SDK JS di Power Automate consente all'applicazione host di inizializzare e gestire il ciclo di vita del widget.

Dettagli dell'SDK JS

Il team di Power Automate fornisce l'SDK JS per facilitare l'integrazione dei widget di Flow nelle applicazioni di terze parti. L'SDK JS di Flow è disponibile come collegamento pubblico nel servizio Flow e consente all'applicazione host di gestire gli eventi dal widget e di interagire con l'applicazione Flow inviando azioni al widget. Gli eventi e le azioni dei widget sono specifiche del tipo di widget.

Inizializzazione dei widget

Prima di inizializzare il widget è necessario aggiungere il riferimento all'SDK JS di Flow all'applicazione host.

<script src="https://flow.microsoft.com/Content/msflowsdk-1.1.js"></script>

Crea un'istanza dell'SDK JS passando il nome host facoltativo e i valori delle impostazioni locali in un oggetto JSON.

var sdk = new MsFlowSdk({
    hostName:'https://flow.microsoft.com',
    locale:'en-US'
}); 

Dopo aver creato l'istanza dell'SDK JS puoi inizializzare e incorporare un widget di Power Automate in un elemento padre nell'applicazione host. Per eseguire queste operazioni, aggiungi un tag div HTML:

<div id="flowDiv" class="flowContainer"></div>

Quindi inizializza il widget Power Automate con il metodo renderWidget() dell'SDK JS. Assicurati di specificare il tipo di widget e le impostazioni corrispondenti.

var widget = sdk.renderWidget('<widgettype>', {
        container: 'flowDiv',
        flowsSettings: {},
        templatesSettings: {},
        approvalCenterSettings: {},
        widgetStyleSettings: {}
});

Di seguito è riportato uno stile di esempio per il contenitore che è possibile modificare per adattarlo alle dimensioni dell'applicazione host.

<head>
    <style>
        .flowContainer iframe {
            width: 400px;
            height: 1000px;
            border: none;
            overflow: hidden;
    }
    </style>
</head>

Di seguito sono elencati i parametri per renderWidget():

Token di accesso

Dopo l'esecuzione di renderWidget() dell'SDK JS, l'SDK JS inizializza un iframe che punta all'URL del widget di Power Automate. Questo URL contiene tutte le impostazioni nei parametri della stringa di query. L'applicazione host deve ricevere un token di accesso di Power Automate per l'utente (token JWT di Azure Active Directory con destinatari https://service.flow.microsoft.com) prima di inizializzare il widget. Il widget genera un evento GET_ACCESS_TOKEN per richiedere un token di accesso proveniente dall'host. L'host deve gestire l'evento e passare il token al widget:

widget.listen("GET_ACCESS_TOKEN", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
        token:  '<accesstokenFromHost>'
    });
});

L'applicazione host è responsabile della gestione del token e del passaggio del token con una data di scadenza valida al widget quando necessario. Se il widget è aperto per lunghi periodi, l'host deve verificare se il token è scaduto e, se necessario, aggiornare il token prima di passarlo al widget.

Rilevare se il widget è pronto

Dopo l'inizializzazione, il widget genera un evento per notificare che il widget è pronto. L'host può rimanere in ascolto dell'evento WIDGET_READY ed eseguire qualsiasi codice host aggiuntivo.

widget.listen("WIDGET_READY", function() {
    console.log("The flow widget is now ready.");
    // other host code on widget ready
});

Impostazioni del widget

FlowsSettings

FlowsSettings consente di personalizzare la funzionalità del widget di Power Automate.

flowsSettings?: {
    createFromBlankTemplateId?: string;
    flowsFilter?: string;sc
    tab?: string;
};

TemplatesSettings

Questa impostazione si applica a tutti i widget che consentono di creare flussi basati su un modello, inclusi i widget dei flussi, di creazione flussi e dei modelli.

templatesSettings?: {
    defaultParams?: any;
    destination?: string;
    pageSize?: number;
    searchTerm?: string;
    templateCategory?: string;
    useServerSideProvisioning?: boolean;
    enableDietDesigner?: boolean;
};

ApprovalCenterSettings

Si applica ai widget del centro approvazioni.

approvalCenterSettings?: {
   approvalsFilter?: string;
   tab?: string;but
   showSimpleEmptyPage? boolean;
   hideLink?: boolean
};

Eventi del widget

Il widget di Power Automate supporta gli eventi che consentono all'host di essere in ascolto degli eventi del ciclo di vita del widget. Il widget di Power Automate supporta due tipi di eventi: eventi di notifica unidirezionale (ad esempio, Widget_Ready) ed eventi generati dal widget per recuperare i dati dall'host (Get_Access_Token). L'host deve usare il metodo widget.listen() per essere in ascolto di determinati eventi generati dal widget.

Utilizzo

widget.listen("<WIDGET_EVENT>", function() {
    console.log("The flow widget raised event");
});

Eventi supportati dal tipo di widget

Widget di runtime

Widget di creazione flussi

Widget di approvazione

L'evento GET_STRINGS consente di personalizzare il testo per alcuni elementi dell'interfaccia utente visualizzati nel widget. È possibile personalizzare le stringhe seguenti:

Esempio

Chiama widgetDoneCallback passando un oggetto JSON con coppie chiave-valore della chiave della stringa e un testo per sostituire il valore predefinito.

widget.listen("GET_STRINGS", function(requestParam, widgetDoneCallback) {
    widgetDoneCallback(null, {
         "FLOW_CREATION_HEADER": "<string override would go here>",
        "INVOKE_FLOW_RUN_FLOW_BUTTON":  "<string override would go here>"
    });
});

Azioni del widget

L'host usa le azioni del widget per inviare un'azione o un messaggio specifico al widget. L'SDK JS del widget fornisce il metodo notify() per inviare un messaggio o un payload JSON al widget. Ogni azione del widget supporta una firma di payload specifica.

Utilizzo

widget.notify('<WIDGET_ACTION>', parameterMatchingParameterInterface)
    .then(result => console.log(result))
    .catch(error => console.log(error))

Esempio

Richiamare un flusso cloud inviando il comando seguente a un widget di runtime

widget.notify('triggerFlow', { flowName: flowName, implicitData:implicitData });  

Widget di runtime

Widget di creazione flussi

Widget di approvazione

Configurazione dell'applicazione client

È necessario configurare l'applicazione client con gli ambiti di servizio di Flow (autorizzazioni delegate). Se l'app di Azure Active Directory (AAD) usata per l'integrazione del widget usa un flusso di autorizzazione 'concessione del codice', l'app AAD deve essere preconfigurata con le autorizzazioni delegate supportate da Power Automate. In questo modo vengono concesse le autorizzazioni delegate che consentono all'applicazione di:

• Gestire le approvazioni
• Leggere le approvazioni
• Leggere le attività
• Gestire i flussi
• Leggere i flussi

Per selezionare una o più autorizzazioni delegate, segui questa procedura:

1. Vai a https://portal.azure.com
2. Selezionare Azure Active Directory.
3. Seleziona Registrazioni app in Gestisci.
4. Specifica l'applicazione di terze parti da configurare per gli ambiti di servizio di Flow.
5. Seleziona Impostazioni.
6. Seleziona Autorizzazioni necessarie in Accesso all'API/
7. Seleziona Aggiungi.
8. Scegli Selezionare un'API.
9. Cerca servizio Power Automate e selezionalo. Nota: per poter visualizzare il servizio Power Automate, è necessario che il tenant abbia almeno un utente AAD che ha eseguito l'accesso al portale di Flow (https://flow.microsoft.com)
10. Scegli gli ambiti di Flow necessari per l'applicazione e quindi seleziona Salva.

L'applicazione otterrà un token del servizio Flow che contiene le autorizzazioni delegate nell'attestazione 'scp' nel token JWT.

Applicazione di esempio con incorporamento di widget di Flow

Nella sezione delle risorse è disponibile un'applicazione a pagina singola JavaScript di esempio che è possibile usare per provare a incorporare widget di Flow in una pagina host. Per usare l'applicazione di esempio è necessario registrare un'applicazione AAD con il flusso di concessione implicita abilitato.

Registrazione di un'app AAD

1. Accedi al portale di Azure.
2. Nel riquadro di spostamento a sinistra seleziona Azure Active Directory, quindi Registrazioni app (Anteprima) > Nuova registrazione.
3. Quando viene visualizzata la pagina Registra un'applicazione, immetti un nome per l'applicazione.
4. In Tipi di account supportati seleziona Account in una directory dell'organizzazione.
5. Nella sezione URL di reindirizzamento seleziona la piattaforma Web e imposta il valore sull'URL dell'applicazione in base al server Web. Imposta questo valore su http://localhost:30662/ per eseguire l'app di esempio.
6. Seleziona Registra.
7. Nella pagina Panoramica dell'app prendi nota del valore di ID applicazione (client).
8. Per l'esempio è necessario abilitare il flusso di concessione implicita. Nel riquadro di spostamento di sinistra dell'applicazione registrata seleziona Autenticazione.
9. In Impostazioni avanzate in Concessione implicita seleziona le caselle di controllo Token ID e Token di accesso. Token ID e token di accesso devono essere specificati poiché l'app esegue l'accesso degli utenti e chiama l'API di Flow.
10. Seleziona Salva.

Esecuzione dell'esempio

1. Scarica l'esempio e copialo in una cartella locale nel dispositivo.
2. Apri il file index.htmlnella cartella FlowSDKSample e modifica applicationConfig per aggiornare clientID all'ID applicazione registrato in precedenza.
3. L'app di esempio è configurata per l'uso degli ambiti di Flow Flows.Read.All e Flow.Manage.All. È possibile configurare altri ambiti aggiornando la proprietà flowScopes nell'oggetto applicationConfig.
4. Esegui questi comandi per installare la dipendenza ed eseguire l'app di esempio:

   > npm install > node server.js

5. Apri il browser e immetti http://localhost:30662
6. Selezionare il pulsante Accedi per eseguire l'autenticazione in AAD e acquisire un token di accesso del flusso cloud.
7. La casella di testo Token di accesso contiene il token di accesso.
8. Seleziona il widget di caricamento flussi o il widget di caricamento modelli per incorporare i widget corrispondenti.

Collegamento per il download dell'applicazione di esempio.

risorse

Pagine di test dei widget

Sono disponibili altre informazioni sull'integrazione e sulle impostazioni dei widget:

• Widget di modelli: <https://flow.microsoft.com/test/templateswidget/>
• Widget di creazione flussi: <https://flow.microsoft.com/test/flowcreationwidget/>
• Widget di runtime: <https://flow.microsoft.com/test/runtimewidget/>
• Widget del centro approvazioni: <https://flow.microsoft.com/test/approvalcenterwidget/>
• Widget dei flussi: <https://flow.microsoft.com/test/managewidget/>

Impostazioni locali dei widget supportate

Se le impostazioni locali inizializzate non sono elencate, Flow usa per impostazione predefinita le impostazioni locali supportate più vicine.

Uso dell'SDK Power Automate Embed è coperto dalle Condizioni di licenza software Microsoft.