Uso delle estensioni OpenAPI
Questa unità spiega come usare le estensioni Microsoft OpenAPI x-ms-capabilities e x-ms-url-encoding nei connettori personalizzati.
L'estensione x-ms-capabilities consente di configurare le funzionalità offerte dal connettore a livello di connettore e di operazione. Attualmente, i connettori personalizzati di Microsoft Power Platform possono essere configurati per le seguenti opzioni:
chunkTransfer: a livello di operazione
testConnection: a livello di connettore
Abilitazione del trasferimento di blocchi
Quando si gestiscono i messaggi, il runtime del connettore impone una dimensione massima al contenuto del messaggio. Questo limite aiuta a ridurre il sovraccarico creato dall'archiviazione e dall'elaborazione dei messaggi di grandi dimensioni. Per gestire messaggi oltre questo limite, i connettori possono suddividerli in blocchi di messaggi più piccoli. In questo modo, si consente il trasferimento di contenuti di grandi dimensioni. Quando si comunica con altri servizi tramite i connettori, il runtime può usare i messaggi di grandi dimensioni, ma solo in blocchi. Ciò significa che i connettori devono supportare anche la divisione in blocchi, che deve essere usata anche per lo scambio di messaggi HTTP sottostante tra il connettore e i servizi.
Affinché un connettore personalizzato possa usare il trasferimento di blocchi, sono necessari i seguenti parametri:
L'API deve supportare la divisione in blocchi. Per altre informazioni, vedere Gestione dei messaggi in blocchi per i connettori.
Il connettore personalizzato deve abilitare l'estensione della capacità di trasferimento di blocchi nell'azione.
Il creatore che usa l'azione del connettore deve abilitare il trasferimento di blocchi per il passaggio del flusso.
Nella definizione del connettore personalizzato la logica seguente deve essere aggiunta alla definizione delle operazioni per cui abilitare il trasferimento di blocchi.
{chunkTransfer: true}
Se si usa il file apiDefinition.swagger.json scaricato anziché l'editor YAML, è necessario apportare la modifica mostrata nello screenshot seguente.
La modifica apportata non verrà visualizzata nella finestra di progettazione dei connettori personalizzati. Tuttavia, quando l'azione viene usata in un flusso, l'opzione seguente, Consenti la divisione in blocchi, verrà visualizzata nelle impostazioni del passaggio.
Supponendo che l'API supporti questa procedura, dopo l'abilitazione della divisione in blocchi i messaggi di grandi dimensioni funzionano e vengono trasferiti con questa funzionalità.
Configurazione della connessione di test
Per impostazione predefinita, quando si crea una connessione con un connettore personalizzato non ne viene verificata la validità. Ad esempio, se è stato fornito un URL host o una chiave API non validi, la connessione può essere creata, ma non funziona. Usando l'estensione OpenAPI testConnection, è possibile specificare un'operazione sul connettore personalizzato che verrà eseguita durante la creazione della connessione per convalidare la configurazione fornita.
Per implementare il test della connessione, è necessario che sul connettore personalizzato sia definita una semplice operazione che restituisce HTTP 200 (operazione completata). Questa operazione può essere già disponibile e configurata oppure è possibile crearne una specificamente per testare la connessione. Se si configura un'operazione di test specifica, è consigliabile contrassegnarla come interna in modo che gli utenti non provino a usarla. È anche possibile passare dei parametri statici all'operazione. Ad esempio, se l'azione ha richiesto un parametro $top per limitare il numero di record restituito, è possibile usare i parametri per limitare i risultati a un record.
L'esempio seguente mostra l'operazione ListInvoices definita e come verrà usata per testare la connessione, nonché la configurazione dell'estensione testConnection.
La modifica di apiDefinition.swagger.json sarà simile all'immagine seguente.
Configurazione della codifica del percorso
L'estensione x-ms-url-encoding si applica ai parametri inclusi nel percorso dell'URL della richiesta.
Ad esempio, per restituire i clienti in base al paese/area geografica, è possibile definire un'azione con la seguente richiesta:
https://myapi.myservice.com/customers/{country}
In questa azione, country diventa un parametro fornito dall'utente del connettore. Poiché questi parametri fanno parte del percorso, devono avere una codifica URL. Per impostazione predefinita, i parametri del percorso hanno una codifica URL singola. Tuttavia, in alcuni scenari, l'API sottostante potrebbe prevedere parametri con codifica URL doppia per risolvere possibili ambiguità introdotte da determinati caratteri come il simbolo della chiocciola (@), la barra (/), la barra rovesciata (\) e così via.
Per configurare la doppia codifica su un parametro del percorso, aggiungere la seguente opzione al parametro:
x-ms-url-encoding: double
Osservare un'API con due metodi che restituiscono il parametro del percorso di input, ma uno usa la doppia codifica, come mostrato nell'immagine seguente.
Quando si esegue un flusso di Microsoft Power Automate che chiama entrambe le azioni con un input complesso, la doppia codifica passa lo stesso valore di testo all'API, ma con doppia codifica.
Questa estensione semplifica la gestione dei parametri in scenari in cui l'API prevede una doppia codifica URL perché l'utente di un connettore non deve codificare i parametri del percorso per la chiamata delle azioni.