Creare un connettore personalizzato da zero

Per creare un connettore personalizzato, è necessario definire l'API a cui connettersi in modo che il connettore comprenda le operazioni e le strutture di dati dell'API. In questo articolo creerai un connettore personalizzato da zero, senza usare un formato OpenAPI Definition per descrivere l'operazione di sentiment dell'API Servizi cognitivi di Azure Analisi del testo (il nostro esempio per questa serie). Invece, definisci completamente il connettore nella procedura guidata del connettore personalizzato.

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

Prerequisiti

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

  Nota

  L'API Analisi del testo Servizi cognitivi Azure viene usata come API di esempio in questa serie di esercitazioni. In caso di problemi durante l'acquisizione della chiave API, è comunque possibile seguire la procedura descritta in questo articolo usando qualsiasi API REST a cui si ha accesso. La procedura guidata del connettore personalizzato accetta qualsiasi chiave API valida prevista dall'API di destinazione.

• Una delle sottoscrizioni seguenti:

  • Power Automate
  • Power Apps

Avviare la procedura guidata del connettore personalizzato

1. Accedi a Power Apps o Power Automate.

2. Nel riquadro a sinistra seleziona Soluzioni.

3. Modificare o creare una soluzione non gestita per il connettore personalizzato. Informazioni su come creare una soluzione.

4. Selezionare l'elenco a discesa Nuovo connettore personalizzato e selezionare Crea da vuoto.

5. Immettere il nome del connettore, ad esempio SentimentDemo. Selezionare Continua per aprire la procedura guidata del connettore in cui sono state completate queste cinque sezioni in Power Automate:

   • General

   • Security

   • Definition

   • Codice (facoltativo)

   • Test

     

Passaggio 1: aggiornare i dettagli generali

Fornire informazioni sul connettore, ad esempio l'icona, la descrizione, lo schema, l'host e l'URL di base nella sezione Generale . Prova ad eseguire questi passaggi:

1. Selezionare "Carica icona connettore" o "Carica" nella casella dell'icona per caricare un file PNG o JPG dell'icona del connettore. Assicurarsi che sia inferiore a 1 MB. È anche possibile designare un colore di sfondo per l'icona.

2. Nel campo Descrizione immetti un valore significativo. Questa descrizione verrà visualizzata nei dettagli del connettore personalizzato e consentirà ad altri di decidere se il connettore può essere utile per le loro esigenze.

3. Selezionare lo schema URL del connettore, ITTP o HTTP.

4. Aggiorna il campo Host sull'indirizzo per l'API Analisi del testo. Il connettore utilizza l'URL di base e l'host dell'API per determinare come chiamare l'API.

   Parametro	Valore
   Descrzione	Uso dell'API Servizi cognitivi di analisi del sentiment del testo per determinare se il testo è positivo o negativo
   Organizzatore evento	westus.api.cognitive.microsoft.com

5. Aggiornare l'URL di base, il punto di partenza per tutte le chiamate API a un servizio specifico.

6. Selezionare Sicurezza nella parte inferiore per passare alla sezione successiva.

Passaggio 2: specificare il tipo di autenticazione

Per l'autenticazione nei connettori personalizzati sono disponibili diverse opzioni. Le API dei Servizi cognitivi utilizzano l'autenticazione con chiave API, quindi è ciò che specifichi per questa esercitazione.

1. Nella sezione Sicurezza , in Tipo di autenticazione selezionare Chiave API nell'elenco a discesa.

2. In Chiave API specificare un'etichetta di parametro, un nome e una posizione. Specificare un'etichetta significativa, perché viene visualizzata quando un utente effettua per la prima volta una connessione con il connettore personalizzato. Il nome e la posizione del parametro devono corrispondere a quanto previsto dall'API.

   Parametro	Valore
   Etichetta del parametro	Chiave API
   Nome del parametro	Ocp-Apim-Subscription-Key
   Posizione del parametro	Intestazione

3. Nella parte superiore della procedura guidata verificare che il nome sia impostato su SentimentDemoe quindi selezionare Crea connettore.

4. Selezionare Definizione nella parte inferiore per passare alla sezione successiva.

Passaggio 3: creare la definizione del connettore

La procedura guidata del connettore personalizzato offre molte opzioni per descrivere il funzionamento del connettore e il modo in cui viene esposto in app per la logica, flussi, app e agenti. È possibile definire azioni, trigger, riferimenti e criteri. Spiegheremo l'interfaccia utente e tratteremo alcune opzioni in questa sezione, ma ti incoraggiamo anche a esplorare da solo.

Creare un'azione

La prima cosa da fare è creare un'azione che richiama l'operazione di analisi del sentiment dell'API di analisi del testo. Nel riquadro sinistro della scheda Definizione vengono visualizzate le azioni, i trigger (per App per la logica, Power Automate e Copilot Studio), i riferimenti e i criteri definiti per il connettore.

1. Seleziona Nuova azione.

2. Nell'area Generale, aggiungi un riepilogo, una descrizione e un ID operazione per questa azione.

   Parametro	Valore
   Riepilogo	Restituisce un punteggio numerico che rappresenta il sentiment rilevato
   Descrzione	L'API restituisce un punteggio numerico compreso tra 0 e 1. I punteggi prossimi a 1 indicano una valutazione positiva, mentre i valori prossimi a 0 indicano una valutazione negativa.
   ID operazione	DetectSentiment

   Lascia la proprietà Visibilità impostata su nessuna. Questa proprietà per operazioni e parametri in un'app per la logica o in un flusso ha le seguenti opzioni:

   • nessuna: visualizzata normalmente nell'app per la logica o nel flusso
   • avanzata: nascosta sotto un altro menu
   • interna: nascosta all'utente
   • importante: sempre mostrata all'utente per prima

3. Nell'area Richiesta, seleziona Importa da esempio.

4. Specifica le informazioni necessarie per la connessione all'API e al corpo della richiesta (fornite dopo la tabella), quindi seleziona Importa.

   Queste informazioni vengono in genere ottenute dalla documentazione dell'API per un'API pubblica.

   Parametro	Valore
   Verbo	POST
   URL	https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment
   Corpo	Utilizza l'esempio JSON.

   Esempio:

   {
     "documents": [
       {
         "language": "string",
         "id": "string",
         "text": "string"
       }
     ]
   }
   

5. Nell'area Risposta seleziona Aggiungi risposta predefinita.

6. Specifica il corpo della risposta, quindi seleziona Importa. Come per il corpo della richiesta, queste informazioni sono disponibili per te, ma in genere vengono fornite nella documentazione dell'API.

   Esempio:

   {
    "documents": [
      {
        "score": 0.0,
        "id": "string"
      }
    ],
    "errors": [
      {
        "id": "string",
        "message": "string"
      }
    ]
   }
   

   L'area Convalida mostra gli eventuali problemi rilevati nella definizione dell'API.

7. Risolvi eventuali problemi. Quando la convalida della definizione ha esito positivo, dovrebbe essere visualizzato un segno di spunta verde.

8. Nell'angolo in alto a destra della procedura guidata, seleziona Aggiorna il connettore.

Aggiorna la definizione

Apportiamo alcune modifiche affinché il connettore sia più intuitivo da usare quando qualcuno lo usa in Logic Apps, Power Automate, Power Apps o Copilot Studio.

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 i valori del parametro e quindi seleziona Indietro.

   Parametro	Valore
   Titolo	ID
   Descrzione	Identificatore per ciascun documento inviato
   Valore predefinito	1
   Obbligatorio	Sì

4. Nell'area Parametri, seleziona lingua>Modifica, quindi ripeti il processo che hai eseguito per id per aggiungere i seguenti valori language:

   Parametro	Valore
   Titolo	Lingua
   Descrzione	Codice di lingua di due o quattro caratteri per il testo
   Valore predefinito	en
   Obbligatorio	Sì

5. Nell'area Parametri, seleziona testo>Modifica, quindi ripeti il processo che hai eseguito per id e language per aggiungere i seguenti valori text:

   Parametro	Valore
   Titolo	Testo
   Descrzione	Testo da analizzare per l'analisi del sentiment
   Valore predefinito	None
   Obbligatorio	Sì

6. Nell'area Parametri, seleziona Indietro per tornare alla scheda principale Definizione.

7. Nell'angolo in alto a destra della procedura guidata, seleziona Aggiorna il connettore.

8. Selezionare Codice nella parte inferiore per passare alla sezione successiva.

Passaggio 4: (facoltativo) utilizzare il supporto per codice personalizzato

Il codice personalizzato trasforma i payload di richieste e risposte oltre l'ambito di modelli di criteri esistenti. Le trasformazioni includono l'invio di richieste esterne per recuperare dati aggiuntivi. Il codice utilizzato avrà la precedenza sulla definizione senza codice. Ciò significa che il codice verrà eseguito e che non invieremo la richiesta al back-end.

Puoi incollare il codice o caricare un file con il codice. Il codice deve:

• Scritto in C#.
• Avere un tempo massimo di esecuzione di cinque secondi.
• Avere una dimensione del file non superiore a 1 MB.

Per istruzioni ed esempi di scrittura di codice, vedi Scrivere codice in connettori personalizzati.

Per domande frequenti sul codice personalizzato, vedi Domande frequenti sul codice personalizzato.

1. Nella scheda Codice immetti il tuo codice personalizzato utilizzando una delle seguenti opzioni:

   • Copia/Incolla
   • Seleziona il pulsante Carica.

   Se scegli di caricare il codice personalizzato, saranno disponibili solo i file con estensione .cs o .csx.

   

   Importante

   Attualmente, supportiamo solo l'evidenziazione della sintassi nell'editor di codice. Assicurati di testare il codice localmente.

2. Dopo aver incollato o caricato il codice, seleziona l'interruttore accanto a Codice disabilitato per abilitare il codice. Il nome dell'interruttore cambia in Codice attivato.

   Puoi abilitare o disabilitare il codice in qualsiasi momento. Se l'interruttore è impostato su Codice disattivato, il tuo codice viene eliminato.

3. Seleziona le azioni e i trigger da applicare al codice personalizzato selezionando un'opzione nel menu a discesa. Se non viene selezionata alcuna operazione, le azioni e i trigger vengono applicati a tutte le operazioni.

   

Passaggio 5: 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 scheda Test seleziona Nuova connessione.

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

   Nota

   Per le API che richiedono l'autenticazione Bearer, aggiungi Bearer e uno spazio prima della chiave API.

3. Ritorna alla scheda Test ed esegui una delle seguenti operazioni:

   • In Power Automate, viene visualizzata la scheda Test. Seleziona l'icona di aggiornamento per assicurarti che le informazioni sulla connessione siano aggiornate.

     

   • In Power Apps viene visualizzato l'elenco delle connessioni disponibili nell'ambiente corrente. Nel riquadro a sinistra, seleziona Connettori personalizzati. Scegli il connettore creato e quindi torna alla scheda Test.

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

   Il connettore chiama l'API.

5. Esamina la risposta, che include il punteggio del sentiment.

   

Procedure consigliate per gli utenti dell'interfaccia della riga di comando

• Scarica tutti i connettori e usa Git o qualsiasi altro sistema di gestione di codice sorgente per salvare i file.

• Nel caso di un aggiornamento non corretto, ridistribuisci il connettore eseguendo di nuovo il comando di aggiornamento con il set di file corretto dal sistema di gestione di codice sorgente.

• Testa il connettore personalizzato e il file di impostazioni in un ambiente di test prima di eseguire la distribuzione nell'ambiente di produzione.

• Verifica sempre con attenzione che gli ID ambiente e connettore siano corretti.

Risolvere i problemi comuni

• Le azioni del connettore personalizzato non vengono caricate: dopo la creazione o l'aggiornamento di un connettore, attendere alcuni minuti prima che la piattaforma propaga le modifiche prima del test. Cancellare la cache del browser o provare una sessione di esplorazione privata se le azioni non vengono ancora visualizzate.

• 401 Errori non autorizzati: verificare che la chiave API o le credenziali OAuth siano corrette e non siano scadute. Per i connettori OAuth, verificare che l'URI di reindirizzamento nel provider di identità corrisponda all'URI di reindirizzamento per connettore visualizzato nella scheda Sicurezza .

• 403 Errori non consentiti: verificare che l'endpoint API consenta le connessioni dagli intervalli IP di Power Platform. Per le Funzioni di Azure che si trovano dietro una rete virtuale, consultare Indirizzi IP in uscita dei connettori gestiti e assicurarsi che le regole di rete consentano il traffico proveniente da tali intervalli IP.

• Connettore non visibile dopo la condivisione: la visualizzazione di un connettore condiviso per altri utenti può richiedere alcuni minuti. Se il connettore è stato aggiunto a una soluzione, gli utenti devono accedere a tale soluzione per visualizzare il connettore.

Passaggi successivi

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

• Power Automate
• Power Apps
• Logic Apps
• Copilot Studio

È 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

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