Panoramica delle variabili
Le variabili possono esistere a quattro 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 l'agente. Forniscono informazioni più contestuali sulla conversazione o sull'utente. Sono disponibili in tutti gli argomenti.
- Le variabili di ambiente vengono create in Power Platform e sono di sola lettura in Copilot Studio. Archiviano le chiavi e i valori dei parametri, che servono quindi come input per vari altri oggetti dell'applicazione, incluso Copilot Studio. La separazione dei parametri dagli oggetti di consumo consente di modificare i valori all'interno dello stesso ambiente o quando si migrano soluzioni ad altri ambienti. L'alternativa è lasciare i valori dei parametri hardcoded all'interno dei componenti che li utilizzano.
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 con sinonimi associati |
| 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. Se si tenta di assegnarla a un valore Stringa di "apples" viene generato un errore.
Quando si esegue il test di un agente, una variabile potrebbe apparire 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. 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. I nodi nel ramo più a sinistra vengono considerati prima dei nodi nel ramo più a destra.
Entità
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. Nella tabella seguente è elencato il tipo di base della 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 |
Variabili di ambiente
Le variabili di ambiente sono un concetto di Power Platform. Le variabili di ambiente abilitano lo scenario ALM (Application Lifecycle Management) di base per lo spostamento di un'applicazione tra ambienti Power Platform. In questo scenario, l'applicazione rimane esattamente la stessa, ad eccezione di alcuni riferimenti esterni chiave che sono diversi tra l'ambiente di origine e quello di destinazione.
Utilizzare le variabili d'ambiente allo stesso modo delle variabili di sistema, globali e di argomento. Una differenza notevole è che le variabili d'ambiente sono di sola lettura in Copilot Studio. Gli autori dell'agente non possono modificare le variabili di ambiente in Copilot Studio. Tuttavia, gli amministratori possono modificare il valore delle variabili di ambiente in Power Apps. In Copilot Studio, puoi utilizzare il riquadro Variabili per visualizzare informazioni su una variabile d'ambiente. Il pannello Variabili contiene anche un collegamento all'esperienza di creazione nativa.
La versione pubblicata di un agente che utilizza variabili di ambiente ha i valori impostati per queste variabili al momento della pubblicazione dell'agente. Ogni volta che un amministratore aggiorna le variabili di ambiente, è necessario ripubblicare tutti gli agenti che utilizzano tali variabili affinché le modifiche siano effettive in fase di esecuzione. Tuttavia, c'è un'eccezione: non è necessario ripubblicare gli agenti quando cambia il valore di una variabile di ambiente di tipo secret. A differenza di altre variabili d'ambiente, le variabili segrete vengono recuperate in fase di esecuzione.
I tipi di variabili di ambiente in Copilot Studio si mappano ai tipi di dati Power Apps come segue:
| Tipo in Copilot Studio | Tipo in Power Apps |
|---|---|
| Numero decimale | Numero |
| JSON | Rileva il tipo dal valore. Se non è JSON => Non specificato (errore di convalida) |
| Testo | String |
| Sì/No | Boolean |
| Data source | String |
| Segreto | String |
Nota
Gli errori della variabile di ambiente sono visibili nella chat Test e durante la pubblicazione. Tuttavia, questi errori non vengono mostrati nell'elenco Argomento perché non sono variabili di argomento.
Variabili di sistema
Ogni agente è dotato di variabili di sistema integrate che forniscono informazioni aggiuntive su una conversazione.
Nota
Per ulteriori informazioni sulle variabili agente abilitate per la voce, vedere Utilizzare le variabili vocali.
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, fai riferimento ad essa come System.User.DisplayName.
| Name | Type | Definizione |
|---|---|---|
| Activity.Attachments | tabella | I file allegati forniti dall'utente |
| Activity.Channel | scelta | L'ID canale della conversazione corrente |
| Activity.ChannelData | qualsiasi | Un oggetto che contiene contenuto specifico del canale |
| Activity.ChannelId | string | L'ID canale della conversazione corrente, come stringa |
| Activity.From.Id | string | L'ID univoco specifico del canale del mittente |
| Activity.From.Name | string | Il nome descrittivo specifico del canale del mittente |
| Activity.Name | string | Il nome dell'evento |
| Activity.Recipient.Id | string | Proprietà Tipo dell'attività in arrivo. |
| Activity.Recipient.Name | string | Rappresenta il nome visualizzato per l'agente all'interno del canale. Nel contesto del canale telefonico, il valore di questa variabile è il numero di telefono a cui è associato l'agente. |
| Activity.Text | string | L'ultimo messaggio inviato dall'utente |
| Activity.Type | scelta | Tipo di impegno |
| Activity.TypeId | string | Tipo di impegno, come stringa |
| Activity.Value | qualsiasi | Valore aperto |
| Bot.EnvironmentId | string | ID ambiente dell'agente |
| Bot.Id | string | L'ID dell'agente |
| Bot.Name | string | Nome dell'agente |
| Bot.SchemaName | string | Il nome dello schema dell'agente |
| Bot.TenantId | string | ID tenant dell'agente |
| ClientPluginActions | scelta | Raccolta di azioni di plug-in client dinamici da considerare per l'orchestrazione generativa |
| Conversation.Id | string | L'ID univoco della conversazione corrente |
| Conversation.InTestMode | Boolean | Flag booleano che indica se la conversazione si sta svolgendo nella canvas di test |
| Conversation.LocalTimeZone | string | Nome del fuso orario che l'utente dovrà utilizzare nel formato del database fuso orario IANA |
| Conversation.LocalTimeZoneOffset | datetime | Differenza temporale rispetto a UTC per il fuso orario locale corrente |
| Error.Code | string | Codice di errore per l'errore corrente Messaggio di errore definito per l'errore corrente. |
| Error.Message | string | Messaggio di errore definito per l'errore corrente. Nota: questa variabile è supportata solo se il trigger è On Error. |
| FallbackCount | Numero | Questa variabile conta le volte in cui un argomento non è stato abbinato all'input dell'utente. Nota: questa variabile è supportata solo se il trigger è On Unknown Intent. |
| InactivityTimer.Continue | Boolean | Flag booleano che indica se il timer deve essere continuato. Nota: questa variabile è supportata solo se il trigger è Inactivity. |
| InactivityTimer.Count | Numero | Numero di volte in cui il timer OnInactivity è stato attivato a causa dell'inattività dell'utente dopo il tempo configurato. Nota: questa variabile è supportata solo se il trigger è Inactivity. |
| LastMessage.Id | string | L'ID del messaggio precedente inviato dall'utente |
| LastMessage.Text | string | Il messaggio precedente inviato dall'utente |
| Recognizer.ExtractedEntities | scelta | Rappresenta le entità estratte dal messaggio di attivazione. Nota: questa variabile è supportata solo se il trigger è On Select Intent. |
| Recognizer.IntentOptions | scelta | Rappresenta le opzioni di intento quando lo strumento di riconoscimento restituisce risultati ambigui. Nota: questa variabile è supportata solo se il trigger è On Select Intent. |
| Recognizer.SelectedIntent | scelta | Rappresenta l'intento selezionato dal riconoscimento. Nota: questa variabile è supportata solo se il trigger è On Select Intent. |
| Recognizer.TriggeringMessage.Id | string | L'ID del messaggio dell'utente che ha attivato l'argomento corrente |
| Recognizer.TriggeringMessage.Text | string | Il messaggio dell'utente che ha attivato l'argomento corrente |
| Recognizer.MultipleTopicsMatchedReason | string | Utilizzato per determinare il motivo per cui sono stati abbinati più argomenti. Nota: questa variabile è supportata solo se il trigger è On Select Intent. |
| SignInReason | scelta | Utilizzato per determinare quale opzione di accesso è necessaria quando si attiva l'argomento. Nota: questa variabile è supportata solo se il trigger è On Sign In. |
| User.Language | scelta | Questa variabile viene utilizzata per impostare la lingua locale dell'utente per ogni conversazione. |
Variabili per l'autenticazione integrata (predefinita)
Le seguenti variabili sono disponibili per gli agenti configurati per l'autenticazione con Microsoft. Questa configurazione utilizza l'autenticazione di Microsoft Entra ID ed è quella predefinita per i nuovi agenti.
Per altre informazioni, vedere Variabili di autenticazione.
| Name | Type | Definizione |
|---|---|---|
| User.DisplayName | string | Il nome visualizzato dell'utente che sta attualmente parlando con l'agente. |
| User.Email | string | L'indirizzo e-mail dell'utente che sta parlando con il agente. |
| User.FirstName | string | Il nome dell'utente che sta parlando con il agente. |
| User.Id | string | L'ID univoco dell'utente che sta attualmente parlando con l'agente. |
| User.IsLoggedIn | Boolean | Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno. |
| User.LastName | string | Il cognome dell'utente che sta parlando con l'agente. |
| User.PrincipalName | string | Il nome dell'entità utente dell'utente che sta attualmente parlando con l'agente. |
Variabili per l'autenticazione manuale con Generic OAuth 2
Le seguenti variabili sono disponibili per gli agenti configurati per l'utilizzo del provider di servizi Generic OAuth 2.
| Name | Type | Definizione |
|---|---|---|
| User.AccessToken | string | Il token di accesso per l'utente che si autentica con l'agente. |
| User.DisplayName | string | Il nome visualizzato dell'utente che sta attualmente parlando con l'agente. |
| User.Id | string | L'ID univoco dell'utente che sta attualmente parlando con l'agente. |
| User.IsLoggedIn | Boolean | Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno. |
Variabili per l'autenticazione manuale con Microsoft Entra ID
Le seguenti variabili sono disponibili per gli agenti configurati per l'utilizzo di provider di servizi Microsoft Entra ID (in precedenza Azure Active Directory).
| Name | Type | Definizione |
|---|---|---|
| User.AccessToken | string | Il token di accesso per l'utente che si autentica con l'agente. |
| User.DisplayName | string | Il nome visualizzato dell'utente che sta attualmente parlando con l'agente. |
| User.Email | string | L'indirizzo e-mail dell'utente che sta parlando con il agente. |
| User.FirstName | string | Il nome dell'utente che sta parlando con il agente. |
| User.Id | string | L'ID univoco dell'utente che sta attualmente parlando con l'agente. |
| User.IsLoggedIn | Boolean | Flag booleano che indica se l'utente che attualmente sta parlando con il agente è autenticato o meno. |
| User.LastName | string | Il cognome dell'utente che sta parlando con l'agente. |
| User.PrincipalName | string | Il cognome dell'utente che sta parlando con l'agente. |
Variabili per gli agenti con comandi vocali
Le seguenti variabili sono disponibili solo per gli agenti con comandi vocali.
Nota
Per ulteriori informazioni sulle variabili agente abilitate per la voce, vedere Utilizzare le variabili vocali.
| Name | Type | Definizione |
|---|---|---|
| Activity.InputDTMFKeys | string | Valore della chiave DTMF non elaborato ricevuto dalla telefonia. |
| Activity.SpeechRecognition.Confidence | Numero | Punteggio di confidenza per il risultato complessivo dell'ipotesi di Azure Site Recovery, da 0 a 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | string | Testo leggermente formattato del risultato dell'ipotesi di Azure Site Recovery. Ad esempio, "cinquecento dollari". Le parole sono enunciate, ma sono incluse le maiuscole e la punteggiatura di base. |
| Activity.UserInputType | scelta | Tipo di input tratto dall'input più recente dell'utente. Il valore può essere testo, comando vocale o DTMF. |
| Conversation.OnlyAllowDTMF | Boolean | Flag booleano che indica se l'IVR deve essere impostato sulla modalità solo DTMF in fase di esecuzione. |
| Conversation.SipUuiHeaderValue | string | Stringa dell'intestazione UUI utilizzata per passare il contesto all'IVR all'avvio della chiamata. |