Compartilhar via

Trabalhar com variáveis

Use variáveis para armazenar as respostas dos clientes para que você possa 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 abordar o cliente pelo nome à medida que a conversa continua.

Você pode passar variáveis para outros tópicos e fluxos do Power Automate, e devolvê-las deles.

Criar uma variável

Qualquer nó que retorna uma saída, como um nó Question , cria automaticamente uma variável de saída do tipo apropriado.

Captura de tela de um

Gorjeta

Renomeie os nós para torná-los mais fáceis de identificar. Selecione o campo de nome do nó para atualizar o nome diretamente, ou selecione os três pontos (...) 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 de Ir para o passo.

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

Escolha uma entidade para usar

Os nós de pergunta usam opções de múltipla escolha por padrão. Para usar uma entidade predefinida ou personalizada diferente, selecione a caixa Identificar e selecione o tipo de informação desejada.

Captura de tela do nó Pergunta com o painel

Renomear uma variável

Para facilitar a manutenção de seus agentes, substitua o nome padrão de cada variável por um nome significativo.

  1. Selecione a variável. O painel Propriedades da variável é exibido.

  2. Em Nome da variável, insira o nome desejado para sua variável.

Definir uma variável

Normalmente, você usa um nó Question para armazenar a entrada do usuário em uma variável. No entanto, talvez você queira definir o valor de uma variável por conta própria. Nesses casos, use um nó Definir valor da variável.

  1. Selecione o ícone Adicionar nó no nó após o qual você deseja adicionar um nó Definir valor da variável.

  2. Selecione Gerenciamento> devariável Definir um valor variável. Um nó de valor de variável Set aparece na tela.

  3. Selecione a caixa em Definir variável. O painel Selecionar uma variável é exibido.

    • Se a variável que você deseja definir já existir, selecione-a.

    • Caso contrário, selecione Criar novo. Essa ação cria uma nova variável. Seu tipo é desconhecido até que você atribua um valor a ele.

      Captura de tela do nó

  4. Para o valor To, atribua um valor usando uma das seguintes opções:

    • Digite um valor literal

    • Selecione uma variável existente do mesmo tipo.

    • Use 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 variáveis em nós de ação

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

Para obter mais contexto, consulte os cenários de exemplo em Chamar um fluxo de agente de um tópico e usar variáveis de entrada e saída para passar informações.

Usar valores literais para entradas de variável

Em um nó em que você define um valor para parâmetros de entrada, você 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 de caracteres, em vez disso, encapsule o valor em aspas duplas, assim: "123".

Para alguns cenários, como cenários que usam tipos complexos, talvez seja necessário usar uma fórmula do Power Fx para definir um tipo específico.

Usar variáveis de ambiente para gerenciar segredos do Azure Key Vault

Uma variável de ambiente pode referenciar um segredo no Key Vault. 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 Power Apps, você deve configurar um cofre do Key Vault.

Para autorizar o Copilot Studio a ler este cofre do Key Vault, conclua as seguintes ações:

  1. Atribua a função de Usuário de Segredos do Key Vault ao aplicativo Serviço do Microsoft Copilot Studio .

  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írgulas.

  3. Para autorizar apenas agentes específicos do ambiente a usar esse cofre, 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 tempo de execução do Dialog armazena em cache o valor secreto por cinco minutos. Ele armazena em cache leituras malsucedidas por 30 segundos.

Aviso

Ao adicionar o segredo no agente, você pode expor o valor desse segredo. Qualquer pessoa que possa editar o agente no ambiente pode adicionar um nó de mensagem e retornar o valor das variáveis de ambiente secretas em uma mensagem.

Painel Variáveis

No painel Variáveis, você pode ver todas as variáveis disponíveis para um tópico, independentemente de quais nós elas são definidas ou usadas.

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

Captura de tela do painel Variáveis, com o botão Variáveis realçado.

Para cada variável de tópico, 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 da variável.

Painel Propriedades da variável

No painel Propriedades variáveis , você pode renomear uma variável, ver onde seu agente a usa ou convertê-la em uma variável global. 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 de uma variável, selecione a variável desejada no painel Variáveis. Você também pode abrir o painel Propriedades variáveis de qualquer nó que usa variáveis selecionando a variável desejada.

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 certamente apreciam não ter que responder às mesmas perguntas mais de uma vez.

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, você pode definir a variável 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.

Este exemplo usa dois tópicos, Saudação e Conversa 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 este tópico for disparado 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 customerName variável 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 este tópico for disparado 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 customerName variável passada do tópico 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.

Percorra as etapas para configurar um tópico para receber valores de outros tópicos. Este cenário de exemplo usa o tópico predefinido Saudação como o tópico de origem e um novo tópico Fale 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 recebe valores de outros tópicos. Neste exemplo, é Falar com o Cliente.

  1. Crie um novo tópico e nomeie-o como "Fale com o Cliente".

  2. Adicione frases de gatilho como "fale comigo", "fale comigo" e "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 insira um ponto de exclamação (!).

  11. Salve o tópico.

Configurar a fonte de dados

O tópico de origem é o tópico que redireciona para outro tópico. Isso fornece o valor e o transfere para o tópico alvo. Neste 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 insira um ponto de exclamação (!).

  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

Em um agente, um tópico coleta uma informação específica. Vários outros tópicos podem chamá-lo e esperar que ele retorne as informações como uma variável. A variável se torna parte do tópico de origem e pode ser usada como qualquer outra variável. Ao disponibilizar as informações que o agente obtém nos tópicos, essa abordagem reduz a necessidade de variáveis globais.

Vamos continuar com o exemplo da seção anterior. Você faz uma nova pergunta no tópico Falar com o Cliente e, em seguida, retorna a resposta para o tópico Saudação .

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

Quando você retorna uma variável para um tópico, o tópico de origem é o tópico que fornece o valor a ser passado 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. Select a variável para abri-la no painel Propriedades da variável. Nomeie-o customerCitye selecione Retornar valores para 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ê retorna uma variável para um tópico, o tópico de destino recebe valores do tópico atual. No exemplo a seguir, 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 aparece 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.

Analisar valores

O nó Parse value converte um valor de um tipo para outro. Um caso de uso comum para o nó de valor parse é a conversão de JSON bruto. Por exemplo, um agente chama um fluxo que chama uma API. A API retorna um resultado. Você precisa de uma maneira de analisar esse resultado e retornar uma ou mais variáveis primitivas. Usando o nó de valor de análise , você pode enviar todo o resultado da API como uma cadeia de caracteres, como o seguinte:

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

O nó Parsar valor converte a variável de string em uma variável do tipo Registro. O editor do Power Fx fornece conclusão de código do IntelliSense e sugestões para esse tipo.

Além de analisar cadeias de caracteres JSON, um uso chave para o nó de análise de valor é interpretar objetos não tipados em tempo de execução. O caso de uso mais comum é quando você recebe um evento e precisa analisar o valor do evento. Ou talvez você queira analisar a propriedade System.Activity.ChannelData, que varia por canal durante o tempo de execução.

Se você precisar analisar informações de um evento proveniente do Teams, consulte a documentação do desenvolvedor do Teams para encontrar um exemplo da aparência do evento esperado. Em seguida, você pode seguir as instruções nesta seção, usando o evento de exemplo como informação adicional.

Para adicionar um nó Parse value a um tópico:

  1. Selecione o ícone Adicionar nó no nó após o qual você deseja analisar um valor. Aponte para Gerenciamento de variáveis e selecione Analisar valor.

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

  3. Para o tipo de dados, selecione De Dados de Exemplo.

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

  4. Selecione Obter Esquema do Exemplo de JSON, insira o exemplo JSON desejado no editor que é aberto e selecione Confirmar.

    Captura de tela mostrando o editor em que você insere dados JSON de exemplo.

  5. Selecione a variável para manter o valor analisado. Normalmente, você cria uma nova variável.

    Captura de tela mostrando como criar uma variável para manter um valor analisado diretamente do nó Analisar valor.

    A variável de saída agora tem o tipo esperado: registro.

    Captura de tela mostrando que a variável que contém os dados analisados tem o tipo esperado: registro.

Conteúdo relacionado

  • Last updated on