Trabalhar com variáveis

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

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

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

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

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 copiloto não podem modificar a variável de ambiente no 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:

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 copilotos 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 copilotos específicos do ambiente a usar esse Cofre de Chaves, crie uma tag AllowedCopilots e coloque o identificador do copiloto 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 copilotos, adicione outra tag com um nome descritivo, mas exclusivo (por exemplo: AllowedCopilots2).

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.

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

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

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

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

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

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

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

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

Variáveis para copilotos habilitados para voz

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

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

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.

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.

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.