Esplorazione delle opzioni di configurazione dei connettori personalizzati
Questa unità continua a presentare le nozioni di base sui connettori personalizzati approfondendo alcune delle opzioni di configurazione disponibili.
Denominazione dei connettori e informazioni generali
Una delle prime decisioni da prendere riguarda il nome del connettore. Il nome deve essere univoco e spiegare il connettore all'utente. Il nome è limitato a 30 caratteri, ma è possibile approfondire ulteriormente nel campo Descrizione. Il campo Colore di sfondo dell'icona può essere utile anche per identificare visivamente il connettore. Questi campi sono importanti perché vengono visualizzati quando l'utente seleziona il connettore da usare e gli indizi visivi aiutano a lavorare in modo più efficiente. Se si prevede di inviare il connettore per la certificazione, assicurarsi di verificare i requisiti più rigorosi nella documentazione Istruzioni per l'invio del connettore a Microsoft.
Denominazione di azioni e trigger
Dopo che un utente ha ristretto la ricerca scegliendo il connettore, selezionerà un'azione o un trigger del connettore da usare. I campi ID operazione, Riepilogo e Descrizione consentono di descrivere ogni azione e trigger. L'ID operazione viene usato internamente, deve essere univoco e non può contenere spazi. L'uso della notazione Camel, ad esempio GetInvoice, favorisce la leggibilità dell'ID se si osserva il markup per trovare la definizione. La mancanza di spazi nei nomi può essere difficile per i creatori che usano utilità per la lettura dello schermo, ma l'uso della notazione Camel rende le definizioni più accessibili.
Il campo Riepilogo è importante perché viene visualizzato nell'elenco delle azioni e dei trigger quando si seleziona quello da usare. È consigliabile usare un testo sufficientemente descrittivo in modo da indicare che cosa fa l'azione o il trigger. Ad esempio, la descrizione dell'azione GetInvoice può essere Ottiene una fattura specifica in base all'ID. Spesso i creatori troveranno l'azione tramite una ricerca e di conseguenza la presenza di nomi descrittivi può aiutarli a trovare rapidamente l'azione più adatta.
L'immagine seguente mostra dove vengono usati gli elementi riepilogo e descrizione quando si seleziona un'azione o un trigger.
Dopo aver selezionato un'azione o un trigger, sarà possibile visualizzare gli elementi riepilogo e descrizione in ogni scheda azione nella finestra di progettazione.
Va notato che, nelle immagini precedenti, i modelli di denominazione non sono coerenti, in quanto in alcuni casi i nomi nel riepilogo contengono spazi e in altri no. È possibile correggere l'errore aggiornando i campi nel portale oppure, se si è proprietari dell'API, è possibile chiedere allo sviluppatore di aggiornare gli elementi forniti nella definizione OpenAPI importata. Tenere presente che se si apportano modifiche manualmente nel portale e quindi si importa di nuovo la definizione OpenAPI, le modifiche verranno sovrascritte.
Visibilità delle azioni
È possibile impostare l'opzione Visibilità in un'azione per determinare il modo in cui l'azione verrà visualizzata nell'esperienza del creatore.
Nessuna - Opzione predefinita. L'azione verrà visualizzata normalmente.
Avanzata - L'azione sarà disponibile, ma non prioritaria.
Interna - L'azione sarà nascosta.
Importante - L'azione avrà la priorità e verrà mostrata per prima.
Ad esempio, se si importa una definizione OpenAPI con 10 azioni e non si vuole che gli utenti ne visualizzino/usino due inizialmente, è possibile selezionare l'opzione Interna per nasconderle. Questo approccio è utile per gestire le operazioni usate per supportare metadati di connettori dinamici. Può anche consentire di nascondere inizialmente le azioni e quindi renderle successivamente visibili quando gli utenti le richiedono. Nascondendo le azioni, è possibile ridurre al minimo l'elenco di quelle visibili agli utenti.
Le azioni selezionate come Importante vengono visualizzate per prime. L'utente deve selezionare il connettore per visualizzare le azioni selezionate come Nessuna o Avanzata. Questo approccio è ottimale quando sono presenti numerose azioni e molte non vengono usate spesso.
Richiesta
La richiesta definisce quali parametri/dati verranno passati nell'operazione quando l'azione richiama l'operazione nell'API. Quando si importa una definizione OpenAPI, vengono configurate la query di richiesta, le intestazioni e le impostazioni del corpo. È anche possibile eseguire l'importazione manuale dall'esempio.
L'immagine seguente mostra un esempio di come appare lo schermata quando si osserva la definizione.
Questa configurazione è importante perché si traduce in quello che viene visualizzato dall'utente quando usa l'azione.
Modificando ognuno dei parametri o chiedendo allo sviluppatore dell'API di fornire altri dettagli, è possibile migliorare l'esperienza utente quando si usa l'azione. Selezionando i puntini di sospensione (...) per ogni parametro, verrà visualizzata la schermata di modifica seguente.
I campi e le opzioni che è necessario verificare e modificare sono i seguenti:
Nome - Non modificare questo campo, in quanto deve corrispondere al valore previsto dall'API.
Riepilogo - Rendere questo campo intuitivo, ad esempio Fino alla data sarebbe A oggi.
Descrizione - Questo campo contiene una frase che descrive il parametro. Verrà usato come testo segnaposto per il campo.
Valore predefinito - Questo campo è un valore predefinito facoltativo, ma deve essere specificato se si imposta la visibilità su Interna e si imposta il parametro come obbligatorio.
Obbligatorio - Assicurarsi di impostare questa opzione se l'API richiede un valore. Questa opzione visualizza un asterisco rosso accanto al campo.
Visibilità - Questo parametro funziona come l'opzione di visibilità per l'azione descritta in precedenza. Se non si usano spesso alcuni parametri, selezionare l'opzione Avanzata.
Tipo e Formato - Assicurarsi che questi campi siano impostati nel modo appropriato, in quanto i presupposti del parametro che esegue l'importazione dagli esempi non sempre sono corretti.
Tipo di elenco a discesa - Usare questo parametro per configurare un elenco statico o dinamico di valori per semplificare e rendere più prevedibile la selezione dell'utente.
L'immagine seguente mostra un esempio della schermata visualizzata dopo aver corretto il parametro Data di inizio.
Risposta
La risposta definisce che cosa ci si aspetta che venga restituito dall'API. A differenza della richiesta, che ha un'unica definizione, possono essere generate diverse risposte in base allo stato HTTP. Ad esempio, se la chiamata API genera un errore, il corpo conterrà i dettagli dell'errore invece dell'output restituito normalmente dall'API. È possibile restituire anche una risposta predefinita, che è una risposta catch-all se non ne è disponibile una per lo stato HTTP specifico.
La selezione di una delle risposte visualizzerà i dettagli e, analogamente al processo con una richiesta, è possibile modificare questi elementi per semplificare l'utilizzo.
Gli elementi nella risposta corrispondono a quelli visualizzati nel pannello Contenuto dinamico.
Come per la richiesta, assicurarsi di aver incluso nomi e descrizioni validi, perché possono semplificare l'uso dei valori.
Convalida
Notare che nella parte inferiore dello schermo viene visualizzata una sezione di convalida simile all'immagine seguente.
Assicurarsi che questa schermata non mostri errori e prendersi il tempo necessario per risolvere i problemi elencati.
Altre impostazioni
Sono presenti anche altre impostazioni, come trigger, riferimenti e criteri, che questo modulo non tratta in modo approfondito.
È possibile configurare trigger se l'API supporta eventi di polling o webhook. Se definiti, i trigger consentono di usare il connettore come trigger per un flusso di Power Automate.
I riferimenti definiscono i parametri riutilizzabili e vengono in genere creati quando si importa la definizione e questa definisce un parametro riutilizzabile. È anche possibile creare manualmente riferimenti usando l'editor Swagger integrato.
È possibile usare i criteri per modificare i comportamenti di azioni e trigger. I criteri si creano tramite uno dei modelli di criteri predefiniti.
Questi argomenti avanzati verranno trattati in dettaglio successivamente in questo percorso di apprendimento.
