Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
As variáveis existem em quatro níveis, ou âmbitos:
- As variáveis de tópico só podem ser utilizadas nos tópicos em que são criadas. Este âmbito é a predefinição para as variáveis que criar.
- Variáveis globais que podem ser utilizadas em todos os tópicos. Pode alterar o âmbito de uma variável de tópico para a tornar numa variável global.
- Variáveis de sistema que o Copilot Studio cria automaticamente para um agente. Fornecem mais informações contextuais sobre a conversação ou o utilizador. Estão disponíveis em todos os tópicos.
- Variáveis de ambiente criadas no Power Platform. São só de leitura no Copilot Studio. Armazenam as chaves e os valores dos parâmetros, que depois servem de entrada para vários outros objetos de aplicação, incluindo o Copilot Studio. Separar os parâmetros dos objetos que consomem permite alterar os valores dentro do mesmo ambiente ou quando migra soluções para outros ambientes. A alternativa é deixar valores de parâmetros codificados dentro dos componentes que os utilizam.
Tipos de variáveis
Cada variável tem um tipo base. O tipo determina os valores que a variável pode conter e os operadores que pode utilizar quando cria uma expressão lógica com ela.
| Tipo | Descrição |
|---|---|
| Cadeia (de carateres) | Uma sequência de carateres utilizada para representar texto |
| Booleano | 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 têm de ser do mesmo tipo |
| Registo | 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 determinado momento |
| Opção | Uma lista de valores de cadeia (de carateres) com sinónimos associados |
| Em Branco | Um marcador de posição para "sem valor" ou "valor desconhecido"; para obter mais informações, consulte Em branco na documentação Power Fx |
O tipo de uma variável é definido na primeira vez que lhe atribui um valor. Depois disso, o tipo fica fixo e não pode atribuir valores de qualquer outro tipo. Por exemplo, se atribuir o valor inicial 1 a uma variável, o tipo será definido como Número. Se depois tentar atribuir um valor de Cadeia (de carateres) como "apples", obterá um erro.
Quando testa um agente, pode aparecer temporariamente uma variável com o tipo desconhecido. Uma variável desconhecida ainda não tem um valor.
A ordem das variáveis é determinada de cima para baixo na tela de criação. Os nós na parte superior da tela de criação são considerados antes dos nós na parte inferior.
Quando cria ramos com nós de Condição, os ramos são ordenados 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 utiliza entidades para identificar tipos específicos de informações a partir das respostas de um utilizador. A informação identificada é guardada numa variável do tipo adequado para a informação. A tabela a seguir lista o tipo base de variáveis associadas a entidades pré-criadas.
| Entidade | Tipo base da variável |
|---|---|
| Opções de escolha múltipla | Opção |
| Toda a resposta do utilizador | Cadeia (de carateres) |
| Antiguidade | Número |
| Booleano | Booleano |
| Localidade | Cadeia (de carateres) |
| Cor | Cadeia (de carateres) |
| Continente | Cadeia (de carateres) |
| País ou região | Cadeia (de carateres) |
| Data e hora | DateTime |
| Cadeia (de carateres) | |
| Evento | Cadeia (de carateres) |
| Número inteiro | Número inteiro |
| Idioma | Cadeia (de carateres) |
| Dinheiro | Número |
| Número | Número |
| Ordinal | Número |
| Organização | Cadeia (de carateres) |
| Percentagem | Número |
| Nome de pessoa | Cadeia (de carateres) |
| Número de telefone | Cadeia (de carateres) |
| Ponto de interesse | Cadeia (de carateres) |
| Velocidade | Número |
| Estado | Cadeia (de carateres) |
| Endereço | Cadeia (de carateres) |
| Temperatura | Número |
| URL | Cadeia (de carateres) |
| Espessura | Número |
| Código postal | Cadeia (de carateres) |
| Entidade personalizada | Opção |
Variáveis de ambiente
Variáveis de ambiente são um conceito do Power Platform. As variáveis de ambiente permitem que o cenário básico de gestão do ciclo de vida das aplicações (ALM) mova uma aplicação entre ambientes do Power Platform. Neste cenário, a aplicação permanece exatamente a mesma, à exceção de algumas referências externas importantes que são diferentes entre o ambiente de origem e o ambiente de destino.
Utilize as variáveis de ambiente da mesma forma que as variáveis de tópico, globais e de sistema. Uma diferença notável é que as variáveis de ambiente são só de leitura no Copilot Studio. Os autores de agentes 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, pode utilizar o Painel de variáveis para ver informações sobre uma variável de ambiente. O Painel de propriedades da variável também tem uma ligação para o Power Apps, a experiência de criação para variáveis de ambiente.
A versão publicada de um agente que utiliza variáveis de ambiente tem os valores definidos para estas variáveis quando o agente é publicado. Sempre que um administrador atualiza variáveis de ambiente, tem de republicar quaisquer agentes que utilizem estas variáveis, para que as alterações sejam eficazes em runtime. No entanto, há uma exceção: não precisa de republicar os seus agentes quando o valor de uma variável de ambiente do tipo Segredo muda. Ao contrário de outras variáveis de ambiente, as variáveis de segredo são obtidas em runtime.
Os tipos de variáveis de ambiente no Copilot Studio mapeiam para os tipos de dados do Power Apps da seguinte forma:
| Tipo no Copilot Studio | Tipo no Power Apps |
|---|---|
| Número decimal | Número |
| JSON | Deteta o tipo a partir do valor. Se não for JSON => Não especificado (erro de validação) |
| Texto | Cadeia (de carateres) |
| Sim/Não | Booleano |
| Origem de dados | Cadeia (de carateres) |
| Segredo | Cadeia (de carateres) |
Nota
Os erros das variáveis de ambiente são visíveis no chat de teste e aquando da publicação. No entanto, estes erros não aparecem na lista de Tópicos porque não são variáveis do tópico.
Variáveis de sistema
Cada agente inclui variáveis de sistema incorporadas que fornecem informações adicionais sobre uma conversação.
Nota
Para obter mais informações sobre variáveis de agente com capacidade de voz, consulte Utilizar variáveis de voz.
O Copilot Studio não mostra todas as variáveis de sistema. Para aceder a variáveis de sistema ocultas, utilize uma fórmula do Power Fx.
Para utilizar variáveis de sistema numa fórmula do Power Fx, adicione System. antes do nome da variável. Por exemplo, para incluir a variável de sistema User.DisplayName numa fórmula, refira-se a ela como System.User.DisplayName.
| Nome | Tipo | Definição |
|---|---|---|
| Activity.Attachments | tabela | Os anexos de ficheiros que o utilizador fornece. |
| Activity.Channel | opção | O ID do canal da conversação atual. |
| Activity.ChannelData | qualquer | Um objeto que contém conteúdo específico do canal. |
| Activity.ChannelId | cadeia (de carateres) | O ID do canal da conversa atual, como uma cadeia (de carateres). |
| Activity.From.Id | cadeia (de carateres) | O ID exclusivo específico do canal do remetente. |
| Activity.From.Name | cadeia (de carateres) | O nome amigável de utilizador, específico do canal do remetente. |
| Activity.Name | cadeia (de carateres) | O nome do evento. |
| Activity.Recipient.Id | cadeia (de carateres) | A propriedade de Tipo da atividade recebida. |
| Activity.Recipient.Name | cadeia (de carateres) | Representa o nome a apresentar do agente dentro do canal. No contexto do canal de telefonia, o valor desta variável é o número de telefone ao qual o agente está associado. |
| Activity.Text | cadeia (de carateres) | A mensagem mais recente enviada pelo utilizador. |
| Activity.Type | opção | Tipo de atividade. |
| Activity.TypeId | cadeia (de carateres) | Tipo de atividade, como cadeia (de carateres). |
| Activity.Value | qualquer | Valor aberto. |
| Bot.EnvironmentId | cadeia (de carateres) | O ID de ambiente do agente. |
| Bot.Id | cadeia (de carateres) | O ID do agente. |
| Bot.Name | cadeia (de carateres) | O nome do seu agente. |
| Bot.SchemaName | cadeia (de carateres) | O nome do esquema do agente. |
| Bot.TenantId | cadeia (de carateres) | O ID de inquilino do agente. |
| ClientPluginActions | opção | Coleção de ações de plug-in de cliente dinâmico a considerar para orquestração generativa. |
| Conversation.Id | cadeia (de carateres) | O ID exclusivo da conversação atual. |
| Conversation.InTestMode | Booleano | Sinalizador booleano que representa se a conversação está a decorrer na tela de teste. |
| Conversation.LocalTimeZone | cadeia (de carateres) | Nome do fuso horário a utilizar pelo utilizador no formato da base de dados de fusos horários da IANA. |
| Conversation.LocalTimeZoneOffset | datetime | O desfasamento horário em relação ao UTC para o fuso horário local atual. |
| Error.Code | cadeia (de carateres) | O código de erro para o erro atual. A mensagem de erro para o erro atual. |
| Error.Message | cadeia (de carateres) | A mensagem de erro para o erro atual. Nota: Esta variável é suportada apenas se o acionador for On Error. |
| FallbackCount | Número | Esta variável conta as vezes em que não foi possível fazer corresponder um tópico à entrada de utilizador. Nota: Esta variável é suportada apenas se o acionador for On Unknown Intent. |
| InactivityTimer.Continue | Booleano | Sinalizador booleano que representa se o temporizador precisa de continuar. Nota: Esta variável é suportada apenas se o acionador for Inactivity. |
| InactivityTimer.Count | Número | Número de vezes que o temporizador OnInactivity foi acionado devido à inatividade do utilizador após o tempo configurado. Nota: Esta variável é suportada apenas se o acionador for Inactivity. |
| LastMessage.Id | cadeia (de carateres) | O ID da mensagem anterior enviada pelo utilizador. |
| LastMessage.Text | cadeia (de carateres) | A mensagem anterior enviada pelo utilizador. |
| Recognizer.ExtractedEntities | opção | Representa as entidades extraídas da mensagem de acionamento. Nota: Esta variável é suportada apenas se o acionador for On Select Intent. |
| Recognizer.IntentOptions | opção | Representa as opções de intenção quando o reconhecedor devolve resultados ambíguos. Nota: Esta variável é suportada apenas se o acionador for On Select Intent. |
| Recognizer.SelectedIntent | opção | Representa a intenção selecionada a partir do reconhecedor. Nota: Esta variável é suportada apenas se o acionador for On Select Intent. |
| Recognizer.TriggeringMessage.Id | cadeia (de carateres) | O ID da mensagem de utilizador que acionou o tópico atual. |
| Recognizer.TriggeringMessage.Text | cadeia (de carateres) | A mensagem de utilizador que acionou o tópico atual. |
| Recognizer.MultipleTopicsMatchedReason | cadeia (de carateres) | Utilizado para determinar porque é que vários tópicos foram correspondidos. Nota: Esta variável é suportada apenas se o acionador for On Select Intent. |
| SignInReason | opção | Utilizado para determinar que opção de início de sessão é necessária ao acionar o tópico. Nota: Esta variável é suportada apenas se o acionador for On Sign In. |
| User.Language | opção | Esta variável é utilizada para definir a região do idioma do utilizador por conversação. |
Variáveis para autenticação integrada (predefinição)
As seguintes variáveis estão disponíveis para agentes configurados para autenticação com a Microsoft. Esta configuração utiliza a autenticação Microsoft Entra ID e é a predefinição para novos agentes.
Para obter mais informações, consulte Variáveis de autenticação.
| Nome | Tipo | Definição |
|---|---|---|
| User.DisplayName | cadeia (de carateres) | O nome a apresentar do utilizador que está a falar com o agente. |
| User.Email | cadeia (de carateres) | O endereço de e-mail do utilizador que está a falar com o agente. |
| User.FirstName | cadeia (de carateres) | O nome próprio do utilizador que está a falar com o agente. |
| User.Id | cadeia (de carateres) | O ID exclusivo do utilizador que está a falar com o agente. |
| User.IsLoggedIn | Booleano | Sinalizador booleano que representa se o utilizador que está atualmente a falar com o agente está autenticado ou não. |
| User.LastName | cadeia (de carateres) | O apelido do utilizador que está a falar com o agente. |
| User.PrincipalName | cadeia (de carateres) | O nome principal de utilizador que está a falar com o agente. |
Variáveis para autenticação manual com Generic OAuth 2
As seguintes variáveis estão disponíveis para agentes configurados para utilizar o fornecedor de serviços Generic OAuth 2.
| Nome | Tipo | Definição |
|---|---|---|
| User.AccessToken | cadeia (de carateres) | O token de acesso para o utilizador se autenticar no agente. |
| User.DisplayName | cadeia (de carateres) | O nome a apresentar do utilizador que está a falar com o agente. |
| User.Id | cadeia (de carateres) | O ID exclusivo do utilizador que está a falar com o agente. |
| User.IsLoggedIn | Booleano | Sinalizador booleano que representa se o utilizador que está atualmente a falar com o agente está autenticado ou não. |
Variáveis para autenticação manual com Microsoft Entra ID
As seguintes variáveis estão disponíveis para agentes configurados para utilizar os fornecedores de serviços Microsoft Entra ID (anteriormente Azure Active Directory).
| Nome | Tipo | Definição |
|---|---|---|
| User.AccessToken | cadeia (de carateres) | O token de acesso para o utilizador se autenticar no agente. |
| User.DisplayName | cadeia (de carateres) | O nome a apresentar do utilizador que está a falar com o agente. |
| User.Email | cadeia (de carateres) | O endereço de e-mail do utilizador que está a falar com o agente. |
| User.FirstName | cadeia (de carateres) | O nome próprio do utilizador que está a falar com o agente. |
| User.Id | cadeia (de carateres) | O ID exclusivo do utilizador que está a falar com o agente. |
| User.IsLoggedIn | Booleano | Sinalizador booleano que representa se o utilizador que está atualmente a falar com o agente está autenticado ou não. |
| User.LastName | cadeia (de carateres) | O apelido do utilizador que está a falar com o agente. |
| User.PrincipalName | cadeia (de carateres) | O nome principal do utilizador que está a falar com o agente. |
Variáveis para agentes com capacidade de voz
As seguintes variáveis estão disponíveis apenas para agentes com capacidade de voz.
Nota
Para obter mais informações sobre variáveis de agente com capacidade de voz, consulte Utilizar variáveis de voz.
| Nome | Tipo | Definição |
|---|---|---|
| Activity.InputDTMFKeys | cadeia (de carateres) | O valor não processado da chave DTMF da telefonia. |
| Activity.SpeechRecognition.Confidence | Número | A pontuação de confiança para o resultado total da hipótese do Azure Site Recovery, de 0 a 1. |
| Activity.SpeechRecognition.MinimallyFormattedText | cadeia (de carateres) | Texto ligeiramente formatado do resultado da hipótese do Azure Site Recovery. Por exemplo, "Quinhentos dólares". As palavras estão escritas por extenso, mas a capitalização e a pontuação básicas estão incluídas. |
| Activity.UserInputType | opção | O tipo da entrada mais recente do utilizador do agente. O valor pode ser testar, voz ou DTMF. |
| Conversation.OnlyAllowDTMF | Booleano | Sinalizador booleano que representa se o IVR deve ser definido para o modo apenas DTMF em runtime. |
| Conversation.SipUuiHeaderValue | cadeia (de carateres) | A cadeia (de carateres) de cabeçalho UUI utilizada para transmitir o contexto para o IVR no início da chamada. |