Introduzione
I connettori personalizzati di Microsoft Power Platform usano le definizioni OpenAPI (noto anche come Swagger) per descrivere l'autenticazione, le azioni, i trigger e i relativi parametri. La specifica OpenAPI consente di definire delle estensioni che ampliano la definizione principale per gestire scenari specifici. Microsoft ha creato diverse estensioni per la definizione OpenAPI per consentire di configurare funzionalità specifiche supportate dai connettori personalizzati.
Per individuare queste estensioni, cercare x-ms-<name> nelle definizioni OpenAPI. Probabilmente alcune di queste definizioni sono state già usate durante la configurazione di un connettore personalizzato nella finestra di progettazione, ad esempio per inserire un riepilogo sul parametro di un'azione che usa l'estensione x-ms-summary per archiviare il valore nella definizione. Diverse estensioni possono essere modificate solo aprendole direttamente con l'editor Swagger della finestra di progettazione oppure esportando le definizioni del connettore, modificandole e importandole nuovamente. Qui è disponibile un elenco completo delle estensioni supportate per il connettore personalizzato.
Questo modulo descrive le seguenti estensioni e spiega come usarle:
x-ms-capabilities: usata nel connettore e nella definizione a livello dell'operazione per indicare le funzionalità offerte.
x-ms-encoding: specifica la codifica per un parametro di percorso.
x-ms-dynamic-values e x-ms-dynamic-list: forniscono un elenco di opzioni che l'utente può usare per selezionare i parametri di input per un'operazione.
x-ms-dynamic-schema: consente di rendere dinamici i parametri e la risposta in base ai risultati dello schema recuperato da un'operazione sull'API.
Il caso d'uso principale per la configurazione di queste estensioni è semplificare l'uso del connettore. Ad esempio, senza valori dinamici i creatori dovrebbero conoscere valori di schema interni o stringhe non descrittive per i parametri di tipo/ricerca. Configurando i valori dinamici, si fornisce loro un elenco a discesa facile da usare da cui effettuare le selezioni.
Tenere presente che alcune estensioni richiedono anche il supporto dall'API. Ad esempio, lo schema dinamico richiede che l'API supporti un'operazione per recuperare lo schema. Se non si controlla l'API, la configurazione di questi tipi di estensioni potrebbe non essere consentita.
Configurazione delle estensioni
Alcune estensioni OpenAPI sono configurate nella finestra di progettazione mentre si lavora con le definizioni, ma non è il caso delle estensioni trattate in questo modulo. Per configurarle, è necessario usare uno dei seguenti approcci:
Importazione di OpenAPI: un file OpenAPI importato può contenere le estensioni Microsoft OpenAPI.
Interfaccia della riga di comando dei connettori Microsoft Power Platform: con lo strumento da riga di comando paconn, è possibile scaricare il file di definizione dell'API e modificarlo con l'editor JSON preferito. Al termine della modifica, è possibile usare paconn per caricare nuovamente le definizioni modificate nell'ambiente. Questo approccio è da preferire quando si devono apportare altre modifiche al file delle proprietà API per i parametri di connessione, ad esempio.
Microsoft Power Platform CLI: usando lo strumento da riga di comando, è possibile scaricare il file di definizione dell'API per i connettori personalizzati che usano soluzioni e modificarlo con l'editor JSON preferito. Al termine della modifica, è possibile usare l'interfaccia della riga di comando per caricare nuovamente le definizioni modificate nella soluzione. Questo approccio è da preferire quando si devono apportare altre modifiche al file delle proprietà API per i parametri di connessione e il connettore personalizzato si trova in una soluzione.
Editor Swagger predefinito: nella finestra di progettazione dei connettori personalizzati è presente un editor OpenAPI predefinito, che rappresenta il modo più rapido per aggiungere estensioni OpenAPI.
Uso dell'editor Swagger
Per rendere visibile l'editor Swagger, attivare l'interruttore Editor Swagger in un qualsiasi passaggio nella finestra di progettazione personalizzata.
Quando l'editor è attivato, la definizione OpenAPI in YAML Ain't Markup Language (YAML) viene visualizzata a sinistra, mentre i messaggi di convalida (se presenti) e un elenco di operazioni vengono visualizzati a destra.
Per chi non lo conosce, YAML è uno standard per la serializzazione dei dati facile da usare che consente di apportare modifiche al contenuto YAML, salvarlo e passarlo al runtime del connettore.
Per la maggior parte delle modifiche da apportare sarà disponibile un esempio con cui iniziare. Per scoprire quali modifiche sono state apportate in YAML, cercare negli altri connettori nel repository GitHub dei connettori Microsoft Power Platform. Ad esempio, per implementare un'estensione x-ms-capability, è possibile cercare nel repository e vedere come è stata configurata negli altri connettori.
Quando si usa l'editor, è meglio apportare piccole modifiche mirate. L'editor controlla la sintassi durante la digitazione e avvisa in tempo reale se sono stati commessi errori e dove si trovano.
Suggerimenti per lavorare con YAML nell'editor Swagger:
Il rientro è importante: il rientro fa parte delle specifiche YAML, quindi è utile osservare come viene usato per fornire ulteriori specifiche di configurazione.
Parentesi graffe aperte e chiuse {}: se è stata inserita una parentesi graffa aperta {, è necessario inserire anche una parentesi graffa chiusa }.
Parentesi quadre aperte e chiuse []: se è stata inserita una parentesi quadra aperta, deve essercene anche una chiusa.
CTRL + F per Trova: questa scelta rapida da tastiera consente di cercare all'interno di YAML.
CTRL + Z per Annulla: se si commette un errore, è possibile usare la scelta rapida da tastiera CTRL + Z per annullare l'ultima modifica.
Il resto del modulo descriverà come usare alcune estensioni Microsoft OpenAPI per semplificare l'uso dei connettori personalizzati.