Condividi tramite

Creare un connettore personalizzato da zero

Nota

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 e usando i connettori Copilot e le azioni in Microsoft Copilot Studio. Assicurati di leggere la panoramica dei connettori personalizzati per capire il processo.

Vai a Utilizzare i connettori Power Platform in Copilot Studio per informazioni su come chiamare i connettori come azioni connettore nell'agente Microsoft Copilot.

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 articolo, crei un connettore personalizzato da zero, usando una definizione OpenAPI che descrive l'API Servizi cognitivi di Azure, Analisi del testo, operazione valutazione API (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.

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.

Prerequisiti

Avviare la procedura guidata del connettore personalizzato

  1. Accedi a Power Apps o Power Automate.

  2. Nel riquadro a sinistra seleziona Soluzioni.

  3. Modifica o crea una soluzione non gestita che includerà il tuo connettore personalizzato. Informazioni su come creare una soluzione

  4. Seleziona il menu a discesa Nuovo e seleziona Automazione>Connettore personalizzato.

    Si apre la procedura guidata per un nuovo connettore

  5. Digita il Nome connettore, ad esempio SentimentDemo.

    Completa il resto dei passaggi seguendo le seguenti istruzioni.

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 decidere se il connettore 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.

    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. Nella scheda Definizione, il pannello a sinistra mostra tutte le azioni, i trigger (per App per la logica, Power Automate e Copilot Studio) e i riferimenti definiti per il connettore.

Nota

In questo connettore non sono presenti trigger. Per informazioni sui trigger per i connettori personalizzati, vai a Usare i webhook come trigger per App per la logica di Azure e Power Automate.

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

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

Aggiorna la definizione

Apportiamo alcune modifiche per rendere il connettore più semplice da usare in nelle App per la logica, 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
    Title ID
    Descrzione Identificatore per ciascun documento inviato
    Default value 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
    Title Lingua
    Descrzione Codice di lingua di due o quattro caratteri per il testo
    Default value 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
    Title Testo
    Descrzione Testo da analizzare per la valutazione
    Impostazione predefinita None
    Obbligatorio Sì

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

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

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.

Nota

  • Questo passaggio è facoltativo. Puoi completare l'esperienza senza codice per la creazione del connettore ignorando questo passaggio e andando al Passaggio 5: 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 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.

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

    Screenshot della risposta del connettore.

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.

Passaggi successivi

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

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

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.