Partilhar via

Trabalhar com variáveis

  • Artigo

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 "customerName," 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.

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.

Captura de tela do nó Pergunta com o nome e o tipo de variável padrão destacados.

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, selecione a caixa Identificar e escolha o tipo de informação que o agente deve escutar.

Captura de tela do nó Pergunta com o painel

Renomear uma variável

As variáveis criadas automaticamente recebem um nome padrão ao ser criadas. Uma melhor prática é dar às suas variáveis nomes significativos para deixar seu propósito claro 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ó de Pergunta para armazenar a entrada do usuário em uma variável. Pode haver situações em que você queira definir o valor de uma variável por conta própria. 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.

    Captura de tela do botão Criar uma nova variável.

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

    Captura de tela do nó Definir Valor da Variável com uma nova variável de tipo desconhecido.

  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 de tipo de cadeia de caracteres, se você encontrar uma incompatibilidade entre Definir variável e Valor de destino, uma mensagem de erro e o botão Corrigir incompatibilidade de tipo serão exibidos. Selecione o botão para que o Copilot Studio gere automaticamente uma fórmula do Power Fx que resolva a incompatibilidade.

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 para uma 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.

Captura de tela de um nó Ação com parâmetros de entrada e saída para uma ação de habilidade.

Usar valores literais para entradas de variável

Nos nós em que é possível definir um valor para os parâmetros de entrada, você sempre pode inserir um valor literal em vez de selecionar outra variável como o valor.

Captura de tela mostrando o uso de um valor literal para um parâmetro de entrada de variável chamado productName.

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 (por exemplo, cenários que usam tipos complexos), pode ser necessário usar uma fórmula do Power Fx para definir um tipo específico.

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. Variáveis de ambiente secretas são um caso especial de variáveis de ambiente com considerações exclusivas.

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

Para autorizar o Copilot Studio a ler este Key Vault, você deve realizar as seguintes ações:

  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 marca AllowedEnvironments no segredo e adicione as IDs de ambiente permitidas separadas por vírgula.

  3. Para autorizar apenas agentes específicos do ambiente a usar esse Key Vault, crie uma marca AllowedAgents e coloque o identificador do 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 marca 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, pois esses usuários podem editar o agente para retornar o valor no nó SendMessage.

Painel de variáveis

O painel Variáveis é onde você pode exibir todas as variáveis disponíveis para um tópico, independentemente de em quais nós elas 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.

Captura de tela do painel Variáveis na tela de criação do Copilot Studio com o botão Variáveis destacado.

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 converter uma variável global de volta em uma variável de tópico. Você também pode selecionar se uma variável de tópico pode receber valores ou passar seu valor para outros tópicos.

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

Passando variáveis entre tópicos

Ao redirecionar um tópico para outro, você pode passar os valores das variáveis do tópico de origem para o tópico de destino e também retornar valores do tópico de destino para o tópico de origem. 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 agente faz a pergunta ao usuário para preencher o valor da variável. Se o valor já tiver sido adquirido pelo agente 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 redireciona para este, ele pode então passar uma variável ou um valor literal nesta variável e ignorar a questão completamente. A experiência do usuário ao falar com o agente é simples.

Neste exemplo, usamos dois tópicos: Saudação e Conversar 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 Conversar com o Cliente ignora 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 Conversar com o Cliente:

Captura de tela do fluxo de conversa do tópico Conversar com o Cliente.

Conforme mostrado no painel de teste, se esse tópico for acionado primeiro, ele perguntará ao usuário: "Como devo chamá-lo?" Ele armazena o valor em uma variável de cadeia de caracteres chamada customerName. A variável customerName 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, customerName!"

Aqui está o fluxo do tópico Saudação:

Captura de tela do fluxo de conversa do tópico Saudação.

Conforme mostrado no painel de teste, se esse tópico for acionado primeiro, ele perguntará ao usuário: "Qual é o seu nome?" Ele armazena o valor em uma variável de cadeia de caracteres chamada customerName. O tópico envia a mensagem: "Prazer em conhecê-lo, customerName!" Em seguida, ele redireciona para o tópico Conversar com o Cliente que envia a mensagem: "Espero que você esteja tendo um dia maravilhoso, customerName!" Observe, no entanto que o tópico Conversar com o Cliente pulou a pergunta sobre o nome do usuário novamente. Em vez disso, ele usou o valor da variável Saudação.

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

Captura de tela do fluxo de conversa do tópico Conversar com o Cliente quando o tópico Saudação é disparado primeiro.

Vamos percorrer as etapas para configurar um tópico para receber valores de outros tópicos. Nosso cenário de exemplo usa o tópico predefinido Saudação como o tópico de origem e um novo tópico Conversar com o Cliente como o tópico de destino, mas as mesmas etapas funcionam para qualquer tópico que deve usar um valor de um tópico anterior quando possível.

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. Em nosso exemplo, é Conversar com o Cliente.

  1. Crie um novo tópico e chame-o de "Conversar com o Cliente".

  2. Adicione frases de gatilho como "fale comigo", "fale comigo", "converse comigo".

  3. Adicione um nó Pergunta e insira "Como devo chamá-lo?" na mensagem.

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

  5. Selecione o nome da variável. O painel Propriedades da variável é aberto.

  6. Substitua o nome padrão por "customerName" e selecione Receber valores de outros tópicos.

    Captura de tela do painel 'Propriedades da variável' mostrando a variável customerName e suas propriedades.

  7. Adicionar um nó Mensagem.

  8. Na caixa de mensagem, digite "Espero que você esteja tendo um dia maravilhoso, ".

  9. Selecione o ícone Inserir variável ({x}) e escolha customerName.

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

  11. 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 e o passa para o tópico de destino. Em nosso exemplo, é Saudação.

  1. Vá para o tópico Saudação e exclua os nós padrão, exceto o nó de Gatilho.

  2. Adicione um nó Pergunta e insira "Qual é o seu nome?" na mensagem.

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

  4. Substitua o nome padrão por "customerNameFromGreeting".

  5. Adicionar um nó Mensagem.

  6. Na caixa de mensagem, digite "Prazer em conhecê-lo, ".

  7. Selecione o ícone Inserir variável ({x}) e escolha customerNameFromGreeting.

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

  9. Adicione um nó de Redirecionamento e selecione o tópico de destino Conversar com o Cliente.

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

    Captura de tela do tópico Saudação com a variável customerName adicionada como entrada em um nó de redirecionamento.

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

    O nó Redirecionamento deve parecer com este:

    Captura de tela do nó Redirecionar concluído no tópico Saudação.

  12. 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. Fazemos uma nova pergunta no tópico Conversar com o Cliente e depois retornamos 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 que fornece o valor a ser passado de volta para o tópico original. Neste exemplo, o tópico de origem é Conversar com o Cliente.

  1. Ir para o tópico da fonte.

  2. Adicione um nó Pergunta e insira "Em que cidade você mora?" 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 como "customerCity" e selecione Retornar valores para os tópicos originais.

    Captura de tela do tópico Conversar com o Cliente com a variável customerCity e suas propriedades destacadas.

  5. Adicionar um nó Mensagem.

  6. Selecione o ícone Inserir variável ({x}) e escolha customerCity.

  7. Após a variável na caixa de mensagem, insira "deve ser bonito nesta época do ano!".

  8. 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 recebe valores do tópico atual. Em nosso exemplo, o tópico de destino é Saudação.

  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.

    Captura de tela do fluxo de conversa do tópico Saudação com a variável returned em um nó Redirecionar.

  3. Salve o tópico.

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 o ícone Adicionar nó aponte para Gerenciamento de variável, e selecione Analisar valor.

Captura de tela do menu para adicionar um nó, selecionando Gerenciamento de variável e, em seguida, 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. Com o nó Analisar valor, você pode enviar todo o resultado da API como uma cadeia de caracteres. Por exemplo: 

{
    "Name": "Parker",
    "Position": "Product manager",
    "Company": "Contoso",
    "FormerPositions": [{
            "Position": "Customer service representative"
        }
    ]
}

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 e selecione a variável que deseja analisar.

    Captura de tela mostrando a seleção da variável a ser analisada.

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

    Captura de tela mostrando a seleção do tipo de dados para um nó Analisar Valor.

  3. Selecione Obter Esquema a partir do JSON de Exemplo e insira o JSON de exemplo desejado no editor que é aberto.

    Captura de tela mostrando Obter esquema do JSON de exemplo.

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

    Captura de tela mostrando a seleção de uma variável de destino para um valor analisado.

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

    Captura de tela mostrando que a variável de destino para os dados analisados tem o tipo desejado: Registro.

Além de analisar cadeias de caracteres JSON, um uso importante do nó Analisar valor está analisando UntypedObjects no runtime. O caso de uso mais comum é quando você recebe um evento e precisa analisar o valor dele. Ou talvez você queira analisar a propriedade System.Activity.ChannelData, que varia em tempo de execução por canal.

Se você fosse analisar as informações de um evento vindo do Teams, precisaria usar a documentação do desenvolvedor do Teams para encontrar um exemplo da aparência do evento esperado e usar esse exemplo como dados de exemplo, conforme descrito anteriormente nesta seção.

Conteúdo relacionado