Utilizzare variabili

Importante

Le capacità e funzionalità di Power Virtual Agents ora fanno parte di Microsoft Copilot Studio a seguito di investimenti significativi nell'intelligenza artificiale generativa e integrazioni migliorate in Microsoft Copilot.

Alcuni articoli e schermate potrebbero fare riferimento a Power Virtual Agents durante l'aggiornamento della documentazione e dei contenuti per il training.

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 UserName e il copilota 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.

Applicazione Web

Le variabili possono esistere a tre livelli o ambiti:

• Le variabili Argomento possono essere utilizzate solo all'interno degli argomenti in cui sono state create. Questo è l'ambito predefinito per le variabili create.
• Le variabili Globali possono essere utilizzate in tutti gli argomenti. Puoi modificare l'ambito di una variabile di argomento per renderla una variabile globale.
• Le variabili di sistema vengono create automaticamente con il tuo copilota. Forniscono informazioni più contestuali sulla conversazione o sull'utente. Sono disponibili in tutti gli argomenti.

Tipi di variabili

Una variabile è associata a un tipo di base. Il tipo determina quali valori la variabile può contenere e gli operatori che puoi utilizzare quando crei un'espressione logica con essa.

Type	Descrzione
String	Una sequenza di caratteri utilizzata per rappresentare il testo
Boolean	Un valore logico che può essere solo true o false
Numero	Qualsiasi numero reale
Table	Un elenco di valori, ma tutti i valori devono essere dello stesso tipo
Registra	Una raccolta di coppie nome-valore in cui i valori possono essere di qualsiasi tipo
Data/Ora	Una data, un'ora, un giorno della settimana o un mese relativi a un punto nel tempo
Choice	Un elenco di valori stringa a cui sono associati sinonimi
Vuoto	Un segnaposto per "nessun valore" o "valore sconosciuto"; per ulteriori informazioni, vedi Spazi vuoti in Power Fx

Il tipo di una variabile viene impostato la prima volta che viene assegnato un valore. Dopo ciò, il tipo per quella variabile è fisso e non possono essere assegnati valori di nessun altro tipo. Ad esempio, a una variabile a cui è stato dato il valore iniziale di 1 viene assegnato il tipo Numero. Il tentativo di assegnarlo a un valore Stringa di "apples" genera un errore.

Quando stai testando un copilota, una variabile potrebbe venire visualizzata temporaneamente come tipo sconosciuto. A una variabile sconosciuta non è stato ancora assegnato un valore.

L'ordine delle variabili è determinato dall'alto verso il basso dell'area del contenuto. Vale a dire, i nodi nella parte superiore dell'area del contenuto vengono considerati prima dei nodi nella parte inferiore. Quando crei diramazioni con nodi Condizione, le diramazioni vengono ordinate da sinistra a destra. Vale a dire, i nodi nel ramo più a sinistra vengono considerati prima dei nodi nel ramo più a destra.

Entità

Microsoft Copilot Studio usa le entità per identificare un tipo specifico di informazioni dalle risposte di un utente. Le informazioni identificate vengono salvate in una variabile del tipo appropriato per le informazioni. La tabella seguente elenca il tipo di base variabile associato alle entità predefinite.

Entity	Tipo di base della variabile
Opzioni scelta multipla	Choice
Risposta completa dell'utente	String
Età	Numero
Boolean	Boolean
City	String
Color	String
Continente	String
Paese o area geografica	String
Data e ora	Data/Ora
Indirizzo e-mail	String
Evento	String
Intero	Intero
Lingua	String
Moneta	Numero
Numero	Numero
Ordinale	Numero
Azienda	String
Percentuale	Numero
Nome persona	String
Numero di telefono	String
Punto d'interesse	String
Velocità	Numero
Provincia	String
Via e numero civico	String
Temperatura	Numero
URL	String
Spessore	Numero
CAP	String
Entità personalizzata	Choice

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.

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 il copilota deve ascoltare.

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

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

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

Impostare una variabile

In genere utilizzerai un nodo Domanda per salvare l'input dell'utente in una variabile. Tuttavia, potrebbero esserci situazioni in cui si desidera impostare il valore manualmente. In questi casi, utilizza un nodo Imposta valore variabile.

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

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

   

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

   

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.

Utilizzare valori letterali

Invece di selezionare un valore di variabile, puoi immettere un valore letterale in qualsiasi variabile.

Il nodo tenta di interpretare i valori letterali immessi come tipo stringa, numero o 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 o laddove utilizzi tipi più complessi, utilizza una formula Power Fx per impostare un tipo specifico.

Riquadro Variabili

Il riquadro Variabili è dove puoi visualizzare tutte le variabili disponibili nell'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à variabile.

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

Riquadro Proprietà variabili

Nel riquadro Proprietà variabile puoi rinominare una variabile, vedere dove viene utilizzata o convertirla in una variabile globale. Tuttavia, non puoi riconvertirla da una variabile globale a una variabile argomento. Puoi anche selezionare se può ricevere valori o trasmetterne il valore ad altri argomenti.

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

Variabili di sistema

Ogni copilota è dotato di variabili di sistema integrate che forniscono informazioni aggiuntive su una conversazione.

Non tutte le variabili di sistema sono mostrate nell'elenco. Devi accedere a queste variabili di sistema nascoste con una formula Power Fx.

Per usare le variabili di sistema in una formula Power Fx, devi aggiungere System. prima del nome della variabile. Ad esempio, per includere la variabile di sistema User.DisplayName in una formula, devi fare riferimento ad esso come System.User.DisplayName.

Name	Type	Nascosta	Definizione
Activity.Channel	scelta	visibile	L'ID canale della conversazione corrente
Activity.ChannelData	qualsiasi	nascosto	Un oggetto che contiene contenuto specifico del canale
Activity.ChannelId	string	nascosto	L'ID canale della conversazione corrente, come stringa
Activity.From.Id	string	nascosto	L'ID univoco specifico del canale del mittente
Activity.From.Name	string	nascosto	Il nome descrittivo specifico del canale del mittente
Activity.Name	string	visibile	Il nome dell'evento
Activity.Text	string	visibile	L'ultimo messaggio inviato dall'utente
Activity.Type	scelta	visibile	Tipo di impegno
Activity.TypeId	string	nascosto	Tipo di impegno, come stringa
Activity.Value	qualsiasi	nascosto	Valore aperto
Bot.Name	string	visibile	Il nome del tuo copilota
Channel.DisplayName	string	nascosto	Il nome visualizzato del canale
Conversation.Id	string	visibile	L'ID univoco della conversazione corrente
LastActivity.Id	string	visibile	L'ID dell'impegno inviato in precedenza
LastMessage.Id	string	visibile	L'ID del messaggio precedente inviato dall'utente
LastMessage.Text	string	visibile	Il messaggio precedente inviato dall'utente
Recognizer.TriggerMessage.Id	string	visibile	L'ID del messaggio dell'utente che ha attivato l'argomento corrente
Recognizer.TriggerMessage.Text	string	visibile	Il messaggio dell'utente che ha attivato l'argomento corrente
User.DisplayName	string	visibile	Nome visualizzato dell'utente che ha effettuato l'accesso

Passare le variabili tra argomenti

Quando reindirizzi un argomento a un altro, puoi passare i valori delle variabili tra l'argomento originale e l'argomento di destinazione. 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, in un nodo Domanda), il copilota chiede all'utente di inserire il valore della variabile. Se il valore è già stato acquisito dal copilota 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 il copilota risulta facile e senza problemi.

In questo esempio, utilizzeremo 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 Parare on il cliente salta la domanda. Utilizza invece il valore della variabile passata dall'argomento Formula di saluto.

Ecco il flusso dell'argomento Parla con il cliente:

Come mostrato nel riquadro Testa copilota, se questo argomento viene attivato per primo, chiede all'utente: "Come dovrei chiamarti?" Memorizza il valore in una variabile stringa chiamata userName. Anche la variabile userName è impostata per ottenere il suo valore da altri argomenti. L'argomento si conclude con il messaggio "Spero che tu stia passando una splendida giornata, {userName}!"

Ecco il flusso dell'argomento Formula di saluto:

Come mostrato nel riquadro Testa copilota, se questo argomento viene attivato per primo, chiede all'utente: "Come ti chiami?" Memorizza il valore in una variabile stringa chiamata UserName. L'argomento invia il messaggio "Piacere di conoscerti, {UserName}!" Quindi reindirizza all'argomento Parla con il cliente, che invia il messaggio "Spero che tu stia passando una giornata meravigliosa, {userName}!" Tieni presente, tuttavia, che l'argomento Parla con il cliente argomento ha saltato la nuova richiesta del nome dell'utente. Utilizza invece il valore della variabile passata UserName dall'argomento Formula di saluto.

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

Esaminiamo i passaggi per configurare un argomento in modo da ricevere valori da altri argomenti. Useremo il nostro esempio attuale, ma gli stessi passaggi funzioneranno ogni volta che un argomento deve ottenere un valore da un precedente argomento.

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, è Parla con il cliente.

1. Crea o vai all'argomento di destinazione.

2. Aggiungi un nodo Domanda e immetti What should I call you? per il messaggio.

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

4. Seleziona la variabile per aprirla nel riquadro Proprietà variabili. Denominala userName, quindi seleziona Ricevi valori da altri argomenti.

   

5. Aggiungi un nodo messaggio.

6. Nella casella del messaggio, digita I hope you're having a wonderful day, .

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

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

9. Salva l'argomento.

Configurare l'argomento di origine

L'argomento di origine è l'argomento che esegue il reindirizzamento, quello che fornisce il valore che verrà passato all'argomento di destinazione. In questo esempio, è Formula di saluto.

1. Vai all'argomento di origine.

2. Aggiungi un nodo di reindirizzamento e seleziona l'argomento di destinazione.

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

   

4. Seleziona l'icona > , quindi seleziona la variabile di cui vuoi trasmettere il valore.

   

   Il nodo Reindirizzamento dovrebbe apparire così:

   

5. 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 il copilota ottiene sono pertanto disponibili tra gli argomenti, riducendo la necessità di variabili globali.

Continuiamo con l'esempio dalla sezione precedente. Faremo una nuova domanda nell'argomento Parla con il cliente, quindi restituiremo la risposta all'argomento Formula di saluto.

Configurare l'argomento di origine per una variabile restituita

Quando restituisci una variabile a un argomento, l'argomento di origine è l'argomento a cui viene reindirizzato, quello che fornisce il valore che verrà passato all'argomento originale. In questo esempio, è Parla con il cliente.

1. Vai all'argomento di origine.

2. Aggiungi un nodo Domanda e immetti What city do you live in? per il messaggio.

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

4. Seleziona la variabile per aprirla nel riquadro Proprietà variabili. Denominala userCity, quindi seleziona Restituisci valori agli argomenti originali.

   

5. Salva l'argomento.

Configurare l'argomento di destinazione per una variabile restituita

Quando restituisci una variabile a un argomento, l'argomento di destinazione è l'argomento che esegue il reindirizzamento, quello che riceverà valori da altri argomenti. In questo esempio, è Formula di saluto.

1. Vai all'argomento di destinazione.

2. La variabile selezionata nell'argomento di origine dovrebbe apparire nel nodo Reindirizzamento come variabile di output.

   

3. Salva l'argomento.

Classico

Tipo di variabili ed entità

Microsoft Copilot Studio usa le entità per identificare un tipo specifico di informazioni dalle risposte di un utente. Un tipo di variabile è associato alle informazioni identificate quando vengono salvate. Il tipo di variabile è analogo all'entità.

Ogni entità o tipo di variabile viene mappato su un tipo di base, come elencato nella tabella seguente. Il tipo di base determina gli operatori che puoi utilizzare quando crei un'espressione logica con la variabile corrispondente. Determina anche se puoi fornire una variabile in un flusso o una competenza Bot Framework come parametro di input.

Ad esempio, a tipo di base booleano esegue il mapping a un operatore "è uguale a" con possibili valori True o False. Un tipo di base numero fornisce operatori numerici come "è uguale a", "è maggiore di" o "è maggiore o uguale a" e così via.

Entità	Tipo di base della variabile
Opzioni a scelta multipla	String
Risposta completa dell'utente	String
Età	Numero
Boolean	Boolean
City	String
Color	String
Continente	String
Paese o area geografica	String
Data e ora	String
Durata	String
Indirizzo e-mail	String
Evento	String
Lingua	String
Moneta	String
Numero	String
Ordinale	String
Azienda	String
Percentuale	Numero
Nome persona	String
Numero di telefono	String
Punto d'interesse	String
Velocità	Numero
Provincia	String
Via e numero civico	String
Temperatura	Numero
URL	String
Spessore	Numero
CAP	String
Entità personalizzata	String

Creazione di una variabile

Nel canvas di creazione del bot, aggiungi un nodo domanda. Una variabile viene creata automaticamente nel nodo.

1. Vai alla Pagina Argomenti del bot e apri l'argomento a cui vuoi aggiungere una variabile.

2. Seleziona Aggiungi nodo (+) e seleziona Poni una domanda.

   

   Viene creata automaticamente una variabile che contiene la risposta dell'utente.

   

Scegli un'entità da utilizzare

Per impostazione predefinita, viene creato un nodo domanda con opzioni a scelta multipla. Per utilizzare un'entità predefinita o personalizzata diversa, scegli cosa identificare dal nodo.

Ridenominazione di una variabile

Le variabili create automaticamente hanno un nome predefinito. Per rinominare una variabile, seleziona il nome della variabile, inserisci un nuovo nome e seleziona Fatto.

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 una competenza Bot Framework, puoi inviarla a quel parametro. L'output dei nodi di azione genera nuove variabili.

Utilizzare valori letterali nei nodi di azione

Puoi digitare un valore letterale nel campo di input della variabile in un nodo di azione invece di selezionare una variabile dal menu.

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 Aggiungi nodo (+), quindi Gestione variabili e 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, dovresti analizzare questa risposta e restituire una o più variabili primitive a Microsoft Copilot Studio. Con il nodo Analizza valore, puoi inviare l'intero risultato dell'API come stringa:

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

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.

   

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

   

3. Ora puoi fornire il JSON facendo clic su "Ottieni schema da JSON di esempio". Facendo clic su questo si apre un editor in cui è possibile incollare l'esempio.

   

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

   

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

   

Ora puoi usare la tua nuova variabile. Qui nell'editor Power Fx puoi vedere che ottieni un intellisense completo per le varie proprietà.

Oltre all'analisi delle stringhe JSON, un utilizzo chiave del nodo del Analizza valore sarà per l'analisi di UntypedObjects in fase di esecuzione. Il più comune di queste analisi sarà quando ricevi un evento e devi analizzare il valore dell'evento. Oppure potresti voler analizzare la proprietà System.Activity.ChannelData, che varia in fase di esecuzione in base al canale.

Nell'esempio seguente, se l'evento provenisse da Teams, dovresti utilizzare la documentazione per sviluppatori di Teams per trovare un esempio di come verrà visualizzato l'evento in arrivo e quindi utilizzare i dati di esempio come descritto in questa sezione.

Passaggio di variabili tra argomenti

Quando reindirizzi ad altri argomenti, puoi passare i valori nelle variabili nell'argomento di destinazione o recuperare le variabili da esso. Il passaggio di variabili tra argomenti è particolarmente utile quando si hanno già le informazioni di cui ha bisogno l'argomento. I tuoi utenti apprezzeranno di non dover rispondere di nuovo alla domanda. Questo può essere utile anche per il refactoring e la separazione degli argomenti in componenti riutilizzabili e vuoi passare variabili tra gli argomenti.

Nota

Le variabili di tipo Custom Entity, Date and Time, Duration e Multiple-choice non possono essere passate tra gli argomenti.

Ricevi valori da altri argomenti

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

Per ricevere valori da altri argomenti, imposta la proprietà della variabile:

1. Nel nodo Domanda seleziona la variabile di cui vuoi ricevere valori da altri argomenti.

2. Nel riquadro Proprietà delle variabili, sotto Argomento (ambito limitato) seleziona Ricevi valori da altri argomenti.

   

3. Salva l'argomento.

4. Vai a un argomento a cui vuoi reindirizzare. Segui i passaggi in Reindirizzare a un altro argomento per reindirizzare al corretto argomento.

5. Seleziona + Aggiungi input per l'argomento di destinazione.

   

6. Seleziona una variabile nell'argomento reindirizzato a cui vuoi passare la variabile.

   

7. In Inserisci o seleziona un valore, seleziona la variabile nell'attuale argomento che vuoi passare all'argomento reindirizzato.

   

   La variabile viene mostrata nel nodo reindirizzato.

   

Restituisci valori agli argomenti originali

Quando un argomento pone una domanda (o ottiene in altro modo una variabile da un'azione), questa variabile può essere restituita all'argomento originale che è stato reindirizzato ad essa.

In questo caso, la variabile diventa anche parte dell'argomento originale e può essere utilizzata come qualsiasi altra variabile. Questo ti aiuta a costruire l'argomento in modo che le informazioni ottenute dal bot siano disponibili tra gli argomenti, riducendo la necessità di variabili globali.

Per restituire una variabile all'argomento originale, imposta la proprietà della variabile:

1. Nel nodo Domanda seleziona la variabile di cui vuoi ricevere valori da altri argomenti.

2. Nel riquadro Proprietà delle variabili, sotto Argomento (ambito limitato) seleziona Restituisci valori agli argomenti originali.

   

3. Salva l'argomento.

4. Vai a un argomento a cui vuoi reindirizzare. Segui i passaggi in Reindirizzare a un altro argomento per reindirizzare al corretto argomento.

   La variabile che viene restituita all'argomento viene mostrata nell'argomento reindirizzato. Usa la variabile restituita nel tuo argomento.

   

Uso del riquadro Variabili

Usa il riquadro Variabili per selezionare lo stato di ricezione o restituzione di più variabili contemporaneamente.

1. Nella barra dei menu dell'argomento, seleziona Variabili.

   

2. Per ciascuna delle variabili nell'argomento, seleziona se desideri che i valori vengano passati, ricevuti o entrambi tra gli argomenti.

   

Utilizzo di valori letterali negli input di variabili

Puoi passare valori letterali e variabili a un argomento. Per passare un valore letterale, digita il valore che vuoi utilizzare come input invece di selezionare una variabile.

Argomenti correlati

• Riutilizzare le variabili tra gli argomenti
• Personalizzare l'aspetto di un copilota