Condividi tramite

Utilizzo di variabili

  • Articolo

Puoi usare le variabili per salvare le risposte dei clienti e riutilizzarne il contenuto successivamente nella conversazione.

Puoi anche utilizzare le variabili per creare espressioni logiche che instradino dinamicamente il cliente lungo percorsi di conversazione diversi. Ad esempio, salva il nome di un cliente in una variabile denominata "customerName" e l'agente può rivolgersi al cliente per nome mentre la conversazione continua.

Le variabili possono anche essere passate a e restituite da, altri argomenti e flussi Power Automate.

Creazione di una variabile

Qualsiasi nodo che richiede di selezionare una variabile come output, ad esempio un nodo Domanda, crea automaticamente una variabile di output del tipo appropriato.

Screenshot di un nodo Domanda, con il nome e il tipo della variabile predefinita evidenziati.

Suggerimento

Rinominare i nodi per renderli più facili da identificare. Seleziona il campo del nome del nodo per aggiornare direttamente il nome, oppure seleziona l'icona Altro (…) del nodo e seleziona Rinomina dal menu. Puoi inoltre rinominare i nodi nell'editor del codice.

Non è possibile rinominare i nodi Trigger e i nodi Vai al passaggio.

I nomi dei nodi possono avere una lunghezza massima di 500 caratteri.

Scegli un'entità da utilizzare

I nodi Domanda vengono creati con opzioni a scelta multipla per impostazione predefinita. Per utilizzare un'entità predefinita o personalizzata diversa, seleziona la casella Identifica e scegli il tipo di informazioni che l'agente deve ascoltare.

Screenshot di un nodo Domanda con il pannello

Ridenominazione di una variabile

Alle variabili viene assegnato automaticamente un nome quando vengono create. Una procedura consigliata è assegnare alle variabili nomi significativi per rendere chiaro il loro scopo a chiunque altro debba mantenere l'agente.

  1. Seleziona la variabile per aprirla nel riquadro Proprietà variabili.

  2. Per Nome variabile, inserisci un nuovo nome per la tua variabile.

Impostare una variabile

In genere si utilizza un nodo Domanda per memorizzare l'input dell'utente in una variabile. Tuttavia, potrebbero verificarsi situazioni in cui è necessario impostare il valore di una variabile autonomamente. In questi casi, utilizza un nodo Imposta valore variabile.

  1. Seleziona Aggiungi nodo (+) per aggiungere un nodo, quindi seleziona Gestione variabili>Imposta un valore variabile.

  2. Seleziona la casella in Imposta variabile, quindi seleziona Crea una nuova variabile.

    Screenshot del pulsante Crea una nuova variabile.

    Viene creata una nuova variabile. Il suo tipo è sconosciuto finché non gli assegni un valore.

    Screenshot di un nodo Imposta valore variabile con una nuova variabile di tipo sconosciuto.

  3. Per A valore, assegna un valore tramite una delle opzioni seguenti:

    • Digita un valore letterale.
    • Seleziona una variabile esistente dello stesso tipo. Questa azione imposta la variabile sullo stesso valore della variabile che hai selezionato.
    • Utilizza una formula Power Fx. Le formule Power Fx sono utili per tipi più complessi, in cui non è possibile utilizzare valori letterali, come i tipi Tabella e Record.

Nota

Durante l'impostazione di una variabile di tipo stringa, se si verifica una mancata corrispondenza tra Imposta variabile e A valore, viene visualizzato un messaggio di errore e il pulsante Correggi mancata corrispondenza di tipo. Seleziona il pulsante per far sì che Copilot Studio generi automaticamente una formula Power Fx che risolva la mancata corrispondenza.

Usa le variabili nei nodi di azione

Quando usi una variabile in un nodo azione, se il suo tipo di base corrisponde a un tipo di parametro specificato per un flusso o per una competenza Bot Framework, puoi inviarla a quel parametro. L'output dei nodi di azione genera nuove variabili.

Screenshot di un nodo Azione con parametri di input e output per un'azione di competenza.

Uso di valori letterali per gli input di variabili

Nei nodi in cui è possibile impostare un valore per i parametri di input, è sempre possibile immettere un valore letterale anziché selezionare un'altra variabile come valore.

Screenshot che mostra l'uso di un valore letterale per un parametro di input variabile denominato productName.

Il nodo tenta di interpretare i valori letterali come una stringa, un numero o un booleano. Ad esempio, 123 viene interpretato come un numero. Se invece vuoi che venga interpretato come un valore stringa, puoi racchiudere questo valore tra virgolette, come "123".

Per alcuni scenari (ad esempio, scenari che utilizzano tipi complessi), potrebbe essere necessario utilizzare una formula Power Fx per impostare un tipo specifico.

Usare le variabili di ambiente per i segreti di Azure Key Vault

Una variabile di ambiente può fare riferimento a un segreto nell'insieme di credenziali delle chiavi. Le variabili d'ambiente segrete sono un caso speciale di variabili d'ambiente con considerazioni specifiche.

Per creare una variabile di ambiente segreta nel portale di Power Apps, devi configurarne l'insieme di credenziali delle chiavi.

Per autorizzare la lettura di questo insieme di credenziali delle chiavi da parte di Copilot Studio, è necessario eseguire le seguenti azioni:

  1. Assegna il ruolo Key Vault Secrets User all'applicazione Microsoft Virtual Agents Service.

  2. Per autorizzare tutti gli agenti dall'ambiente ad accedere al segreto, crea un tag AllowedEnvironments nel segreto e aggiungi gli ID ambiente consentiti separati da virgole.

  3. Per autorizzare solo agenti specifici dell'ambiente a usare questo insieme di credenziali delle chiavi, crea un tag AllowedAgents e inserisci l'identificatore agente nel formato {envId}/{schemaName}. In caso di più valori, separarli con virgole.

Se raggiungi il numero massimo di caratteri ma devi comunque aggiungere altri agenti, aggiungi un altro tag con un nome descrittivo ma univoco (ad esempio: AllowedAgents2).

Il valore del segreto viene memorizzato nella cache durante l'esecuzione del dialogo per cinque minuti. Le letture non riuscite vengono memorizzate nella cache per 30 secondi.

Avviso

Aggiungendo il segreto nell'agente, potresti esporre il valore di questo segreto a tutti gli utenti che possono modificare l'agente nell'ambiente perché tali utenti potrebbero modificare l'agente affinché restituisca il valore nel nodo SendMessage.

Riquadro Variabili

Nel riquadro Variabili puoi visualizzare tutte le variabili disponibili per un argomento, indipendentemente dai nodi in cui sono definite o utilizzate. Per ogni variabile, puoi selezionare se può ricevere il suo valore da altri argomenti, restituire il suo valore ad altri argomenti o entrambi. Puoi anche selezionare una variabile per modificarne le proprietà nel riquadro Proprietà variabili.

Per aprire il riquadro Variabili, nella barra dei menu dell'argomento, seleziona Variabili.

Screenshot del riquadro Variabili nell'area del contenuto Copilot Studio, con il pulsante Variabili evidenziato.

Riquadro Proprietà variabili

Nel riquadro Proprietà variabile puoi rinominare una variabile, vedere dove viene utilizzata o convertirla in una variabile globale. Tuttavia, non è possibile riconvertire una variabile globale in una variabile argomento. È anche possibile selezionare se una variabile argomento può ricevere valori da altri argomenti o passarne il valore ad altri.

Per aprire il riquadro Proprietà variabili per una variabile, seleziona la variabile desiderata nel riquadro Variabili. Puoi anche aprire il riquadro Proprietà variabili selezionando una variabile in qualsiasi nodo.

Passare le variabili tra argomenti

Quando si reindirizza un argomento a un altro, è possibile passare i valori delle variabili dall'argomento di origine all'argomento di destinazione e anche restituire valori dall'argomento di destinazione all'argomento di origine. Il passaggio di variabili tra argomenti è particolarmente utile quando un argomento precedente ha già raccolto le informazioni di cui ha bisogno un argomento successivo. I tuoi utenti apprezzeranno di non dover rispondere di nuovo alla stessa domanda.

Ricevi valori da altri argomenti

Quando un argomento definisce una variabile (ad esempio, tramite un nodo Domanda), l'agente chiede all'utente di inserire il valore della variabile. Se il valore è già stato acquisito dall'agente in un argomento precedente, non c'è motivo di porre nuovamente la domanda. Per questi casi, la variabile può essere impostata su Ricevi valori da altri argomenti. Quando un altro argomento reindirizza a questo argomento, può passare il valore di una variabile o un valore letterale in questa variabile e ignorare del tutto la domanda. L'esperienza per l'utente che parla con l'agente è fluida.

In questo esempio utilizziamo due argomenti: Formula di saluto e Parlare con il cliente. Entrambi gli argomenti richiedono il nome del cliente. Tuttavia, se l'argomento Formula di saluto viene eseguito per primo, l'argomento Parlare con il cliente salta la domanda. Invece, utilizza il valore della variabile passata dall'argomento Formula di saluto.

Ecco il flusso dell'argomento Parlare con il cliente:

Screenshot del flusso di conversazione per l'argomento Parla con il cliente.

Come mostrato nel pannello di test, se questo argomento viene attivato per primo, chiede all'utente: "Come devo chiamarti?" Archivia il valore in una variabile stringa chiamata customerName. Anche la variabile customerName è impostata per ottenere il suo valore da altri moduli. Il modulo si conclude con il messaggio: "Spero che tu stia trascorrendo una giornata meravigliosa, customerName."

Ecco il flusso dell'argomento Formula di saluto:

Screenshot del flusso di conversazione per l'argomento Saluto.

Come mostrato nel pannello di test, se questo argomento viene attivato per primo, chiede all'utente: "Come ti chiami?" Archivia il valore in una variabile stringa chiamata customerName. L'argomento invia il messaggio "Piacere di conoscerti, customerName." Quindi reindirizza all'argomento Parlare con il cliente, che invia il messaggio "Spero che tu stia trascorrendo una giornata meravigliosa, customerName." Nota, tuttavia, che l'argomento Parlare con il cliente ha saltato di nuovo la richiesta del nome dell'utente. Invece, utilizza il valore della variabile customerName passata dall'argomento Formula di saluto.

Infine, ecco di nuovo la seconda conversazione, questa volta dal punto di vista dell'argomento Parlare con il cliente:

Screenshot del flusso di conversazione per l'argomento Parla con il cliente quando viene attivato prima l'argomento Saluto.

Esaminiamo i passaggi per configurare un argomento in modo da ricevere valori da altri argomenti. Il nostro scenario di esempio utilizza l'argomento predefinito Formula di saluto come argomento di origine e un nuovo argomento Parlare con il cliente come argomento di destinazione, ma gli stessi passaggi funzionano per qualsiasi argomento che dovrebbe utilizzare un valore da un argomento precedente, se possibile.

Configurare l'argomento di destinazione

L'argomento di destinazione è l'argomento a cui viene reindirizzato, quello che riceverà valori da altri argomenti. Nel nostro esempio, è Parlare con il cliente.

  1. Crea un nuovo argomento e chiamalo "Parla con il cliente".

  2. Aggiungi frasi di attivazione come "parla con me", "parlami", "chatta con me".

  3. Aggiungi un nodo Domanda e inserisci "Come dovrei chiamarti?" per il messaggio.

  4. In Identifica, seleziona l'entità Nome persona predefinita.

  5. Seleziona il nome della variabile. Si apre il riquadro Proprietà variabili.

  6. Sostituisci il nome predefinito con "customerName", quindi seleziona Ricevi valori da altri argomenti.

    Screenshot del pannello 'Proprietà variabili' che mostra la variabile customerName e le sue proprietà.

  7. Aggiungi un nodo messaggio.

  8. Nella casella del messaggio, inserisci "Spero che tu stia trascorrendo una giornata meravigliosa".

  9. Seleziona l'icona Inserisci variabile ({x}), quindi seleziona customerName.

  10. Seleziona lo spazio dopo la variabile e digita "!".

  11. Salva l'argomento.

Configurare l'argomento di origine

L'argomento di origine è l'argomento che esegue il reindirizzamento, quello che fornisce il valore e lo passa all'argomento di destinazione. In questo esempio, è Formula di saluto.

  1. Vai all'argomento Formula di saluto ed elimina i nodi predefiniti, ad eccezione del nodo Trigger.

  2. Aggiungi un nodo Domanda e inserisci "Come ti chiami?" come messaggio.

  3. In Identifica, seleziona l'entità Nome persona predefinita.

  4. Sostituisci il nome predefinito con "customerNameFromGreeting".

  5. Aggiungi un nodo messaggio.

  6. Nella casella del messaggio, inserisci "Piacere di conoscerti,".

  7. Seleziona l'icona Inserisci variabile ({x}), quindi seleziona customerNameFromGreeting.

  8. Seleziona lo spazio dopo la variabile e digita "!".

  9. Aggiungi un nodo Reindirizza e seleziona l'argomento di destinazione Parlare con il cliente.

  10. Seleziona Aggiungi input, quindi seleziona la variabile dall'argomento di destinazione a cui vuoi passare un valore.

    Screenshot dell'argomento Greeting con la variabile customerName aggiunta come input in un nodo di reindirizzamento.

  11. Seleziona l'icona >, quindi seleziona la variabile di cui vuoi passare il valore, customerNameFromGreeting, in questo esempio.

    Il nodo Reindirizza dovrebbe apparire così:

    Screenshot del nodo Reindirizza completato nell'argomento Formula di saluto.

  12. Salva l'argomento.

Restituisci valori agli argomenti originali

Quando un argomento viene reindirizzato e ottiene una variabile ponendo una domanda o in un altro modo, questa variabile può essere restituita all'argomento originale che è stato reindirizzato ad essa. La variabile diventa parte dell'argomento originale e può essere utilizzata come qualsiasi altra variabile. Le informazioni che l'agente ottiene sono pertanto disponibili tra gli argomenti, riducendo la necessità di variabili globali.

Continuiamo con l'esempio dalla sezione precedente. Poniamo una nuova domanda nell'argomento Parlare con il cliente e poi restituiamo la risposta nell'argomento Formula di saluto.

Configurare l'argomento di origine per una variabile restituita

Quando si restituisce una variabile a un argomento, l'argomento di origine è l'argomento che fornisce il valore da restituire all'argomento originale. In questo esempio, l'argomento di origine è Parlare con il cliente.

  1. Vai all'argomento di origine.

  2. Aggiungi un nodo Domanda e inserisci "In quale città vivi?" come messaggio.

  3. In Identifica, seleziona l'entità Città predefinita.

  4. Seleziona la variabile per aprirla nel riquadro Proprietà variabili. Assegnagli il nome "customerCity", quindi seleziona Restituisci valori agli argomenti originali.

    Screenshot dell'argomento Parla con il cliente con la variabile customerCity e le sue proprietà evidenziate.

  5. Aggiungi un nodo messaggio.

  6. Seleziona l'icona Inserisci variabile ({x}), quindi seleziona customerCity.

  7. Dopo la variabile nella casella del messaggio, inserisci "deve essere bellissimo in questo periodo dell'anno.".

  8. Salva l'argomento.

Configurare l'argomento di destinazione per una variabile restituita

Quando si restituisce una variabile a un argomento, l'argomento di destinazione è l'argomento che riceve i valori dall'argomento corrente. Nel nostro esempio, l'argomento di destinazione è Formula di saluto.

  1. Vai all'argomento di destinazione.

  2. La variabile selezionata nell'argomento di origine dovrebbe essere visualizzata sul nodo Reindirizza come variabile di output.

    Screenshot del flusso di conversazione per l'argomento Saluto con una variabile restituita in un nodo Reindirizzamento.

  3. Salva l'argomento.

Nodo Analizza valore

Il nodo Analizza valore consente di convertire un valore di un tipo in un valore di un altro tipo. Quando aggiungi un nodo a un argomento, seleziona l'icona Aggiungi nodo , punta a Gestione variabili e seleziona Analizza valore.

Screenshot del menu per aggiungere un nodo, selezionando Gestione variabili, quindi Analizza valore.

Gli scenari chiave che utilizzano il nodo Analizza valore si concentrano sulla conversione di variabili JSON non elaborate o non tipizzate (il cui valore o struttura non è noto fino al runtime, ad esempio ChannelData) in tipi concreti.

Il processo inizia quando viene chiamato un flusso, che a sua volta chiama un'API. L'API restituisce un risultato. In genere, è necessario analizzare questa risposta e restituire una o più variabili primitive. Con il nodo Analizza valore, puoi inviare l'intero risultato dell'API come stringa. Ad esempio: 

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

La variabile di stringa che hai ora può essere convertita in una variabile di record, con il supporto completo di Intellisense in Power Fx, utilizzando questo nuovo nodo. Un esempio che utilizza dati aiuterà a illustrare questo processo.

Esempio di utilizzo del nodo Analizza valore

  1. Aggiungi un nodo Analizza valore e seleziona la variabile che vuoi analizzare.

    Screenshot che mostra la selezione di la variabile da analizzare.

  2. Seleziona il tipo di dati. In questo caso scegli Dai dati di esempio.

    Screenshot che mostra la selezione del tipo di dati per un nodo Analizza valore.

  3. Seleziona Ottieni schema da JSON di esempio e inserisci l'esempio JSON desiderato nell'editor che si apre.

    Screenshot che mostra Ottieni schema da JSON di esempio.

  4. Infine, specifica in quale variabile desideri inserire il valore analizzato. Di solito creeresti una nuova variabile per questo.

    Screenshot che mostra la selezione di una variabile di destinazione per un valore analizzato.

    Nota che la variabile di output è ora del tipo corretto: Record.

    Lo screenshot che mostra la variabile di destinazione per i dati analizzati ha il tipo desiderato: Record.

Oltre all'analisi delle stringhe JSON, un utilizzo fondamentale del nodo Analizza valore è l'analisi di UntypedObjects al momento del runtime. Il caso d'uso più comune è quando si riceve un evento e si ha la necessità di analizzarne il valore. Oppure potresti voler analizzare la proprietà System.Activity.ChannelData, che varia in fase di esecuzione in base al canale.

Per analizzare le informazioni di un evento proveniente da Teams, è necessario utilizzare la documentazione per sviluppatori di Teams per trovare un esempio di come potrebbe apparire l'evento previsto e quindi utilizzare questo esempio come dati campione, come descritto in precedenza in questa sezione.

Contenuto correlato