Uso dell'estensione per gli elenchi di valori dinamici
Quando si imposta un parametro per un'azione in un connettore personalizzato, l'esperienza predefinita per il creatore consiste nell'immettere il valore del parametro in una casella di testo semplice. Se in un'azione Aggiungi fattura si dispone di un parametro denominato ID del tipo di fattura, l'esperienza del creatore risulta simile all'immagine seguente.
È necessario che il creatore conosca i valori corretti per il campo Invoice Type ID che, per questo esempio, sono i seguenti.
| Valore | Etichetta |
|---|---|
| 1 | Purchase Order |
| 2 | Non ordine di acquisto |
Un creatore deve immettere 1 per indicare che la fattura è di tipo Ordine di acquisto. Per rendere più semplice la definizione di OpenAPI, è consigliabile supportare la parola chiave di enumerazione. È possibile definire un'enumerazione con un elenco di valori tra cui il creatore può scegliere.
È possibile configurare un'enumerazione tramite la finestra di progettazione del connettore personalizzato, modificando la configurazione del parametro. Se nella configurazione si seleziona Statico nell'area Tipo di elenco a discesa, sarà possibile specificare un elenco di valori separati da virgole. Lo screenshot seguente mostra l'aspetto della configurazione di ID del tipo di fattura.
È anche possibile usare l'editor Swagger e aggiungere l'enumerazione, come mostrato nell'immagine seguente.
Inoltre, l'esperienza del creatore in Power Automate risulta ora simile all'immagine seguente.
Sebbene l'esperienza sia migliorata, è comunque necessario che il creatore conosca il significato del valore 1 o 2. È possibile descrivere il significato di quei valori nella descrizione del parametro per rendere il processo più semplice per i creatori. L'uso delle enumerazioni è la soluzione migliore per i dati auto-descrittivi. Ad esempio, nel caso di un parametro per Giorni alla scadenza, un'enumerazione 30,60,90 sarebbe semplice da comprendere e usare. Un'altra limitazione correlata all'uso dell'enumerazione è relativa all'uso di un'API che aggiunge nuovi valori consentiti: in tal caso è necessario modificare la definizione dell'enumerazione del connettore personalizzato e pubblicare la versione aggiornata del connettore. Per migliorare ulteriormente l'esperienza, Microsoft ha aggiunto l'estensione OpenAPI x-ms-dynamic-values.
Configurazione di valori dinamici
È possibile configurare l'estensione x-ms-dynamic-values su un parametro per recuperare l'elenco di valori dall'API sottostante.
Questo approccio offre i vantaggi seguenti:
È possibile configurare un'etichetta che l'utente vede oltre al valore.
I valori restituiti rappresentano sempre i valori corretti dall'API.
L'API può tagliare l'elenco di valori in base alla sicurezza o ad altre esigenze, a seconda dell'utente o della connessione.
È possibile passare all'API altri valori del parametro per poter filtrare l'elenco restituito.
L'output di un campo può essere usato come parametro di input per un'altra chiamata API, rendendo possibile la creazione di opzioni dipendenti, come elenchi di paesi/aree geografiche e stati.
L'API usata deve fornire un'operazione che restituisca una matrice di valori validi e, facoltativamente, le relative descrizioni. A supporto dell'esempio precedente per ID del tipo di fattura, l'API ha fornito un'operazione ListInvoiceTypes che ha restituito i dati seguenti.
Nella finestra di progettazione del connettore personalizzato per il parametro ID del tipo di fattura è possibile configurare l'estensione x-ms-dynamic-values selezionando Dinamico e quindi specificando un valore in ID operazione, Valore e Nome visualizzato del valore. Lo screenshot seguente mostra la configurazione di ID del tipo di fattura.
È anche possibile configurare l'estensione x-ms-dynamic-values usando l'editor Swagger.
È necessario usare l'editor Swagger o eseguire il download e la modifica del file JSON se si configurano i parametri sull'estensione.
Dopo aver configurato l'estensione, al creatore viene presentata un'esperienza più semplice quando usa l'azione.
Oltre all'estensione x-ms-dynamic-values, Microsoft ha anche implementato una nuova estensione denominata x-ms-dynamic-list. In teoria, entrambe hanno lo stesso obiettivo di trasformare il parametro dell'azione in un elenco a discesa in cui l'utente può effettuare una selezione. Si consideri l'estensione x-ms-dynamic-values come versione 1 e l'estensione x-ms-dynamic-list come versione 2. Se è previsto il supporto di flussi esistenti precedenti, è consigliabile implementarli entrambi nella definizione. Se è previsto solo il supporto di nuovi flussi, usare esclusivamente x-ms-dynamic-list. L'estensione x-ms-dynamic-list migliora lo schema per i parametri di azione, consentendo di risolvere alcuni riferimenti ambigui. Se ad esempio una richiesta presenta un ID parametro di percorso e un ID parametro come parte del corpo della richiesta, la specifica x-ms-dynamic-list consente di distinguere i due parametri, mentre x-ms-dynamic-values non è in grado di supportare questa API.
Per configurare l'estensione x-ms-dynamic-list, è necessario modificare direttamente la definizione OpenAPI perché la finestra di progettazione del connettore personalizzato configura solo x-ms-dynamic-values. L'immagine seguente mostra la configurazione di x-ms-dynamic-values che ha anche aggiunto una configurazione di x-ms-dynamic-list.
La configurazione di valori dinamici sui parametri per un connettore personalizzato può rendere quest'ultimo più semplice da usare per i creatori.