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.
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 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 |
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.
Selecione a variável para abri-la no painel Propriedades da variável.
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.
Selecione Adicionar nó (+) para adicionar um nó e Gerenciamento de variáveis>Definir um valor de variável.
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.
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 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 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.
Crie ou vá para o tópico de destino.
Adicione um nó Pergunta e insira
What should I call you?
na mensagem.Em Identificar, selecione a entidade predefinida Nome da pessoa.
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.Adicione um nó Mensagem.
Na caixa de mensagens, digite
I hope you're having a wonderful day,
.Selecione o ícone Inserir variável ({x}), e então selecione userName.
Selecione o espaço após a variável e digite
!
.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.
Ir para o tópico da fonte.
Adicionar um nó redirecionado e selecione o tópico de destino.
Selecione + Adicionar entrada, e então selecione a variável do tópico de destino para o qual você deseja passar um valor.
Selecione o ícone > e, em seguida, selecione a variável cujo valor você deseja passar.
O nó redirecionado deve ter este aspecto:
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.
Ir para o tópico da fonte.
Adicione um nó Pergunta e insira
What city do you live in?
na mensagem.Em Identificar, selecione a entidade predefinida Cidade.
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.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.
Ir para o tópico de destino.
A variável selecionada no tópico de origem deve aparecer no nó Redirecionar como uma variável de saída.
Salve o tópico.
Conteúdo relacionado
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários