Creare un connettore personalizzato da una definizione OpenAPI

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, Microsoft Power Automate e Microsoft 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 definizione OpenAPI che descrive l'API valutazione di analisi del testo di Servizi cognitivi (il nostro esempio per questa serie).

Per un'altra modalità di descrizione di un'API, vai a Creare un connettore personalizzato da zero.

Prerequisiti

• Una definizione OpenAPI che descrive l'API di esempio. Quando si crea un connettore personalizzato, la definizione OpenAPI deve essere inferiore a 1 MB. La definizione OpenAPI deve essere nel formato OpenAPI 2.0 (precedentemente noto come Swagger).

  Se sono presenti più definizioni di sicurezza, il connettore personalizzato seleziona la definizione di sicurezza principale. La creazione di connettori personalizzati non supporta le credenziali client (ad esempio, applicazione e password) nella definizione di sicurezza OAuth.

• 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 usi App per la logica, prima di tutto crea un connettore personalizzato in App per la logica di Azure.

Importare la definizione OpenAPI

Ora sei pronto per lavorare con la definizione OpenAPI che hai scaricato. Tutte le informazioni richieste sono contenute nella definizione e puoi rivedere e aggiornare queste informazioni mentre esegui la procedura guidata del connettore personalizzato.

Per iniziare, importa la definizione OpenAPI per App per la logica, o per Power Automate e Power Apps.

Nota

Una definizione OpenAPI deve essere nel formato OpenAPI 2.0 (precedentemente noto come Swagger). Le definizioni OpenAPI che sono nel formato OpenAPI 3.0 non sono supportate.

Importare la definizione OpenAPI 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 seleziona Modifica.

   

3. In Generale, scegli Carica un file OpenAPI, e quindi passa alla definizione OpenAPI creata.

   

Nota

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

Importare la definizione OpenAPI per Power Automate e Power Apps

1. Accedi a Power Apps o Power Automate.

2. Nel riquadro a sinistra, seleziona Dati > Connettori personalizzati.

   

3. Seleziona Nuovo connettore personalizzato, e quindi scegli Importa un file OpenAPI.

   

4. Immetti un nome per il connettore personalizzato, vai alla definizione OpenAPI scaricata o creata e seleziona Continua.

   

   Parametro	valore
   Titolo connettore personalizzato	SentimentDemo

Esamina 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. Indicheremo eventuali differenze. In questa parte dell'argomento, esamineremo principalmente l'interfaccia utente e ti mostreremo come i valori corrispondono alle sezioni del file OpenAPI.

1. Nella parte superiore della procedura guidata verifica che il nome sia impostato su SentimentDemo e quindi seleziona Crea connettore.

2. Nella pagina Generale esamina le informazioni importate dalla definizione OpenAPI, inclusi l'host e l'URL di base dell'API. Il connettore utilizza l'URL di base e l'host dell'API per determinare come chiamare l'API.

   

   Nota

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

   La seguente sezione della definizione OpenAPI contiene informazioni per questa pagina dell'interfaccia utente:

     "info": {
       "version": "1.0.0",
       "title": "SentimentDemo",
       "description": "Uses the Cognitive Services Text Analytics Sentiment API to determine whether text is positive or negative"
     },
     "host": "westus.api.cognitive.microsoft.com",
     "basePath": "/",
     "schemes": [
       "https"
     ]
   

Esaminare il tipo di autenticazione

Per l'autenticazione nei connettori personalizzati sono disponibili diverse opzioni. Le API di Servizi cognitivi utilizzano l'autenticazione della chiave API, che quindi è specificata nella definizione OpenAPI.

Nella pagina Sicurezza, esamina le informazioni di autenticazione per la chiave API.

L'etichetta viene visualizzata quando qualcuno stabilisce una connessione con il connettore personalizzato; puoi scegliere Modifica per cambiare questo valore. Il nome e la posizione del parametro devono corrispondere al nome e alla posizione previsti dall'API, in questo caso Ocp-Apim-Subscription-Key e Intestazione.

La seguente sezione della definizione OpenAPI contiene informazioni per questa pagina dell'interfaccia utente:

  "securityDefinitions": {
    "api_key": {
      "type": "apiKey",
      "in": "header",
      "name": "Ocp-Apim-Subscription-Key"
    }
  }

Esaminare la definizione del connettore

La pagina Definizione della procedura guidata del connettore personalizzato offre molte opzioni per definire il funzionamento del connettore e la modalità di esposizione 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. Per informazioni sulla definizione di oggetti da zero in questa interfaccia utente, vedi Creare la definizione del connettore.

1. L'area seguente 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 definizione OpenAPI. 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. Qui è possibile modificare le informazioni, inclusa la proprietà Visibilità relativa alle operazioni e ai parametri in un'app per la logica o un flusso:

   • nessuna: visualizzati normalmente nell'app per la logica o nel flusso

   • avanzata: nascosti in un menu aggiuntivo

   • interna: nascosti all'utente

   • importante: sempre mostrati all'utente come prima cosa

     

3. L'area Richiesta visualizza informazioni basate sulla richiesta HTTP inclusa nella definizione OpenAPI. In questo caso, il verbo HTTP è POST e l'URL è /text/analytics/v2.0/sentiment (l'URL completo all'API è <https://westus.api.cognitive.microsoft.com//text/analytics/v2.0/sentiment>). Guarderemo più da vicino il parametro body a breve.

   

   La seguente sezione della definizione OpenAPI contiene informazioni per le aree Generale e Richiesta dell'interfaccia utente:

   "paths": {
     "/text/analytics/v2.0/sentiment": {
       "post": {
         "summary": "Returns a numeric score representing the sentiment detected",
         "description": "The API returns a numeric score between 0 and 1. Scores close to 1 indicate positive sentiment, while scores close to 0 indicate negative sentiment.",
         "operationId": "DetectSentiment"
   

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

   

   La seguente sezione della definizione OpenAPI contiene alcune informazioni correlate alla risposta:

   "score": {
    "type": "number",
    "format": "float",
    "description": "score",
    "x-ms-summary": "score"
   },
   "id": {
    "type": "string",
    "description": "id",
    "x-ms-summary": "id"
   }
   

   Questa sezione mostra i due valori restituiti dal connettore: id e score. Include i loro tipi di dati e il campo x-ms-summary, che è un'estensione OpenAPI. Per ulteriori informazioni su questa e altre estensioni, vedi Estendere una definizione OpenAPI per un connettore personalizzato.

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

   

Aggiorna la definizione

La definizione OpenAPI scaricata è un buon esempio di base, ma è possibile usare definizioni che richiedono molti aggiornamenti, in modo che il connettore risulti più semplice quando gli utenti lo usano in un'app per la logica, un flusso o un'app. Ti mostreremo come apportare una modifica alla definizione.

1. Nell'area Richiesta, seleziona corpo e quindi seleziona Modifica.

   

2. Nell'area Parametro verranno visualizzati i tre parametri previsti dall'API: ID, Language e Text. Seleziona ID, quindi Modifica.

   

3. Nell'area Proprietà dello schema aggiorna la descrizione del parametro e quindi scegli Indietro.

   

   Parametro	Valore
   Descrizione	Identificatore numerico per ogni documento inviato

4. Nell'area Parametro scegli Indietro per tornare alla pagina di definizione principale.

5. Nell'angolo superiore destro della procedura guidata, seleziona Aggiorna connettore.

Scaricare il file OpenAPI aggiornato

Al momento puoi creare da zero un connettore da un file OpenAPI o da zero (in Power Automate e Power Apps). Indipendentemente da come viene creato un connettore, è possibile scaricare la definizione OpenAPI usata internamente dal servizio.

• In App per la logica esegui il download dal connettore personalizzato.

  

• In Power Automate o Power Apps, scarica dall'elenco dei connettori personalizzati.

  

Test del 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 seleziona Nuova connessione.

   

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

   

3. Ritorna alla scheda Pagina di test ed esegui una delle seguenti operazioni:

   • 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 fai clic sull'icona a forma di ingranaggio e quindi seleziona Connettori personalizzati. Scegli il connettore creato e quindi torna alla pagina Test.

     

4. Nella pagina Test immettere un valore per il campo testo (negli altri campi vengono usati i valori predefiniti impostati in precedenza) e quindi selezionare Verifica operazione.

   

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

   

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 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.