Trabalhar com variáveis

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 agente 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 quatro níveis, ou escopos:

• tópico As variáveis só podem ser usadas nos tópicos em que foram 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.
• Variáveis de sistema são criadas automaticamente com seu agente. Eles fornecem informações mais contextuais sobre a conversa ou o usuário. Elas estão disponíveis em todos os tópicos.
• Variáveis de ambiente são criadas em Power Platform e são somente leitura em Copilot Studio. Elas armazenam as chaves e os valores dos parâmetros, que servem como entrada para diversos outros objetos do aplicativo, incluindo o Copilot Studio. Separar os parâmetros dos objetos de consumo permite alterar os valores dentro do mesmo ambiente ou ao migrar soluções para outros ambientes. A alternativa é deixar os valores dos parâmetros embutidos em código nos componentes que os utilizam.

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 com 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. Tentar atribuí-lo a um valor String de "apples" resulta em erro.

Ao testar um agente, 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. Os nós na parte superior da tela de criação 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. Os nós no ramo mais à esquerda são considerados antes dos nós no ramo mais à direita.

Entidades

O 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 às entidades pré-criadas.

Entity	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.

Dica

Renomeie os nós para torná-los mais fáceis de identificar. Select o campo de nome do nó para atualizar o nome diretamente ou selecione o ícone Mais (...) do nó e selecione Renomear no menu. Você também pode renomear nós no editor de código.

Não é possível renomear os nós de Gatilho e os nós Ir para etapa.

Os nomes do nó podem ter até 500 caracteres.

Escolha uma entidade para usar

Os nós de pergunta são criados com opções de múltipla escolha por padrão. Para usar uma entidade pré-criada ou personalizada diferente, Select marque a caixa Identificar e escolha o tipo de informação que o agente 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 agente.

1. Selecione a variável para abri-la no painel Propriedades da variável.

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

Definir uma variável

Normalmente, você usa um nó Pergunta para salvar a entrada do usuário em uma variável. No entanto, There pode ser uma situação 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 Gerenciamento de variáveis>Definir um valor de 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.

Observação

Ao definir uma variável do tipo string, se você encontrar uma incompatibilidade entre Definir variável e Para valor, uma mensagem de erro e o botão Corrigir incompatibilidade de tipo serão exibidos. Select o botão para Copilot Studio gerar automaticamente uma Power Fx fórmula que resolva a incompatibilidade.

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 uma cadeia de caracteres, um número ou um booliano. 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 da variável, selecione uma variável no painel Variáveis. Você também pode abrir o painel Propriedades de variável selecionando uma variável em qualquer nó.

Variáveis de ambiente

Variáveis de ambiente são um Power Platform conceito. As variáveis de ambiente permitem o cenário básico de gerenciamento do ciclo de vida do aplicativo (ALM) de mover um aplicativo entre ambientes da Power Platform. Nesse cenário, o aplicativo permanece exatamente o mesmo, exceto por algumas referências externas importantes que são diferentes entre o ambiente de origem e o ambiente de destino.

Use as variáveis do Ambiente da mesma forma que as variáveis de Tópico, Globais e do Sistema. Uma diferença notável é que você só pode usar variáveis de ambiente no modo somente leitura. Os autores do agente não podem modificar a variável de ambiente em Copilot Studio. No entanto, os administradores podem alterar o valor das variáveis de ambiente no portal do PowerApps.

Os tipos de variáveis de ambiente no mapa do Copilot Studio para tipos de dados do PowerApps da seguinte maneira:

Digite no Copilot Studio	Digite no PowerApps
Número decimal	Número
JSON	Detecte o tipo a partir do valor. Se não for Json => Não especificado (erro de validação)
Texto	cadeia
Sim/Não	Boolean
Fonte de dados	cadeia
Segredo	String

Observação

Erros de variável de ambiente são visíveis no chat de Teste e durante a publicação. No entanto, esses erros não são mostrados na lista de Tópicos porque eles não são variáveis de tópico.

Não é possível criar ou editar variáveis de ambiente no Copilot Studio. Você deve usar o portal do PowerApps para alterar ou definir variáveis de ambiente. No Copilot Studio, você pode usar o painel Variáveis para ver informações sobre uma variável de ambiente. O painel Variáveis também possui um link para a experiência de criação nativa.

Usar variáveis de ambiente em segredos do Azure Key Vault

Uma variável de ambiente pode fazer referência a um segredo no Cofre de Chaves. Este é um caso especial de variáveis de ambiente com considerações exclusivas.

Para criar uma variável de ambiente secreta no portal do PowerApps, você deve configurar seu Cofre de Chaves.

Além da configuração acima, você deve executar as seguintes ações para autorizar o Copilot Studio a ler este Cofre de Chaves:

1. Atribua a função Key Vault Secrets User ao aplicativo do Microsoft Virtual Agents Service.

2. Para autorizar todos os agentes do ambiente a acessar o segredo, crie uma tag AllowedEnvironments no segredo e adicione os IDs de ambiente permitidos separados por vírgula.

3. Para autorizar apenas agentes específicos do ambiente a usar este Key Vault, crie uma tag AllowedAgents e coloque o identificador agente no formato {envId}/{schemaName}. Para vários valores, separe os valores com vírgulas.

Se você atingir o número máximo de caracteres, mas ainda precisar adicionar mais agentes, adicione outra tag com um nome descritivo, mas exclusivo (por exemplo: AllowedAgents2).

O valor do segredo é armazenado em cache no tempo de execução do Diálogo por cinco minutos. As leituras malsucedidas são armazenadas em cache por 30 segundos.

Aviso

Ao adicionar o segredo no agente, você pode expor o valor desse segredo a todos os usuários que podem editar o agente no ambiente, porque esses usuários podem editar o agente para retornar o valor no nó SendMessage .

Variáveis do sistema

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

Observação

Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.

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 do sistema User.DisplayName em uma fórmula, consulte-a como System.User.DisplayName.

Name	Type	Definição
Activity.Attachments	tabela	Os anexos de Arquivo fornecidos pelo usuário
Activity.Channel	opção	O ID do canal da conversa atual
Activity.ChannelData	qualquer	Um objeto que contém conteúdo específico do canal
Activity.ChannelId	cadeia	O ID do canal da conversa atual, como uma cadeia de caracteres
Activity.From.Id	cadeia	ID exclusivo específico do canal para o remetente
Activity.From.Name	cadeia	Nome amigável do remetente específico do canal
Activity.Name	cadeia	O nome do evento
Activity.Recipient.Id	cadeia	A propriedade Tipo de atividade de entrada.
Activity.Recipient.Name	cadeia	Representa o nome de exibição do agente dentro do canal. No contexto do canal de telefonia, o valor desta variável será o número de telefone ao qual o agente está anexado.
Activity.Text	cadeia	A mensagem mais recente enviada pelo usuário
Activity.Type	opção	Tipo de atividade
Activity.TypeId	cadeia	Tipo de atividade, como uma cadeia de caracteres
Activity.Value	qualquer	Valor em aberto
Bot.EnvironmentId	cadeia	O ID do ambiente do agente
Bot.Id	cadeia	O ID do agente
Bot.Name	cadeia	O nome do seu agente
Bot.SchemaName	cadeia	O nome do esquema do agente
Bot.TenantId	cadeia	O ID do locatário do agente
ClientPluginActions	opção	Coleção de ações de plug-in de cliente dinâmico a serem consideradas para orquestração generativa
Conversation.Id	cadeia	O ID exclusivo da conversa atual
Conversation.InTestMode	boolean	Sinalizador booliano que representa se a conversa está acontecendo na tela de teste
Conversation.LocalTimeZone	cadeia	Nome do fuso horário a ser usado pelo usuário no formato de banco de dados de Fuso Horário IANA
Conversation.LocalTimeZoneOffset	datetime	O deslocamento de hora de UTC para o fuso horário local atual
Error.Code	cadeia	O código de erro para o erro atual. Nota: Esta variável é suportada somente se Gatilho for On Error.
Error.Message	cadeia	A mensagem de erro do erro atual. Nota: Esta variável é suportada somente se Gatilho for On Error.
FallbackCount	número	Essa variável conta as vezes em que um tópico não pôde ser correspondida à entrada do usuário. Nota: Esta variável é suportada somente se Gatilho for On Unknown Intent.
InactivityTimer.Continue	boolean	Sinalizador booliano que representa se o temporizador precisa continuar. Nota: Esta variável é suportada somente se Gatilho for Inactivity.
InactivityTimer.Count	número	Número de vezes que o temporizador OnInactivity foi acionado devido à inatividade do usuário após o tempo configurado. Nota: Esta variável é suportada somente se Gatilho for Inactivity.
LastMessage.Id	cadeia	ID da mensagem anterior enviada pelo usuário
LastMessage.Text	cadeia	A mensagem anterior enviada pelo usuário
Recognizer.ExtractedEntities	opção	Representa as entidades extraídas da mensagem de disparo. Nota: Esta variável é suportada somente se Gatilho for On Select Intent.
Recognizer.IntentOptions	opção	Representa as opções de intenção quando o reconhecedor retorna resultados ambíguos. Nota: Esta variável é suportada somente se Gatilho for On Select Intent.
Recognizer.SelectedIntent	opção	Representa a intenção selecionada do reconhecedor. Nota: Esta variável é suportada somente se Gatilho for On Select Intent.
Recognizer.TriggeringMessage.Id	cadeia	ID da mensagem do usuário que acionou o tópico atual
Recognizer.TriggeringMessage.Text	cadeia	Mensagem do usuário que acionou o tópico atual
Recognizer.MultipleTopicsMatchedReason	cadeia	Usado para determinar por que vários tópicos foram correspondidos. Nota: Esta variável é suportada somente se Gatilho for On Select Intent.
User.Language	opção	Essa variável é usada para definir a localidade de idioma do usuário por conversa.
SignInReason	opção	Usado para determinar qual opção de entrada é necessária ao acionar o tópico. Nota: Esta variável é suportada somente se Gatilho for On Sign In.

Variáveis para autenticação integrada (padrão)

As seguintes variáveis estão disponíveis quando você configura seu agente para autenticar com Microsoft. Isso usará a autenticação do Entra ID e permitirá apenas os canais do Teams e do PowerApps. Este é o padrão para novos agentes.

Para obter mais informações, consulte Variáveis de autenticação.

Name	Type	Definição
User.DisplayName	cadeia	O nome de exibição do usuário que está falando com agente.
User.Email	cadeia	O endereço de e-mail do usuário que está falando com agente.
User.FirstName	cadeia	O nome do usuário que está conversando com o agente.
User.Id	cadeia	O ID exclusivo do usuário que está falando com agente.
User.IsLoggedIn	boolean	Sinalizador booliano que representa se o usuário atualmente falando com agente está autenticado ou não.
User.LastName	cadeia	O sobrenome do usuário que está conversando com o agente.
User.PrincipalName	cadeia	O nome principal do usuário que está conversando com agente.

Variáveis para autenticação manual com Generic OAuth 2

As seguintes variáveis estão disponíveis quando você configura seu agente para usar o provedor de serviços Generic OAuth 2.

Name	Type	Definição
User.AccessToken	cadeia	O token de acesso para o usuário autenticado com agente.
User.DisplayName	cadeia	O nome de exibição do usuário que está falando com agente.
User.Id	cadeia	O ID exclusivo do usuário que está falando com agente.
User.IsLoggedIn	boolean	Sinalizador booliano que representa se o usuário atualmente falando com agente está autenticado ou não.

Variáveis para autenticação manual com o Microsoft Entra ID

As seguintes variáveis estão disponíveis quando você configura seu agente para usar os provedores de serviço de Microsoft Entra ID (anteriormente Azure Active Directory).

Name	Type	Definição
User.AccessToken	cadeia	O token de acesso para o usuário autenticado com agente.
User.DisplayName	cadeia	O nome de exibição do usuário que está falando com agente.
User.Email	cadeia	O endereço de e-mail do usuário que está falando com agente.
User.FirstName	cadeia	O nome do usuário que está conversando com o agente.
User.Id	cadeia	O ID exclusivo do usuário que está falando com agente.
User.IsLoggedIn	boolean	Sinalizador booliano que representa se o usuário atualmente falando com agente está autenticado ou não.
User.LastName	cadeia	O sobrenome do usuário que está conversando com o agente.
User.PrincipalName	cadeia	O nome principal do usuário que está conversando com agente.

Variáveis para agentes habilitados para voz

As variáveis a seguir estão disponíveis apenas em agentes habilitados para voz.

Observação

Para obter mais informações sobre variáveis agente habilitadas para voz, consulte Usar variáveis de voz.

Name	Type	Definição
Activity.InputDTMFKeys	cadeia	O valor bruto da chave DTMF que foi recebido da telefonia.
Activity.SpeechRecognition.Confidence	número	O pontuação de confiança para a hipótese de ASR resultado total, 0 a 1.
Activity.SpeechRecognition.MinimallyFormattedText	cadeia	Texto ligeiramente formatado do resultado da hipótese de ASR. Por exemplo, quinhentos dólares. As palavras são soletradas, mas maiúsculas básicas e pontuação são incluídas.
Activity.UserInputType	opção	O tipo de entrada mais recente do usuário final. O valor pode ser teste, fala ou DTMF.
Conversation.OnlyAllowDTMF	boolean	Sinalizador booliano que representa se o IVR deve ser definido para o modo somente DTMF no tempo de execução.
Conversation.SipUuiHeaderValue	cadeia	A cadeia de caracteres de cabeçalho UUI usada para passar o contexto para o IVR no início da chamada.

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ó Pergunta), o agente faz a pergunta ao usuário para preencher o valor da variável. Se o agente já adquiriu o valor em um tópico, There's anterior, não há razão 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 agente é 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 Teste agente, 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 Teste agente, se este tópico for acionado primeiro, ele perguntará ao usuário: "Qual é 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ó de 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. Adicione um nó de redirecionamento e Select o destino tópico.

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 agente 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ássica

Entidade e tipo de variável

O 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 Verdadeiro ou Falso. 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 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.

Conteúdo relacionado

• Usar variáveis para transportar conteúdo entre tópicos
• Personalize a aparência de um agente