Utilizzo di variabili

Le variabili possono esistere a quattro livelli o ambiti:

• Le variabili argomento possono essere utilizzate solo negli 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 agente. Forniscono informazioni più contestuali sulla conversazione o sull'utente. Sono disponibili in tutti gli argomenti.
• Le variabili 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.

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" risulta in un errore.

Quando si testa un agente, una variabile potrebbe apparire temporaneamente come di 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 di creazione 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 sono elencati i tipi di base delle variabili associati alle entità predefinite.

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

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

Ridenominazione di una variabile

Alle variabili viene assegnato automaticamente un nome quando vengono create. Una buona norma è quella di dare alle variabili nomi significativi per chiarirne lo scopo a chiunque debba gestire il tuo 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 salvare l'input dell'utente in una variabile. Tuttavia, potrebbero esserci situazioni in cui si desidera impostare il valore personalmente. 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.

   

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

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 ambiente

Le variabili ambiente sono un Power Platform concetto. 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 Argomento, globali e di sistema. Una differenza notevole è che è possibile utilizzare le variabili di ambiente solo in modalità di sola lettura. Gli autori di agente non possono modificare la variabile ambiente in Copilot Studio. Tuttavia, gli amministratori possono modificare il valore delle variabili di ambiente nel portale PowerApps.

I tipi di variabili di ambiente in Copilot Studio si mappano ai tipi di dati PowerApps come segue:

Non puoi creare o modificare le variabili di ambiente in Copilot Studio. Devi usare il portale PowerApps per modificare o impostare le variabili di ambiente. Da Copilot Studio, puoi usare il riquadro Variabili per visualizzare informazioni su una variabile di ambiente. Il riquadro Variabili ha anche un collegamento per l'esperienza di creazione nativa.

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. Questo è un caso speciale di variabili di ambiente con considerazioni univoche.

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

Oltre alla configurazione riportata sopra, è necessario eseguire le seguenti azioni per autorizzare Copilot Studio a leggere questo insieme di credenziali delle chiavi:

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

2. Per autorizzare tutti gli agenti di ambiente ad accedere al segreto, crea un tag AllowedEnvironments sul segreto e aggiungi gli ID ambiente consentiti separati da virgola.

3. Per autorizzare solo agenti specifici di ambiente a utilizzare questo Key Vault, crea un tag AllowedAgents e inserisci l'identificativo agente nel formato {envId}/{schemaName}. In caso di più valori, separarli con virgole.

Se raggiungi il numero massimo di caratteri ma devi ancora 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.

Variabili di sistema

Ogni agente è 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, fai riferimento ad essa come System.User.DisplayName.

Variabili per l'autenticazione integrata (predefinita)

Le seguenti variabili sono disponibili se hai configurato agente per l'autenticazione con Microsoft. Questo utilizzerà l'autenticazione Entra ID e consentirà solo Teams e i canali PowerApps. Questa è l'impostazione predefinita per i nuovi agenti.

Per ulteriori informazioni, vedere Variabili di autenticazione.

Variabili per l'autenticazione manuale con Generic OAuth 2

Le seguenti variabili sono disponibili se hai configurato agente per utilizzare il provider di servizi Generic OAuth 2.

Variabili per l'autenticazione manuale con Microsoft Entra ID

Le seguenti variabili sono disponibili se hai configurato agente per utilizzare i provider di servizi Microsoft Entra ID (in precedenza Azure Active Directory).

Variabili per agenti abilitati alla voce

Le seguenti variabili sono disponibili solo negli agenti con comando vocale.

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), agente pone all'utente la domanda per inserire il valore della variabile. Se agente ha già acquisito il valore in un precedente argomento, non c'è motivo di porre di nuovo 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, 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 Test agente, se questo argomento viene attivato per primo, chiede all'utente: "Come dovrei chiamarti?". Memorizza il valore in una variabile stringa denominata 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 Test agente, se questo argomento viene attivato per primo, chiede all'utente: "Come ti chiami?". Memorizza il valore in una variabile stringa denominata 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. Aggiungere 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 Redirect e Seleziona la destinazione argomento.

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 ottenute da agente sono quindi disponibili in tutti 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.

Tipo di variabili ed entità

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.

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 degli argomenti del tuo bot e apri il 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 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.

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.