Uso dello schema dinamico
Quando si configura un'azione su un connettore personalizzato, è anche possibile configurare i parametri. Questi parametri vengono configurati importando una definizione OpenAPI o una richiesta di esempio. Indipendentemente dall'approccio adottato, l'elenco dei parametri è fisso. Quando viene utilizzata tale azione, al creatore verrà presentato l'elenco statico di parametri come definito dal connettore. Per molti scenari, questo approccio è appropriato perché i parametri dell'elenco sono fissi e non variano. In alcuni casi, i parametri che dovrebbero essere presentati per l'input sono variabili.
I casi d'uso più comuni sono:
L'elenco dei parametri varia in base a un tipo, ad esempio una categoria o un tipo di fattura.
Lo stato del record potrebbe determinare quali parametri possono essere modificati. Ad esempio, un ordine spedito potrebbe avere parametri disponibili diversi rispetto a un ordine non spedito.
L'elenco dei parametri potrebbe essere tagliato dalla sicurezza.
Un'implementazione di un'azione comune su alcuni tipi di dati diversi. Ad esempio, l'API potrebbe implementare un'azione Crea che si applica ad account, contatti, ordini o fatture. I parametri di input saranno definiti dal tipo di oggetto selezionato dal creatore.
I connettori personalizzati supportano questi scenari consentendo di configurare le estensioni OpenAPI dello schema dinamico. Quando le estensioni OpenAPI dello schema dinamico sono configurate, il runtime del connettore personalizzato chiamerà un'operazione per recuperare lo schema che definisce quali parametri devono essere visibili per quella determinata azione. I dati dello schema possono includere altre opzioni come il nome visualizzato e la descrizione del parametro.
Nell'esempio dell'API Contoso Invoicing, dopo l'importazione della definizione OpenAPI, l'aspetto dell'azione era simile all'immagine seguente quando la si usava in un flusso di Power Automate.
L'immagine precedente mostra parametri che non sono pertinenti per l'aggiunta di una fattura di un ordine fornitore rispetto a una fattura non di un ordine fornitore. Inoltre, non tutti i campi della fattura sono input validi per la creazione della fattura. Ad esempio, createDate è un campo impostato dall'API e non deve far parte dell'input utente. Dopo aver implementato i valori dinamici per l'ID del tipo di fattura e lo schema dinamico per gli altri parametri, l'azione sarà simile all'immagine seguente.
Quando il creatore cambia il tipo di fattura da ordine fornitore a non ordine fornitore, il parametro Ordine fornitore viene nascosto o mostrato come appropriato.
Il runtime del connettore personalizzato supporta due diverse estensioni che possono essere usate per configurare lo schema dinamico. Entrambe svolgono lo stesso compito, dove l'estensione x-ms-dynamic-schema è la versione 1 e x-ms-dynamic-properties è la versione 2. Se è necessario supportare i flussi precedenti utilizzando la propria azione, è possibile configurare entrambe le versioni sul connettore personalizzato. Se sono supportati solo i nuovi flussi, è possibile configurare solo l'estensione x-ms-dynamic-properties.
Supporto dell'API
Per poter configurare lo schema dinamico, l'API sottostante deve fornire supporto definendo l'operazione che restituisce lo schema. Se l'API non dispone già di un'azione adatta e non si ha la possibilità di modificare l'API o richiedere le modifiche, si potrebbe non essere in grado di implementare lo schema dinamico.
L'operazione che restituisce lo schema può accettare uno o più parametri passati dal runtime del connettore personalizzato. Questi parametri possono essere costanti o rappresentare altri dati raccolti sulla scheda azione. Tali dati possono essere usati dall'API per filtrare l'elenco dei parametri restituiti come parte dello schema. Nell'esempio precedente, Tipo di fattura viene passato come parametro all'operazione per ottenere lo schema dinamico.
La risposta dall'operazione usata per lo schema dinamico deve essere uno schema JSON valido. L'esempio seguente mostra il valore restituito da GetInvoiceSchema dell'API Contoso.
Prendere nota dei seguenti punti chiave relativi al contenuto:
Il tipo deve essere specificato e viene usato per identificare il tipo di dati del parametro.
Il riepilogo e la descrizione vengono usati nella finestra di progettazione di Power Automate per identificare i parametri per il creatore.
La proprietà dell'estensione x-ms-visibility può essere specificata per indicare in quale punto questo parametro dovrà essere sempre visualizzato (valore "importante") o se è necessaria un'azione utente affinché sia reso visibile al creatore, quale seleziona collegamento avanzato su una scheda di flusso (valore "avanzato"). Poiché queste informazioni vengono recuperate dinamicamente, possono variare a seconda delle informazioni di contesto disponibili.
La matrice richiesta fornisce l'elenco dei parametri obbligatori.
Configurazione dell'estensione dello schema dinamico
Per configurare le estensioni x-ms-dynamic-schema o x-ms-dynamic-properties, è necessario modificare direttamente la definizione OpenAPI del connettore personalizzato. Attualmente, il supporto per la finestra di progettazione dei connettori personalizzati non è disponibile per la modifica di questi valori.
L'immagine seguente mostra l'aspetto della configurazione del parametro AddInvoice dopo l'importazione della definizione OpenAPI fornita dall'API.
L'esempio precedente mostra che AddInvoice accetta un oggetto CreateInvoiceRequest come input. Le proprietà sono definite da un riferimento #/definitions/Invoice, che è una definizione condivisa di tutte le proprietà della fattura.
Per implementare la chiamata all'estensione dello schema dinamico, è possibile sostituire le proprietà con l'estensione configurata.
Anziché avere un elenco di proprietà hardcoded, verrà chiamata l'operazione GetInvoiceSchema per recuperare l'elenco in base al parametro typeId.
L'implementazione dello schema dinamico sul connettore personalizzato permette di far conoscere al creatore quali parametri devono essere utilizzati per l'azione.