Creare un connettore personalizzato da una raccolta Postman

Nota

Questo argomento fa parte di una serie di esercitazioni sulla creazione e sull'uso di connettori personalizzati in App per la logica di Azure, Power Automate e Power Apps. Assicurati di leggere la panoramica dei connettori personalizzati per capire il processo.

Per creare un connettore personalizzato, è necessario descrivere l'API con cui vuoi stabilire la connessione in modo che il connettore ne riconosca le operazioni e le strutture dati. In questo argomento, crei un connettore personalizzato, usando una raccolta Postman che descrive l'API Servizi cognitivi di analisi del sentiment del testo (il nostro esempio per questa serie).

Per altri modi per descrivere un'API, vai ai seguenti argomenti:

Prerequisiti

Importare la raccolta Postman

A questo punto è possibile usare la raccolta Postman creata o scaricata. La raccolta contiene numerose informazioni necessarie. È anche possibile esaminare e aggiornare queste informazioni durante la creazione guidata del connettore personalizzato. Per iniziare, importa la raccolta Postman per App per la logica o per Power Automate e Power Apps.

Importare la raccolta Postman per App per la logica

  1. Passa al portale di Azure e apri il connettore per App per la logica creato in precedenza in Creare un connettore personalizzato in App per la logica di Azure.

  2. Nel menu del connettore, seleziona Connettore per app per la logica, quindi scegli Modifica.

    Modificare il connettore per app per la logica

  3. Sotto Generale, scegli Carica raccolta Postman V1, quindi vai alla raccolta Postman che hai creato.

    Screenshot che mostra l'opzione Carica raccolta Postman V1.

    La procedura guidata importa la raccolta, quindi la converte in una definizione OpenAPI denominata generatedApiDefinition.swagger.json.

Nota

In questa esercitazione si usa un API REST, ma puoi anche utilizzare un'API SOAP con App per la logica.

Importare la raccolta Postman per Power Automate e Power Apps

  1. Vai a make.powerapps.com o flow.microsoft.com.

  2. Nel riquadro di spostamento seleziona Dati > Connettori personalizzati.

  3. Scegli Nuovo connettore personalizzato e quindi Importa un file Postman Collection.

  4. Immetti un nome per il connettore personalizzato, quindi passa alla raccolta Postman scaricata o creata e scegli Continua.

    Screenshot che mostra i passaggi per importare la raccolta.

    Parametro Valore
    Titolo connettore personalizzato "SentimentDemo"

    La procedura guidata importa la raccolta, quindi la converte in una definizione OpenAPI denominata generatedApiDefinition.swagger.json.

Aggiornare i dettagli generali

Da qui in avanti verrà illustrata l'interfaccia utente di Power Automate, ma i passaggi sono per lo più uguali per tutte le tre tecnologie. Le eventuali differenze verranno evidenziate.

  1. Nella pagina Generale esamina le informazioni importate dalla raccolta Postman, inclusi l'host e l'URL di base dell'API. Il connettore usa l'URL dell'host e di base per determinare come chiamare l'API.

    Nota

    Per ulteriori informazioni sulla connessione alle API locali, vedi Connessione alle API locali utilizzando il gateway dati.

  2. Immetti una descrizione significativa. Questa descrizione verrà visualizzata nei dettagli del connettore personalizzato e consentirà ad altri utenti di determinare se può essere utile per le loro esigenze.

    Parametro valore
    Descrizione "Uso dell'API Servizi cognitivi di analisi del sentiment del testo per determinare se il testo è positivo o negativo"

Specifica il tipo di autenticazione

Per l'autenticazione nei connettori personalizzati sono disponibili diverse opzioni. L'API Servizi cognitivi utilizza l'autenticazione con chiave API.

  1. Nella pagina Sicurezza scegli Chiave API in Tipo di autenticazione.

  2. In Chiave API specifica etichetta, nome e posizione di un parametro. Scegli un'etichetta espressiva e significativa. Questo testo verrà visualizzato agli utenti per indirizzarli a stabilire connessioni usando il connettore personalizzato. Il nome e la posizione del parametro devono corrispondere al nome e alla posizione previsti dall'API, in questo caso l'intestazione specificata in Postman. Scegliere Connetti.

    Parametri della chiave API

    Parametro valore
    Etichetta parametro "Chiave API"
    Nome parametro "Ocp-Apim-Subscription-Key"
    Posizione parametro "Intestazione"
  3. Nella parte superiore della procedura guidata verifica che il nome sia impostato su "SentimentDemo" e quindi seleziona Crea connettore.

Esaminare e aggiornare la definizione del connettore

La procedura guidata del connettore personalizzato offre diverse opzioni per definire il funzionamento del connettore e il modo in cui verrà esposto nelle app per la logica, nei flussi e nelle app. Spiegheremo l'interfaccia utente e tratteremo alcune opzioni in questa sezione, ma ti incoraggiamo anche a esplorare da solo.

Esaminare l'interfaccia utente e la definizione

Prima di entrare in alcuni passaggi specifici nella pagina Definizione, diamo prima un'occhiata all'interfaccia utente.

  1. Questa area visualizza le azioni, i trigger (per App per la logica e Power Automate) e i riferimenti definiti per il connettore. In questo caso viene visualizzata l'azione DetectSentiment della raccolta Postman. In questo connettore non sono presenti trigger. Per informazioni sui trigger per i connettori personalizzati, vedere l'articolo su come usare i webhook con App per la logica di Azure e Power Automate.

    Pagina Definizione: azioni e trigger

  2. L'area Generale mostra informazioni sull'azione o sul trigger attualmente selezionato. Queste informazioni provengono dalla raccolta Postman. Qui è possibile modificare le informazioni, inclusa la proprietà Visibilità relativa alle operazioni e ai parametri in un'app per la logica o un flusso:

    • importante: sempre mostrati all'utente come prima cosa
    • nessuna: visualizzati normalmente nell'app per la logica o nel flusso
    • avanzata: verranno inizialmente nascoste in un menu aggiuntivo
    • interna: non verranno mostrate all'utente
  3. L'area Richiesta visualizza informazioni basate sulla richiesta HTTP inclusa nella raccolta Postman. In questo caso, il verbo HTTP è POST e l'URL è "/text/analytics/v2.0/sentiment". L'URL completo dell'API è <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>. Guarderemo più da vicino il parametro body a breve.

  4. L'area Risposta visualizza informazioni basate sulla risposta HTTP inclusa nella raccolta Postman. In questo caso, l'unica risposta definita è "200" (risposta con esito positivo), ma è possibile definire altre risposte.

  5. L'area Convalida mostra gli eventuali problemi rilevati nella definizione dell'API. Verifica questa area prima di salvare un connettore.

Aggiorna la definizione

Verranno ora apportate alcune modifiche per rendere il connettore più semplice da usare in un'app per la logica, Power Automate, o Power Apps.

  1. Nell'area Generale modificare il riepilogo in "Restituzione di un punteggio numerico che rappresenta il sentiment rilevato".

  2. Nell'area Richiesta seleziona corpo e quindi Modifica.

  3. Nell'area Parametro verranno visualizzati i tre parametri previsti dall'API: id, language e text. Seleziona ID e quindi Modifica.

  4. Nell'area Proprietà dello schema aggiorna i valori del parametro e quindi scegli Indietro.

    Modifica la proprietà dello schema

    Parametro valore
    Titolo "ID"
    Descrizione "Identificatore per ogni documento inviato"
    Valore predefinito "1"
    Obbligatorio "Sì"
  5. Nell'area Parametro scegli language, quindi Modifica e ripeti il processo eseguito in precedenza con i valori seguenti.

    Parametro valore
    Titolo "Lingua"
    Descrizione "Codice di lingua di 2 o 4 caratteri per il testo"
    Valore predefinito "en"
    Obbligatorio "Sì"
  6. Nell'area Parametro scegli text, quindi Modifica e ripeti il processo eseguito in precedenza con i valori seguenti.

    Parametro valore
    Titolo "Testo"
    Descrizione "Testo in cui analizzare il sentiment"
    Valore predefinito Nessuna
    Obbligatorio "Sì"
  7. Nell'area Parametro scegli Indietro per tornare alla pagina di definizione principale.

  8. Seleziona Aggiorna connettore in alto a destra nella procedura guidata.

Testare il connettore

Dopo averlo creato, testa il connettore per verificare se funziona correttamente. I test sono attualmente disponibili solo in Power Automate e Power Apps.

Importante

Quando si utilizza una chiave API, ti consigliamo di non testare il connettore immediatamente dopo averlo creato. Potrebbero essere necessari alcuni minuti prima che il connettore sia pronto per la connessione all'API.

  1. Nella pagina Test scegli Nuova connessione.

  2. Immetti la chiave API dell'API Analisi del testo e quindi seleziona Crea connessione.

  3. Torna alla pagina Test:

    • In Power Automate viene visualizzata nuovamente la pagina Test. Scegli l'icona di aggiornamento per assicurarti che le informazioni relative alla connessione siano aggiornate.
    • In Power Apps viene visualizzato l'elenco delle connessioni disponibili nell'ambiente corrente. Nell'angolo superiore destro scegli l'icona a forma di ingranaggio e quindi seleziona Connettori personalizzati. Scegli il connettore creato e quindi torna alla pagina Test.
  4. Nella pagina Test immetti un valore per il campo testo (negli altri campi vengono usati i valori predefiniti impostati in precedenza) e quindi seleziona Verifica operazione.

  5. Il connettore chiama l'API e puoi esaminare la risposta che include il punteggio del sentiment.

    Risposta del connettore

Limiti

In Power Automate e Power Apps, se aggiorni un connettore personalizzato esistente utilizzando una raccolta Postman, dovrai ripetere tutte le personalizzazioni precedenti prima di salvare il connettore. Ad esempio, dovrai riconfigurare il tipo di autenticazione, i valori predefiniti dei parametri per le azioni e altro.

Passaggi successivi

Una volta creato un connettore personalizzato e definiti i relativi comportamenti, è possibile usarlo.

È anche possibile condividere un connettore nell'organizzazione e/o ottenerne la certificazione in modo che possa essere usato da persone esterne all'organizzazione.

Inviare commenti

L'invio da parte degli utenti di feedback sui problemi riscontrati con la piattaforma di connettori o di idee su nuove funzionalità è molto apprezzato. Per fornire un feedback, vai a Inviare problemi o ottenere assistenza per i connettori e seleziona il tipo di commenti.