Creare un connettore personalizzato da una raccolta Postman

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:

• Creare un connettore personalizzato da una definizione OpenAPI

• Creare un connettore personalizzato da zero.

Prerequisiti

• Una raccolta Postman che descrive l'API di esempio:

  • Scaricare la raccolta Postman creata
    oppure
  • Completa l'argomento Creare una raccolta Postman per un connettore personalizzato Tieni presente che quando crei un connettore personalizzato, la raccolta Postman deve essere di dimensioni inferiori a 1 MB.

• Una chiave API per l'API Analisi del testo di Servizi cognitivi

• Una delle sottoscrizioni seguenti:

  • Azure, se stai usando le App per la logica
  • Power Automate
  • Power Apps

• Se utilizzi App per la logica, prima di tutto crea un connettore personalizzato in App per la logica di Azure

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.

   

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

   

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

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.

   

   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.

   

   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.

   

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.

   

   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.

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.

   

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.

• Usare un connettore personalizzato da un flusso
• Usare un connettore personalizzato da un'app
• Utilizzare un connettore personalizzato da un'app per la logica

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

• Condividere il connettore
• Certificare il connettore

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.