Creare un connettore personalizzato da zero

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

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 da zero, senza usando una definizione OpenAPI per descrivere l'operazione della valutazione dell'API dell'analisi del testo di Servizi cognitivi di Azure (il nostro esempio per questa serie). Al contrario, descrivi 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

• 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 Dati > Connettori personalizzati.

3. Seleziona Nuovo connettore personalizzato > Crea da zero.

4. Immetti un nome per il connettore personalizzato e quindi seleziona Continua.

   Parametro	valore
   Titolo connettore personalizzato	SentimentDemo

Passaggio 1: 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 tecnologie. Indicheremo eventuali differenze.

Nella scheda Generale, procedi come segue:

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

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

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 scheda Sicurezza scegli Chiave API in Tipo di autenticazione.

2. In Chiave API specifica etichetta, nome e posizione di un parametro. Specificare un'etichetta significativa, perché verrà visualizzata quando un utente stabilisce per la prima volta una connessione con il connettore personalizzato. Il nome e la posizione del parametro devono corrispondere a quanto previsto dall'API. Selezionare 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.

Passaggio 3: creare la definizione del connettore

La procedura guidata del connettore personalizzato offre molte opzioni per definire il funzionamento del connettore e la modalità di esposizione in app per la logica, flussi e app. 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 chiama l'operazione di valutazione dell'API di analisi del testo.

1. Il riquadro sinistro della scheda Definizione mostra tutte le azioni e tutti i trigger (per App per la logica e Power Automate), oltre ai riferimenti definiti per il connettore. Seleziona Nuova azione.

   In questo connettore non sono presenti trigger. Per informazioni sui trigger per i connettori personalizzati, vai a 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. Aggiungi un riepilogo, una descrizione e un ID operazione per questa azione.

   Parametro	valore
   Riepilogo	Restituisce un punteggio numerico che rappresenta la valutazione rilevata
   Descrizione	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: visualizzati normalmente nell'app per la logica o nel flusso
   • avanzata: nascosti sotto un altro menu
   • interna: nascosti all'utente
   • importante: sempre mostrati all'utente come prima cosa

3. L'area Richiesta visualizza le informazioni in base alla richiesta HTTP per l'azione. Selezionare Importa da esempio.

4. Specifica le informazioni necessarie per la connessione all'API, specifica il corpo della richiesta (fornito dopo l'immagine seguente) e seleziona Importa. Forniamo queste informazioni per te, ma per un'API pubblica, in genere ottieni queste informazioni da documentazione come API di analisi del testo (v2.0).

   Parametro	valore
   Verbo	POST
   URL	<https://westus.api.cognitive.microsoft.com/text/analytics/v2.0/sentiment>
   Body	Utilizza il seguente codice JSON

   Esempio:

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

5. L'area Risposta visualizza le informazioni in base alla risposta HTTP per l'azione. Selezionare Aggiungi risposta predefinita.

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

   Esempio:

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

7. L'area Convalida mostra gli eventuali problemi rilevati nella definizione dell'API. Controlla lo stato, quindi nell'angolo in alto a destra della procedura guidata, seleziona Aggiorna connettore.

Aggiorna la definizione

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

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
   Title	ID
   Descrzione	Identificatore per ciascun documento inviato
   Default value	1
   Obbligatorio	Sì

4. Nell'area Parametro, seleziona lingua > Modifica, quindi ripeti il processo che utilizzato per id nei passaggi 2 e 3 di questa procedura, con i seguenti valori.

   Parametro	valore
   Title	Lingua
   Descrzione	Codice di lingua di due o quattro caratteri per il testo
   Default value	en
   Obbligatorio	Sì

5. Nell'area Parametro, seleziona testo > Modifica, quindi ripeti il processo che utilizzato per id nei passaggi 2 e 3 di questa procedura, con i seguenti valori.

   Parametro	Valore
   Titolo	Testo
   Descrizione	Testo da analizzare per la valutazione
   Valore predefinito	Nessuno
   Obbligatorio	Sì

6. Nell'area Parametro, scegli Indietro per tornare alla scheda principale Definizione.

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

Passaggio 4: (facoltativo) abilita il connettore come plug-in IA

Utilizza la scheda Plug-in IA (anteprima) per un connettore solo se hai intenzione di certificare il tuo connettore. Affinché un connettore possa essere utilizzato come plug-in IA, il connettore deve essere certificato.

Prima di abilitare il connettore come plug-in IA, assicurati di comprendere il caso d'uso per gli scenari di plug-in IA e di aver esaminato altre considerazioni come supportabilità, procedure consigliate e consigli. Ulteriori informazioni: Creare un plug-in IA del connettore (anteprima)

1. Nel riquadro di spostamento a sinistra, seleziona Connettori personalizzati.

   Se non vedi Connettori personalizzati, seleziona Altro > Scopri tutto > Connettori personalizzati. L'opzione viene visualizzata nel riquadro di spostamento a sinistra.

2. In alto a destra, seleziona un'opzione dal menu Nuovo connettore personalizzato.

3. Assicurati di aver completato il Passaggio 1, Passaggio 2 e Passaggio 3 in questo articolo.

4. Seleziona la scheda Plug-in IA (anteprima).

5. Nella sezione Manifesto plug-in, inserisci i dettagli per abilitare questo connettore come plugin di intelligenza artificiale.

   

   Campo	Descrzione
   Manifesto plug-in: nome	Nome del plug-in IA.
   Manifesto del plug-in: descrizione	Descrizione del plug-in IA. Ulteriori informazioni: Creare un plug-in IA del connettore (anteprima)
   Manifesto del plug-in: e-mail di contatto	Indirizzo e-mail del contatto per questo plug-in IA.
   Manifesto del plug-in: URL delle informazioni legali	Un luogo accessibile al pubblico in cui vengono pubblicate le informazioni legali relative al tuo plug-in IA.

6. Scorri verso il basso fino alla sezione Dettagli azioni plug-in e inserisci i dettagli dell'azione per ciascuna azione nel plug-in IA del connettore.

   

   Campo	Descrzione
   Dettagli dell'azione del plug-in: riepilogo	Riepilogo di ciascuna azione del plug-in IA che gli utenti possono eseguire.
   Dettagli dell'azione del plug-in: descrizione	Descrizione di ogni azione che gli utenti possono eseguire in merito a questo specifico passaggio dell'azione del plug-in dell'intelligenza artificiale.
   Casella di controllo: abilita come operazione del plug-in copilota	Quando è presente un segno di spunta nella casella di controllo, l'operazione del plug-in IA è abilitata.
   Casella di controllo: conferma utente richiesta?	Quando è presente un segno di spunta nella casella di controllo, è richiesta la conferma dell'utente.

   Suggerimento

   Se hai bisogno di aiuto per definire le tue azioni, attiva l'interruttore editor Swagger.

7. Scorri verso il basso fino alla sezione Parametro e inserisci i dettagli del parametro per il plug-in IA del connettore.

   

   Campo	Descrzione
   Parametro: nome	Nome del parametro. Utilizza nomi identificabili come Identificatore account invece di ID.
   Parametro: descrizione	Descrizione del parametro. Utilizza una spiegazione descrittiva come Data di nascita per un contatto nel formato MM/GG/AAAA invece di b_data. Tali nomi e descrizioni aiutano i LLM (modelli linguistici di grandi dimensioni) a interagire in modo efficace con il plug-in IA.
   Parametro: riepilogo	Informazioni di riepilogo sul parametro.
   Parametro: valore predefinito	Valore predefinito del parametro.

8. nella sezione Richiesta sotto le sezioni plug-in IA (anteprima), seleziona il parametro di input, quindi immetti una descrizione.

Passaggio 5: (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 backend.

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

• Essere scritto in C#.
• Avere un tempo massimo di esecuzione di cinque secondi.
• Avere dimensioni file superiori 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 abilitato.

   Puoi abilitare o disabilitare il codice in qualsiasi momento. Se l'interruttore è Codice disabilitato, il codice verrà 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 6: 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 della connessione, 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 Dati > 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.

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

   

Procedure consigliate (per gli utenti che utilizzano l'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.

Passaggi successivi

Una volta creato un connettore personalizzato e definiti i comportamenti, puoi usarlo da:

• Un flusso
• Un'app
• 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.