Visão geral das variáveis
As variáveis podem existir em quatro níveis, ou escopos:
- 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.
- As 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 agente. Eles fornecem informações mais contextuais sobre a conversa ou o usuário. Elas estão disponíveis em todos os tópicos.
- As Variáveis de ambiente são criadas no Power Platform e são somente leitura no 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 da Cadeia de caracteres de "apples" resulta em um erro.
Quando você está testando 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 na ramificação mais à esquerda são considerados antes dos nós na ramificação 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 base de variável associado a entidades predefinidas.
| 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 |
| 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 | String |
| Weight | Número |
| CEP | String |
| Entidade personalizada | Opção |
Variáveis de ambiente
As Variáveis do ambiente são um conceito do Power Platform. 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 as variáveis de ambiente são somente leitura no Copilot Studio. Os autores do agente não podem modificar variáveis de ambiente no Copilot Studio. No entanto, os administradores podem alterar o valor das variáveis de ambiente no Power Apps. 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 tem um link para a experiência de criação nativa.
A versão publicada de um agente que usa variáveis de ambiente tem os valores que foram definidos para essas variáveis quando o agente foi publicado. Sempre que um administrador atualizar variáveis de ambiente, você deverá republicar quaisquer agentes que usem essas variáveis para que as alterações sejam efetivas no tempo de execução. No entanto, há uma exceção: você não precisa republicar seus agentes quando o valor de uma variável de ambiente do tipo segredo é alterado. Ao contrário de outras variáveis de ambiente, as variáveis secretas são recuperadas em tempo de execução.
Os tipos de variáveis de ambiente no mapa do Copilot Studio para tipos de dados do Power Apps da seguinte maneira:
| Digite no Copilot Studio | Digite no Power Apps |
|---|---|
| Número decimal | Número |
| JSON | Detecte o tipo a partir do valor. Caso não seja JSON=> Não especificado (erro de validação) |
| Texto | String |
| Sim/Não | Boolean |
| Fonte de dados | String |
| 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.
Variáveis do sistema
Cada agente vem com variáveis de sistema internas 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 para exibição do agente no canal. No contexto do canal de telefonia, o valor dessa variável é 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 | A ID do ambiente do agente |
| Bot.Id | cadeia | A ID do agente |
| Bot.Name | cadeia | O nome do seu agente |
| Bot.SchemaName | cadeia | O nome do esquema do agente |
| Bot.TenantId | cadeia | A ID de 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. A mensagem de erro definida para o erro atual. |
| Error.Message | cadeia | A mensagem de erro definida para o erro atual. Observação: essa variável só é compatível se o 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. Observação: essa variável só é compatível se o gatilho for On Unknown Intent. |
| InactivityTimer.Continue | Boolean | Sinalizador booliano que representa se o temporizador precisa continuar. Observação: essa variável só é compatível se o 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. Observação: essa variável só é compatível se o 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. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| Recognizer.IntentOptions | opção | Representa as opções de intenção quando o reconhecedor retorna resultados ambíguos. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| Recognizer.SelectedIntent | opção | Representa a intenção selecionada do reconhecedor. Observação: essa variável só é compatível se o 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. Observação: essa variável só é compatível se o gatilho for On Select Intent. |
| SignInReason | opção | Usado para determinar qual opção de entrada é necessária ao acionar o tópico. Observação: essa variável só é compatível se o gatilho for On Sign In. |
| User.Language | opção | Essa variável é usada para definir a localidade de idioma do usuário por conversa. |
Variáveis para autenticação integrada (padrão)
As variáveis a seguir estão disponíveis para agentes configurados para se autenticarem com a Microsoft. Essa configuração usa autenticação do Microsoft Entra ID e é 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 o agente. |
| User.Email | cadeia | O endereço de e-mail do usuário que está falando com o agente. |
| User.FirstName | cadeia | O primeiro nome do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Boolean | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
| User.LastName | cadeia | O nome da família do usuário que está falando com o agente. |
| User.PrincipalName | cadeia | O nome UPN do usuário que está falando atualmente com o agente. |
Variáveis para autenticação manual com OAuth 2 Genérico
As variáveis a seguir estarão disponíveis para agentes configurados seu agente para usar o provedor de serviços genérico OAuth 2.
| Name | Type | Definição |
|---|---|---|
| User.AccessToken | cadeia | O token de acesso para o usuário autenticar com o agente. |
| User.DisplayName | cadeia | O nome de exibição do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Boolean | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
Variáveis para autenticação manual com o Microsoft Entra ID
As variáveis a seguir estarão disponíveis para agentes configurados seu agente para usar os provedores de serviço do Microsoft Entra ID (anteriormente Azure Active Directory).
| Name | Type | Definição |
|---|---|---|
| User.AccessToken | cadeia | O token de acesso para o usuário autenticar com o agente. |
| User.DisplayName | cadeia | O nome de exibição do usuário que está falando com o agente. |
| User.Email | cadeia | O endereço de e-mail do usuário que está falando com o agente. |
| User.FirstName | cadeia | O primeiro nome do usuário que está falando com o agente. |
| User.Id | cadeia | O ID exclusivo do usuário que está falando com o agente. |
| User.IsLoggedIn | Boolean | Sinalizador booleano que representa se o usuário que está falando atualmente com o agente é autenticado ou não. |
| User.LastName | cadeia | O nome da família do usuário que está falando com o agente. |
| User.PrincipalName | cadeia | O nome da entidade de segurança do usuário que está falando com o 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 | A pontuação de confiança para o resultado inteiro da hipótese de Recuperação de Site do Azure, 0 a 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | cadeia | Texto ligeiramente formatado do resultado da hipótese de Recuperação de Site do Azure. 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 da última entrada do usuário. 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. |