Creare un connettore personalizzato da zero

  • Articolo

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.

Nota

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 da zero, usando una raccolta Postman o una definizione OpenAPI che descrive l'operazione della valutazione dell'API di analisi del testo dei Servizi cognitivi di Azure (il nostro esempio per questa serie). Al contrario, descrivi completamente il connettore nella procedura guidata del connettore personalizzato.

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

Nota

Al momento puoi creare da zero un connettore personalizzato in Power Automate e Power Apps. Per le app per la logica, devi iniziare con almeno una definizione OpenAPI di base o una raccolta Postman.

Prerequisiti

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 di intelligenza artificiale

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

Prima di abilitare il connettore come plug-in di intelligenza artificiale, assicurati di comprendere il caso d'uso per gli scenari di plug-in di intelligenza artificiale e di aver esaminato altre considerazioni come supportabilità, procedure consigliate e consigli. Ulteriori informazioni: Creare un plug-in di intelligenza artificiale 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 di intelligenza artificiale (anteprima).

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

    Screenshot dei campi nella pagina Manifesto plug-in.

    Campo Descrzione
    Manifesto plug-in: nome Nome del plug-in di intelligenza artificiale.
    Manifesto del plug-in: descrizione Descrizione del plug-in di intelligenza artificiale. Ulteriori informazioni: Creare un plug-in di intelligenza artificiale del connettore (anteprima)
    Manifesto del plug-in: e-mail di contatto Indirizzo e-mail del contatto per questo plug-in di intelligenza artificiale.
    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 di intelligenza artificiale.

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

    Screenshot dei campi nella pagina Dettagli azione plug-in.

    Campo Descrzione
    Dettagli dell'azione del plug-in: riepilogo Riepilogo di ciascuna azione del plug-in di intelligenza artificiale 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 di intelligenza artificiale è 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 di intelligenza artificiale del connettore.

    Screenshot dei campi nella pagina Parametri.

    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 di intelligenza artificiale.
    Parametro: riepilogo Informazioni di riepilogo sul parametro.
    Parametro: valore predefinito Valore predefinito del parametro.

  8. nella sezione Richiesta sotto le sezioni Plug-in di intelligenza artificiale (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.

Nota

  • Questo passaggio è facoltativo. Puoi completare l'esperienza senza codice per la creazione del connettore ignorando questo passaggio e andando al Passaggio 6: testare il connettore.
  • Il supporto per codice personalizzato è disponibile in anteprima pubblica.

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.

    Screenshot di Carica il tuo codice personalizzato.

    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.

    Screenshot delle azioni e dei trigger Seleziona.

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.

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

      Screenshot di Aggiorna connessione.

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

    Screenshot della risposta del connettore.

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:

È anche possibile condividere un connettore nell'organizzazione 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.