Usar variáveis

Importante

As capacidades e os recursos do Power Virtual Agents agora fazem parte do Microsoft Copilot Studio após investimentos significativos em IA generativa e integrações aprimoradas no Microsoft Copilot.

Alguns artigos e capturas de tela podem fazer referência ao Power Virtual Agents enquanto atualizamos a documentação e o conteúdo do treinamento.

Você pode usar variáveis para salvar respostas dos clientes e reutilizar seu conteúdo posteriormente na conversa.

Você também pode usar variáveis para criar expressões lógicas que direcionam dinamicamente o cliente por diferentes caminhos de conversa. Por exemplo, salve o nome de um cliente em uma variável chamada UserName, e o copiloto pode se dirigir ao cliente pelo nome enquanto a conversa continua.

As variáveis também podem ser passadas e retornadas de Outros tópicos e fluxos do Power Automate.

Aplicativo Web

As variáveis podem existir em três níveis, ou escopos:

• Tópico: as variáveis de tópico só podem ser referenciadas dentro dos tópicos em que são criadas. Este escopo é o padrão para as variáveis que você cria.
• Variáveis globais podem ser usadas em todos os tópicos. Você pode alterar o escopo de qualquer variável de tópico para torná-la uma variável global.
• As variáveis do sistema são criadas automaticamente com seu copiloto. Eles fornecem informações mais contextuais sobre a conversa ou o usuário. Elas estão disponíveis em todos os tópicos.

Tipos de variáveis

Uma variável está associada a um tipo base. O tipo determina quais valores a variável pode conter e os operadores que você pode usar ao criar uma expressão lógica com a variável correspondente.

Tipo	Descrição
Cadeia de caracteres	Uma sequência de caracteres usada para representar texto
Booliano	Um valor lógico que só pode ser true ou false
Número	Qualquer número real
Tabela	Uma lista de valores, mas todos os valores devem ser do mesmo tipo
Registro	Uma coleção de pares nome-valor em que os valores podem ser de qualquer tipo
DateTime	Uma data, hora, dia da semana ou mês em relação a um ponto no tempo
Opção	Uma lista de valores de cadeia de caracteres que têm sinônimos associados
Em branco	Um espaço reservado para "sem valor" ou "valor desconhecido"; para mais informações, consulte Espaços em Power Fx

O tipo de uma variável é definido na primeira vez que um valor é atribuído. Depois disso, o tipo para essa variável é fixo e não podem ser atribuídos valores de nenhum outro tipo. Por exemplo, uma variável com o valor inicial de 1, recebe o tipo Número. A tentativa de atribuir um valor de Cadeira de caracteres de "apples" resultará um erro.

Ao testar um copiloto, uma variável pode aparecer temporariamente como o tipo desconhecido. Uma variável desconhecida ainda não recebeu um valor.

A ordem das variáveis é determinada de cima para baixo na tela de autoria. Ou seja, os nós na parte superior da tela de autoria são considerados antes dos nós na parte inferior. Quando você cria ramificações com nós Condição, as ramificações são ordenadas da esquerda para a direita. Ou seja, os nós do ramo mais à esquerda são considerados antes dos nós do ramo mais à direita.

Entidades

O Microsoft Copilot Studio usa entidades para identificar um tipo específico de informação das respostas de um usuário. As informações identificadas são salvas em uma variável do tipo apropriado para as informações. A tabela a seguir lista o tipo de base variável associado a entidades predefinidas.

Entidade	Tipo base variável
Opções de múltipla escolha	Opção
Resposta completa do usuário	Cadeia de caracteres
Idade	Número
Booliano	Booliano
Cidade	Cadeia de caracteres
Cor	Cadeia de caracteres
Continente	Cadeia de caracteres
País ou região	Cadeia de caracteres
Data e hora	DateTime
Email	Cadeia de caracteres
Evento	Cadeia de caracteres
Inteiro	Inteiro
Linguagem	Cadeia de caracteres
Quantia	Número
Número	Número
Ordinal	Número
Organização	Cadeia de caracteres
Porcentagem	Número
Nome da pessoa	Cadeia de caracteres
Número do telefone	Cadeia de caracteres
Ponto de interesse	Cadeia de caracteres
Velocidade	Número
Estado	Cadeia de caracteres
Endereço	Cadeia de caracteres
Temperatura	Número
URL	Cadeia de caracteres
Peso	Número
CEP	Cadeia de caracteres
Entidade personalizada	Opção

Criar uma variável

Qualquer nó que solicite que você selecione uma variável como saída, como um nó Pergunta, automaticamente cria uma variável de saída do tipo apropriado.

Escolha uma entidade para usar

Pergunta Os nós são criados com opções de múltipla escolha por padrão. Para usar uma entidade pré-criada ou personalizada diferente, selecione a caixa Identificar e escolha o tipo de informação que o copiloto deve escutar.

Renomear uma variável

As variáveis criadas automaticamente recebem um nome padrão ao ser criadas. Uma prática recomendada é dar nomes significativos às suas variáveis para deixar sua finalidade clara para qualquer outra pessoa que precise manter seu copiloto.

1. Selecione a variável que você quer abrir no painel de propriedades da variável.

2. Para Nome variável, insira um novo nome para sua variável.

Definir uma variável

Geralmente, você usará um nó de Pergunta para salvar a entrada do usuário em uma variável. Pode haver situações em que você mesmo deseja definir o valor. Nesses casos, use um nó Definir valor variável.

1. Selecione Adicionar nó (+) para adicionar um nó, e então selecionar Defina um valor variável.

2. Selecione a caixa em Definir variável, e então selecione Criar uma nova variável.

   

   Uma nova variável é criada. Seu tipo é desconhecido até que você atribua um valor a ele.

   

3. Para Valor de destino, atribua um valor usando uma das seguintes opções:

   • Digite um valor literal
   • Selecione uma variável existente do mesmo tipo. Esta ação define sua variável com o mesmo valor da variável que você selecionar.
   • Usar uma fórmula do Power Fx. As fórmulas do Power Fx são úteis para tipos mais complexos onde os valores literais não podem ser usados, tais como os tipos Tabela e Registro.

Usar valores literais

Em vez de selecionar um valor variável, você pode inserir um valor literal em qualquer variável.

O nó tenta interpretar valores literais como um fio, um número, ou um tipo booleano. Por exemplo, 123 é interpretado como um número. Se você quiser que ele seja interpretado como um valor de cadeia, você pode embrulhar o valor em aspas duplas, como esta: "123".

Para alguns cenários, ou onde você estiver usando tipos mais complexos, use uma fórmula do Power Fx para definir um tipo específico.

Painel de variáveis

No painel Variáveis, você pode visualizar todas as variáveis disponíveis no tópico, independentemente de quais nós são definidas ou usadas. Para cada variável, você pode selecionar se ela pode receber seu valor de outros tópicos, retornar seu valor para outros tópicos ou ambos. Você também pode selecionar uma variável para editar suas propriedades no painel Propriedades de variável.

Para abrir o painel Variáveis, na barra de menu do tópico, selecione Variáveis.

Painel de propriedades da Variável

No painel Propriedades variáveis, você pode renomear uma variável, ver onde ela é usada, ou convertê-la em uma variável global. No entanto, você não pode convertê-lo de uma variável global de volta para uma variável de tópico. Você também pode selecionar se pode receber valores ou passar seu valor para outros tópicos.

Para abrir o painel Propriedades de variável, selecione uma variável no Variáveis. Você também pode abrir o painel Propriedades de variável selecionando uma variável em qualquer nó.

Variáveis do sistema

Cada copiloto vem com variáveis de sistema integradas que fornecem informações adicionais sobre uma conversa.

Nem todas as variáveis do sistema são mostradas na lista. Você deve acessar essas variáveis de sistema ocultas com uma fórmula do Power Fx.

Se você quiser usar variáveis do sistema em uma fórmula do Power Fx, você deve adicionar System. antes do nome. Por exemplo, para incluir a variável de sistema User.DisplayName em uma fórmula, você precisa se referir a ela como System.User.DisplayName.

Nome	Tipo	Oculto	Definição
Activity.Channel	opção	visível	O ID do canal da conversa atual
Activity.ChannelData	qualquer	oculto	Um objeto que contém conteúdo específico do canal
Activity.ChannelId	cadeia	oculto	O ID do canal da conversa atual, como uma cadeia de caracteres
Activity.From.Id	cadeia	oculto	ID exclusivo específico do canal para o remetente
Activity.From.Name	cadeia	oculto	Nome amigável do remetente específico do canal
Activity.Name	cadeia	visível	O nome do evento
Activity.Text	cadeia	visível	A mensagem mais recente enviada pelo usuário
Activity.Type	opção	visível	Tipo de atividade
Activity.TypeId	cadeia	oculto	Tipo de atividade, como uma cadeia de caracteres
Activity.Value	qualquer	oculto	Valor em aberto
Bot.Name	cadeia	visível	O nome do seu copiloto
Channel.DisplayName	cadeia	oculto	Exibe o nome do canal
Conversation.Id	cadeia	visível	O ID exclusivo da conversa atual
LastActivity.Id	cadeia	visível	ID da atividade enviada anteriormente
LastMessage.Id	cadeia	visível	ID da mensagem anterior enviada pelo usuário
LastMessage.Text	cadeia	visível	A mensagem anterior enviada pelo usuário
Recognizer.TriggerMessage.Id	cadeia	visível	ID da mensagem do usuário que acionou o tópico atual
Recognizer.TriggerMessage.Text	cadeia	visível	Mensagem do usuário que acionou o tópico atual
User.DisplayName	cadeia	visível	O nome de exibição do usuário

Passando variáveis entre tópicos

Ao redirecionar um tópico para outro, você pode passar os valores das variáveis entre o tópico original e o tópico de destino. A passagem de variáveis entre tópicos é especialmente útil quando você já tem informações de que o tópico precisa. Seus usuários vão gostar de não ter que responder à pergunta novamente.

Receber valores de outros tópicos

Quando um tópico define uma variável (por exemplo, em um nó de Pergunta), o copiloto faz a pergunta ao usuário para preencher o valor da variável. Se o valor já tiver sido adquirido pelo copiloto em um tópico anterior, não há motivo para fazer a pergunta novamente. Nesses casos, essa variável pode ser definida como Receber valores de outros tópicos. Quando outro tópico redirecionar para este, ele poderá então passar uma variável (ou valores literais) nesta variável e ignorará a questão completamente. A experiência do usuário ao falar com o copiloto é simples.

Neste exemplo, usaremos dois tópicos, Cumprimentar e Falar com o Cliente. Ambos os tópicos pedem o nome do cliente. No entanto, se o tópico Saudação for executado primeiro, o tópico Falar com o cliente pula sua pergunta. Em vez disso, ele usa o valor da variável passada do tópico Saudação.

Aqui está o fluxo do tópico Fale com o cliente:

Conforme mostrado no painel Testar copiloto, se este tópico for acionado primeiro, ele perguntará ao usuário: "Como devo chamá-lo?" Ele armazena o valor em uma variável de string chamada userName. A variável userName também é definida para obter seu valor de outros tópicos. O tópico termina com a mensagem: "Espero que você esteja tendo um dia maravilhoso, {userName}!"

Aqui está o fluxo do tópico Fale com o cliente:

Conforme mostrado no painel Testar copiloto, se este tópico for acionado primeiro, ele perguntará ao usuário: "Qual é o seu nome?" Ele armazena o valor em uma variável de string chamada UserName. O tópico envia a mensagem "Prazer em conhecê-lo, {UserName}!" Em seguida, ele redireciona para o tópico Fale com o cliente, que envia a mensagem: "Espero que você esteja tendo um dia maravilhoso, {userName}!" Observe, no entanto, que o tópico Fale com o cliente pulou solicitando o nome do usuário novamente. Em vez disso, ele usa o valor da variável UserName passada do tópico Saudação.

Por fim, aqui está a segunda conversa novamente, desta vez sob a perspectiva do tópico Fale com o cliente:

Vamos percorrer as etapas para configurar um tópico para receber valores de outros tópicos. Usaremos nosso exemplo atual, mas as mesmas etapas funcionarão sempre que um tópico precisar obter um valor de um tópico anterior.

Configurar o tópico de destino

O tópico de destino é o tópico para o qual está sendo redirecionado, aquele que receberá valores de outros tópicos. No nosso exemplo, é Fale com o Cliente.

1. Crie ou vá para o tópico de destino.

2. Adicione um nó Pergunta e insira What should I call you? na mensagem.

3. Em Identificar, selecione a entidade predefinida Nome da pessoa.

4. Selecione a variável que você quer abrir no painel Propriedades de variável. Nomeie-o userName e selecione Receber valores de outros tópicos.

   

5. Adicione um nó Mensagem.

6. Na caixa de mensagens, digite I hope you're having a wonderful day, .

7. Selecione o ícone Inserir variável ({x}), e então selecione userName.

8. Selecione o espaço após a variável e digite !.

9. Salve o tópico.

Configurar a fonte de dados

O tópico de origem é o tópico que faz o redirecionamento, aquele que fornece o valor que será passado para o tópico de destino. Em nosso exemplo, ela é Greeting.

1. Ir para o tópico da fonte.

2. Adicionar um nó redirecionado e selecione o tópico de destino.

3. Selecione + Adicionar entrada, e então selecione a variável do tópico de destino para o qual você deseja passar um valor.

   

4. Selecione o ícone > e, em seguida, selecione a variável cujo valor você deseja passar.

   

   O nó redirecionado deve ter este aspecto:

   

5. Salve o tópico.

Retornar valores aos tópicos originais

Quando um tópico é redirecionado e obtém uma variável fazendo uma pergunta ou de alguma outra forma, a variável pode ser retornada ao tópico original. a variável também passa a fazer parte do tópico original e pode ser usada como qualquer outra variável. As informações obtidas pelo copiloto ficam disponíveis em todos os tópicos, reduzindo a necessidade de variáveis globais.

Vamos continuar com o exemplo da seção anterior. Faremos uma nova pergunta no tópico Fale com o Cliente, e então retornaremos a resposta para o tópico Saudação.

Configure o tópico de origem para uma variável retornada

Quando você está retornando uma variável para um tópico, o tópico de origem é o tópico para o qual está sendo redirecionado, aquele que fornece o valor que será passado de volta para o tópico original. Neste exemplo, é Fale com o cliente.

1. Ir para o tópico da fonte.

2. Adicione um nó Pergunta e insira What city do you live in? na mensagem.

3. Em Identificar, selecione a entidade predefinida Cidade.

4. Selecione a variável que você quer abrir no painel Propriedades de variável. Nomeie-o userCity e selecione Receber valores de outros tópicos.

   

5. Salve o tópico.

Configure o tópico de destino para uma variável retornada

Quando você está retornando uma variável para um tópico, o tópico de destino é o tópico que está fazendo o redirecionamento, aquele que receberá valores de outros tópicos. Em nosso exemplo, ela é Greeting.

1. Ir para o tópico de destino.

2. A variável selecionada no tópico de origem deve aparecer no nó Redirecionar como uma variável de saída.

   

3. Salve o tópico.

Clássico

Entidade e tipo de variável

O Microsoft Copilot Studio usa entidades para identificar um tipo específico de informação das respostas de um usuário. Um tipo de variável é associado às informações identificadas quando ele é salvo. O tipo de variável é análogo à entidade.

Cada entidade ou tipo de variável é mapeado para um tipo base, conforme listado na tabela a seguir. O tipo base determina os operadores que você pode usar ao construir uma expressão lógica com a variável correspondente. Também determina se você pode alimentar uma variável para um fluxo ou habilidade do Bot Framework como parâmetro de entrada.

Por exemplo, um tipo base booliano mapeia um operador "é igual a" no qual os valores possíveis são True ou False. Um tipo base número fornece operadores numéricos como "é igual a", "é maior que" ou "é maior ou igual a" e assim por diante.

Entidade	Tipo base variável
Opções de múltipla escolha	Cadeia de caracteres
Resposta completa do usuário	Cadeia de caracteres
Idade	Número
Booliano	Booliano
Cidade	Cadeia de caracteres
Cor	Cadeia de caracteres
Continente	Cadeia de caracteres
País ou região	Cadeia de caracteres
Data e hora	Cadeia de caracteres
Duração	Cadeia de caracteres
Email	Cadeia de caracteres
Evento	Cadeia de caracteres
Linguagem	Cadeia de caracteres
Quantia	Cadeia de caracteres
Número	Cadeia de caracteres
Ordinal	Cadeia de caracteres
Organização	Cadeia de caracteres
Porcentagem	Número
Nome da pessoa	Cadeia de caracteres
Número do telefone	Cadeia de caracteres
Ponto de interesse	Cadeia de caracteres
Velocidade	Número
Estado	Cadeia de caracteres
Endereço	Cadeia de caracteres
Temperatura	Número
URL	Cadeia de caracteres
Peso	Número
CEP	Cadeia de caracteres
Entidade personalizada	Cadeia de caracteres

Criar uma variável

Na tela de criação de bot, adicione um nó de pergunta. Uma variável é criada automaticamente no nó.

1. Vá para a Página de tópicos do seu bot e abra o tópico ao qual você deseja adicionar uma variável.

2. Selecione Adicionar nó (+) e Fazer uma pergunta.

   

   Uma variável que contém a resposta do usuário é criada automaticamente.

   

Escolha uma entidade para usar

Por padrão, um nó de pergunta é criado com opções de múltipla escolha. Para usar uma entidade pré-criada ou personalizada diferente, escolha o que identificar no nó.

Renomear uma variável

As variáveis criadas automaticamente vêm com um nome padrão. Para renomear uma variável, selecione o nome da variável, insira um novo nome e selecione Concluído.

Usar variáveis em nós de ação

Ao usar uma variável em um nó de ação, se seu tipo base corresponder a um tipo de parâmetro especificado para um fluxo ou habilidade do Bot Framework, você pode alimentá-lo para esse parâmetro. A saída dos nós de ação gera novas variáveis.

Usar valores literais em nós de ação

Você pode digitar um valor literal no campo de entrada de variável em um nó de ação em vez de selecionar uma variável no menu.

Nó Analisar Valor

O nó Analisar Valor permite que você converta um valor de um tipo em um valor de outro tipo. Ao adicionar um nó a um tópico, selecione Adicionar nó (+), depois Gerenciamento de variável e Analisar Valor.

Os principais cenários usando o nó Analisar Valor concentram-se na conversão de JSON bruto ou variáveis sem tipo (cujos valores ou estruturas não sejam conhecidos até o tempo de execução; por exemplo, ChannelData) em tipos concretos.

O processo começa quando um Fluxo é chamado, que por sua vez , chama uma API. A API retorna um resultado. Normalmente, você precisaria analisar essa resposta e retornar uma ou mais variáveis primitivas ao Microsoft Copilot Studio. Com o nó Analisar Valor, você pode enviar todo o resultado da API como uma cadeia de caracteres:

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

A variável de cadeia de caracteres que você tem agora poderá ser convertida em uma variável Registro, com suporte do IntelliSense completo no Power Fx, usando este novo nó. Um exemplo usando dados de exemplo ajudará a ilustrar esse processo.

Exemplo de uso do nó Analisar Valor

1. Adicione um nó Analisar Valor selecione a variável que deseja analisar.

   

2. Selecione o tipo de dados. Nesse caso, escolha "Dos Dados de Exemplo".

   

3. Agora você pode fornecer o JSON clicando em 'Obter Esquema do JSON de Exemplo'. Clicar nisso abre um editor em que você poderá colar o exemplo.

   

4. Por fim, especifique em qual variável você deseja colocar o valor analisado. Normalmente você criaria uma nova variável para isso.

   

   Observe que a variável de saída agora é do tipo correto: Registro.

   

Agora você pode usar a nova variável. Aqui no editor do Power Fx, você pode ver que obtém o IntelliSense completo para as várias propriedades.

Além de analisar cadeias de caracteres JSON, um uso importante do nó Analisar Valor será para analisar UntypedObjects em tempo de execução. O mais comum deles será quando você receber um Evento e precisar analisar o valor dele. Ou talvez você queira analisar a propriedade System.Activity.ChannelData, que varia em tempo de execução por canal.

No exemplo a seguir, se o evento vier do Teams, você precisará usar a documentação do desenvolvedor do Teams para encontrar um exemplo de como será o evento de entrada e usar os dados de exemplo conforme descrito nesta seção.

Passando variáveis entre tópicos

Ao redirecionar para outros tópicos, você pode passar valores para variáveis no tópico de destino ou obter variáveis dele. A passagem de variáveis entre tópicos é especialmente útil quando você já tem informações de que o tópico precisa. Seus usuários vão gostar de não ter que responder à pergunta novamente. Isso também pode ser útil quando você refatora e separa seus tópicos em componentes reutilizáveis e você quer passar variáveis entre os tópicos.

Nota

Variáveis do tipo Custom Entity, Date and Time, Duration e Multiple-choice não podem ser passadas entre os tópicos

Receber valores de outros tópicos

Quando um tópico define uma variável (por exemplo, por um nó de pergunta), o bot faz a pergunta ao usuário para preencher o valor da variável. Se o valor já tiver sido adquirido pelo bot, não há motivo para fazer a pergunta novamente. Nesses casos, essa variável pode ser definida como Receber valores de outros tópicos. Quando outro tópico redirecionar para este, ele poderá então passar uma variável (ou valores literais) nesta variável e ignorará a questão completamente. A experiência para o usuário que está conversando com o bot é descomplicada.

Para receber valores de outros tópicos, defina a propriedade da variável:

1. No nó Pergunta, selecione a variável que você que que receba valores de outros tópicos.

2. No painel Propriedades das variáveis, em Tópico (escopo limitado), selecione Receber valores de outros tópicos.

   

3. Salve o tópico.

4. Vá para um tópico para o qual você deseja redirecionar. Siga os passos em Redirecionar para outro tópico para redirecionar para o tópico correto.

5. Selecione + Adicionar entrada ao tópico de destino.

   

6. Selecione a variável no tópico redirecionado para o qual você quer passar a variável.

   

7. Em Inserir ou selecionar um valor, selecione a variável no tópico atual que você quer passar para o tópico redirecionado.

   

   A variável é mostrada no nó redirecionado.

   

Retornar valores aos tópicos originais

Quando um tópico faz uma pergunta ou obtém a variável de uma ação de alguma outra forma, essa variável pode ser retornada ao tópico original que redirecionou para ela.

Nesse caso, a variável também passa a fazer parte do tópico original e pode ser usada como qualquer outra variável. Isso ajuda você a construir o tópico para que as informações obtidas pelo bot estejam disponíveis em todos os tópicos, reduzindo a necessidade de variáveis globais.

Para retornar uma variável ao tópico original, defina a propriedade da variável:

1. No nó Pergunta, selecione a variável que você que que receba valores de outros tópicos.

2. No painel Propriedades das variáveis, em Tópico (escopo limitado), selecione Retornar valores para os tópicos originais.

   

3. Salve o tópico.

4. Vá para um tópico para o qual você deseja redirecionar. Siga os passos em Redirecionar para outro tópico para redirecionar para o tópico correto.

   A variável que está sendo retornada ao tópico é exibida no tópico redirecionado. Use a variável retornada em seu tópico.

   

Usando o painel de variáveis

Use o painel Variáveis para selecionar o status de recebimento ou de retorno de várias variáveis de uma vez.

1. Na barra de menu do tópico, selecione Variáveis.

   

2. Selecione se deseja que os valores sejam passados, recebidos ou ambos entre os tópicos para cada uma das variáveis no tópico.

   

Usando valores literais em entradas de variável

Você pode passar valores literais, bem como variáveis para um tópico. Para passar um valor literal, digite o valor que deseja usar como entrada em vez de selecionar uma variável.

Tópicos relacionados

• Reutilizar variáveis entre tópicos
• Personalizar a aparência do seu copiloto