Trabajar con variables
Puede utilizar variables paga guardar las respuestas de los clientes y reutilizarlas más adelante en la conversación.
También puede usar variables para crear expresiones lógicas que dirijan dinámicamente al cliente por diferentes rutas de conversación. Por ejemplo, guarde el nombre de un cliente en una variable llamada UserName
y el copiloto puede dirigirse al cliente por su nombre mientras continúa la conversación.
Las variables también se pueden pasar y devolver desde otros temas y flujos de Power Automate.
Las variables pueden existir en cuatro niveles, o ámbitos:
- Tema: las variables solo se pueden referenciar dentro de los temas en los que se crean. Este es el ámbito predeterminado para las variables que crea.
- Las variables globales pueden utilizarse en todos los temas. Puede cambiar el alcance de una variable de tema para convertirla en una variable global.
- Se crean automáticamente variables de sistema con su copiloto. Proporcionan más información contextual sobre la conversación o el usuario. Están disponibles en todos los temas.
- Las variables de entorno se crean en Power Platform y son de solo lectura en Copilot Studio. Almacenan las claves y los valores de los parámetros, que luego sirven de entrada a otros objetos de la aplicación, incluido Copilot Studio. Separar los parámetros de los objetos consumidores le permite cambiar los valores dentro del mismo entorno o cuando migra soluciones a otros entornos. La alternativa es dejar valores de parámetros codificados de forma rígida en los componentes que los utilizan.
Tipos de variables
Una variable está asociada a un tipo base. El tipo determina qué valores puede contener la variable y los operadores que puede usar al crear una expresión lógica con ella.
Type | Description |
---|---|
String | Una secuencia de caracteres utilizados para representar texto |
Booleana | Un valor lógico que sólo puede ser true o false |
Number | Cualquier número real |
Table | Una lista de valores, pero todos los valores deben ser del mismo tipo |
Grabar | Una colección de pares de nombre y valor donde los valores pueden ser de cualquier tipo |
Fecha y hora | Una fecha, hora, día de la semana o mes relativo a un punto en el tiempo |
Opción | Una lista de valores de cadena con sinónimos asociados |
En blanco | Un marcador de posición para "sin valor" o "valor desconocido"; para obtener más información, consulte Espacio en blanco en Power Fx |
El tipo de una variable se establece la primera vez que se le asigna un valor. Después, el tipo de esa variable es fijo y no se le pueden asignar valores de ningún otro tipo. Por ejemplo, a una variable dado el valor inicial de 1
se le asigna el tipo Número. Intentar asignarlo a un valor Cadena de "apples"
resultará en un error.
Cuando está probando un copiloto, puede aparecer una variable temporalmente como el tipo desconocido. A una variable desconocida aún no se le ha asignado un valor.
El orden de las variables se determina de arriba a abajo del lienzo de creación. Es decir, los nodos en la parte superior del lienzo de creación se consideran antes que los nodos en la parte inferior. Cuando crea ramas con nodos de condición, las ramas se ordenan de izquierda a derecha. Es decir, los nodos de la rama más a la izquierda se consideran antes que los nodos de la rama más a la derecha.
Entidades
Copilot Studio usa entidades para identificar un tipo específico de información de las respuestas de un usuario. La información identificada se guarda en una variable del tipo apropiado para la información. La siguiente tabla enumera el tipo de base variable que está asociado con entidades preconstruidas.
Entity | Tipo base de variable |
---|---|
Opciones de elección múltiple | Opción |
Respuesta completa del usuario | String |
Edad | Number |
Booleana | Booleana |
City | String |
Color | String |
Continente | String |
País o región | String |
Fecha y hora | Fecha y hora |
String | |
Evento | String |
Número entero | Número entero |
Lenguaje | String |
Money | Number |
Number | Number |
Ordinal | Number |
Organization | String |
Porcentaje | Number |
Nombre de la persona | String |
N.º de teléfono | String |
Punto de interés | String |
Velocidad | Number |
Valor | String |
Dirección postal | String |
Temperatura | Number |
Dirección URL | String |
Grosor | Number |
Código postal | String |
Entidad personalizada | Opción |
Crear una variable
Cualquier nodo que le solicite seleccionar una variable como salida, como un nodo Pregunta, crea automáticamente una variable de salida del tipo correcto.
Seleccionar la entidad que se va a usar
De forma predeterminada, se crean nodos de pregunta con opciones de selección múltiple. Para utilizar una entidad personalizada o prediseñada diferente, seleccione la casilla Identificar y elija el tipo de información que el copiloto debe escuchar.
Cambiar el nombre de una variable
A las variables se les asigna un nombre automáticamente al crearse. Un procedimiento recomendado es dar a las variables nombres significativos para dejar claro su propósito a cualquier otra persona que deba mantener su copiloto.
Seleccione la variable para abrirla en el panel Propiedades de variables.
En Nombre de la variable, introduzca un nuevo nombre para su variable.
Establecer una variable
Por lo general, usará un nodo de pregunta para guardar la entrada del usuario en una variable. Sin embargo, puede haber situaciones en las que desee establecer el valor usted mismo. En esos casos, use un nodo Establecer valor variable.
Seleccione Agregar nodo (+) para agregar un nodo y luego seleccione Administración de variables>Establecer un valor de variable.
Seleccione el cuadro bajo Establecer variable y luego Crear una nueva variable.
Se crea una nueva variable. Su tipo es desconocido hasta que le asigna un valor.
Para Hasta valor, asigne un valor usando una de las siguientes opciones:
- Escriba un valor literal.
- Seleccione una variable existente del mismo tipo. Esta acción establece la variable en el mismo valor que la variable que seleccione.
- Use una fórmula Power Fx. Las fórmulas de Power Fx son útiles para tipos más complejos, donde no se pueden usar valores literales, como los tipos Tabla y Registro.
Usar valores literales
En lugar de seleccionar un valor de variable, puede introducir un valor literal en cualquier variable.
El nodo intenta interpretar valores literales como una cadena, un número o un valor booleano. Por ejemplo, 123
se interpreta como un número. Si desea que se interprete como un valor de cadena, puede envolver el valor entre comillas dobles, como: "123"
.
Para algunos escenarios, o donde esté usando tipos más complejos, use una fórmula de Power Fx apropiada para establecer un tipo específico.
Panel Variables
El panel Variables es donde puede ver todas las variables que están disponibles en tema, independientemente de en qué nodos estén definidas o utilizadas. Para cada variable, puede seleccionar si puede recibir su valor de otros temas, devolver su valor a otros temas o ambos. También puede seleccionar una variable para editar sus propiedades en el panel Propiedades de variable.
Para abrir el panel de variables, en la barra de menú de tema, seleccione Variables.
Panel Propiedades de variables
En el panel de propiedades de la variable, puede cambiar el nombre de una variable, ver dónde se usa o convertirla en variable global. Sin embargo, no puede convertirlo de una variable global a una variable tema. También puede seleccionar si puede recibir valores o pasar su valor a otros temas.
Para abrir el panel Propiedades de variable, seleccione una variable en el panel Variables. También puede abrir el panel de propiedades de la variable seleccionando una variable en cualquier nodo.
Variables de entorno
Las variables de entorno son un concepto de Power Platform. Las variables de entorno habilitan el escenario básico de administración del ciclo de vida de la aplicación (ALM) de mover una aplicación entre entornos de Power Platform. En este escenario, la aplicación se mantiene exactamente igual salvo por unas pocas referencias externas clave que son diferentes entre el entorno de origen y el de destino.
Utilice variables de entorno de la misma forma que las variables de Tema, Global y Sistema. Una diferencia notable es que solo puede utilizar variables de entorno en modo solo lectura. Los autores de Copiloto no pueden modificar la variable de entorno en Copilot Studio. Sin embargo, los administradores pueden cambiar el valor de las variables de entorno en el portal de PowerApps.
Los tipos de variables de entorno en Copilot Studio se asignan a los tipos de datos de PowerApps del siguiente modo:
Tipo en Copilot Studio | Tipo en PowerApps |
---|---|
Número decimal | Number |
JSON | Detectar el tipo a partir del valor. Si no es Json => No especificado (error de validación) |
Text | string |
Sí/No | Booleana |
Origen de datos | string |
Secret | String |
Nota
Los errores de las variables de entorno son visibles en el chat de Prueba y al publicar. Sin embargo, estos errores no se muestran en la lista Tema porque no son variables de tema.
No puede crear ni editar variables de entorno en Copilot Studio. Debe utilizar el portal PowerApps para cambiar o establecer las variables de entorno. Desde Copilot Studio, puede usar las variables para ver información sobre una variable de entorno. El panel Variables también tiene un vínculo a la experiencia de creación nativa.
Usar variables de entorno para secretos de Azure Key Vault
Una variable de entorno puede hacer referencia a un secreto en Key Vault. Se trata de un caso especial de variables de entorno con consideraciones únicas.
Para crear una variable de entorno secreta en el portal de PowerApps, debe configurar su Key Vault.
Además de la configuración anterior, debe realizar las siguientes acciones para autorizar a Copilot Studio a leer este Key Vault:
Asigne el rol
Key Vault Secrets User
a la aplicaciónMicrosoft Virtual Agents Service
.Para autorizar a todos los copilotos del entorno a tener acceso al secreto, cree una etiqueta
AllowedEnvironments
en el secreto y agregue los ID de los entornos permitidos separados por comas.Para autorizar solo a determinados copilotos del entorno a utilizar esta Key Vault, cree una etiqueta
AllowedCopilots
y ponga el identificador del copiloto en el formato{envId}/{schemaName}
. Para valores múltiples, separe los valores con comas.
Si alcanza el número máximo de caracteres pero aún necesita agregar más copilotos, agregue otra etiqueta con un nombre descriptivo pero único (por ejemplo: AllowedCopilots2
).
El valor secreto se almacena en caché en el tiempo de ejecución del diálogo durante cinco minutos. Las lecturas erróneas se almacenan en caché durante 30 segundos.
Advertencia
Al agregar el secreto en el copiloto, podría exponer el valor de este secreto a todos los usuarios que puedan editar el copiloto en el entorno, ya que dichos usuarios podrían editar el copiloto para devolver el valor en el nodo SendMessage
.
Variables del sistema
Cada copiloto viene con variables de sistema integradas que brindan información adicional sobre una conversación.
Nota
Para obtener más información sobre las variables de copiloto habilitadas por voz, consulte Usar variables de voz.
No todas las variables del sistema se muestran en la lista. Debe acceder a estas variables ocultas del sistema con una fórmula de Power Fx.
Para utilizar variables del sistema en una fórmula de Power Fx, debe agregar System.
antes del nombre de variable. Por ejemplo, para incluir la variable del sistema User.DisplayName
en una fórmula, haga referencia a ella como System.User.DisplayName
.
Name | Type | Definición |
---|---|---|
Activity.Attachments |
tabla | Los archivos adjuntos proporcionados por el usuario |
Activity.Channel |
opción | El ID de canal de la conversación actual |
Activity.ChannelData |
cualquiera | Un objeto que contiene contenido específico del canal |
Activity.ChannelId |
string | El ID de canal de la conversación actual, como cadena |
Activity.From.Id |
string | El ID único específico del canal para el remitente |
Activity.From.Name |
string | El nombre descriptivo del remitente específico del canal |
Activity.Name |
string | El nombre del evento |
Activity.Recipient.Id |
string | Tipo de propiedad de la actividad entrante. |
Activity.Recipient.Name |
string | Representa el nombre para mostrar del copiloto dentro del canal. En el contexto del canal de telefonía, el valor de esta variable será el número de teléfono al que está asociado el copiloto. |
Activity.Text |
string | El mensaje más reciente enviado por el usuario |
Activity.Type |
opción | Tipo de actividad |
Activity.TypeId |
string | Tipo de actividad, como una cadena |
Activity.Value |
cualquiera | Valor con extremo abierto |
Bot.EnvironmentId |
string | El Id. del entorno del copiloto |
Bot.Id |
string | El Id. del copiloto |
Bot.Name |
string | El nombre de su copiloto |
Bot.SchemaName |
string | El nombre del esquema del copiloto |
Bot.TenantId |
string | El Id. de inquilino del copiloto |
ClientPluginActions |
opción | Colección de acciones de complementos de cliente dinámicos a tener en cuenta para acciones generativas |
Conversation.Id |
string | El id. exclusivo de la conversación actual |
Conversation.InTestMode |
booleano | Indicador booleano que representa si la conversación está sucediendo en el lienzo de prueba |
Conversation.LocalTimeZone |
string | Nombre de la zona horaria que utilizará el usuario en el formato de la base de datos de zonas horarias de IANA |
Conversation.LocalTimeZoneOffset |
datetime | La diferencia horaria con respecto a UTC para la zona horaria local actual |
Error.Code |
string | El código del error actual.
Nota: Esta variable solo se admite si el desencadenador es |
Error.Message |
string | El mensaje de error para el error actual.
Nota: Esta variable solo se admite si el desencadenador es |
FallbackCount |
número | Esta variable cuenta las veces que un tema no pudo coincidir con la entrada del usuario.
Nota: Esta variable solo se admite si el desencadenador es |
InactivityTimer.Continue |
booleano | Bandera booleana que representa si el temporizador debe continuar.
Nota: Esta variable solo se admite si el desencadenador es |
InactivityTimer.Count |
número | Número de veces que el temporizador OnInactivity se ha activado debido a la inactividad del usuario después del tiempo configurado.
Nota: Esta variable solo se admite si el desencadenador es |
LastMessage.Id |
string | El id. del mensaje anterior enviado por el usuario |
LastMessage.Text |
string | El mensaje anterior enviado por el usuario |
Recognizer.ExtractedEntities |
opción | Representa las entidades extraídas del mensaje desencadenante.
Nota: Esta variable solo se admite si el desencadenador es |
Recognizer.IntentOptions |
opción | Representa las opciones de intención cuando el reconocedor devuelve resultados ambiguos.
Nota: Esta variable solo se admite si el desencadenador es |
Recognizer.SelectedIntent |
opción | Representa la intención seleccionada del reconocedor.
Nota: Esta variable solo se admite si el desencadenador es |
Recognizer.TriggeringMessage.Id |
string | El id. del mensaje de usuario que activó el tema actual |
Recognizer.TriggeringMessage.Text |
string | El mensaje de usuario que activó el tema actual |
Recognizer.MultipleTopicsMatchedReason |
string | Se utiliza para determinar por qué coincidieron varios temas.
Nota: Esta variable solo se admite si el desencadenador es |
User.Language |
opción | Esta variable se utiliza para establecer la configuración regional del idioma del usuario por conversación. |
SignInReason |
opción | Se utiliza para determinar qué opción de inicio de sesión se necesita cuando se activa tema.
Nota: Esta variable solo se admite si el desencadenador es |
Variables para autenticación integrada (predeterminado)
Las siguientes variables están disponibles cuando ha configurado su copiloto para autenticarse con Microsoft. Esto utilizará la autenticación de Entra ID y solo permitirá canales de Teams y PowerApps. Es el valor predeterminado de nuevos copilotos.
Name | Type | Definición |
---|---|---|
User.DisplayName |
string | El nombre para mostrar del usuario que está hablando actualmente con copiloto. |
User.Email |
string | La dirección de correo electrónico del usuario que está hablando actualmente con copiloto. |
User.FirstName |
string | El nombre de pila del usuario que está hablando actualmente con copiloto. |
User.Id |
string | El identificador único del usuario que está hablando actualmente con copiloto. |
User.IsLoggedIn |
booleano | Bandera booleana que representa si el usuario que está hablando actualmente con copiloto está autenticado o no. |
User.LastName |
string | Los apellidos del usuario que está hablando actualmente con el copiloto. |
User.PrincipalName |
string | El nombre principal de usuario del usuario que está hablando actualmente con el copiloto. |
Variables para la autenticación manual con OAuth genérico 2
Las siguientes variables están disponibles cuando ha configurado su copiloto para usar el proveedor de servicios genérico OAuth 2.
Name | Type | Definición |
---|---|---|
User.AccessToken |
string | El token de acceso para el usuario que se autentica con el copiloto. |
User.DisplayName |
string | El nombre para mostrar del usuario que está hablando actualmente con copiloto. |
User.Id |
string | El identificador único del usuario que está hablando actualmente con copiloto. |
User.IsLoggedIn |
booleano | Bandera booleana que representa si el usuario que está hablando actualmente con copiloto está autenticado o no. |
Variables para la autenticación manual con Microsoft Entra ID
Las siguientes variables están disponibles cuando ha configurado su copiloto para usar los proveedores de servicios de Microsoft Entra ID (anteriormente Azure Active Directory).
Name | Type | Definición |
---|---|---|
User.AccessToken |
string | El token de acceso para el usuario que se autentica con el copiloto. |
User.DisplayName |
string | El nombre para mostrar del usuario que está hablando actualmente con copiloto. |
User.Email |
string | La dirección de correo electrónico del usuario que está hablando actualmente con copiloto. |
User.FirstName |
string | El nombre de pila del usuario que está hablando actualmente con copiloto. |
User.Id |
string | El identificador único del usuario que está hablando actualmente con copiloto. |
User.IsLoggedIn |
booleano | Bandera booleana que representa si el usuario que está hablando actualmente con copiloto está autenticado o no. |
User.LastName |
string | Los apellidos del usuario que está hablando actualmente con el copiloto. |
User.PrincipalName |
string | El nombre principal de usuario del usuario que está hablando actualmente con el copiloto. |
Variables para voz / IVR
Las siguientes variables solo están disponibles en los copilotos habilitados por voz.
Name | Type | Definición |
---|---|---|
Activity.InputDTMFKeys |
string | El valor de la clave DTMF sin procesar que se recibió desde la telefonía. |
Activity.SpeechRecognition.Confidence |
número | La puntuación de confianza para la hipótesis ASR resultado completo, 0 a 1. |
Activity.SpeechRecognition.MinimallyFormattedText |
string | Texto ligeramente formateado del resultado de la hipótesis ASR. Por ejemplo, quinientos dólares. Las palabras están escritas, pero se incluyen las mayúsculas y la puntuación básicas. |
Activity.UserInputType |
opción | El tipo de entrada de la entrada más reciente del usuario final. El valor puede ser prueba, voz o DTMF. |
Conversation.OnlyAllowDTMF |
booleano | Bandera booleana que representa si el IVR debe configurarse en modo solo DTMF en tiempo de ejecución. |
Conversation.SipUuiHeaderValue |
string | La cadena de encabezado UUI utilizada para pasar contexto a IVR al iniciar la llamada. |
Pasar variables entre temas
Cuando redirige un tema a otro, puede pasar los valores de las variables entre el tema original y el destino tema. Pasar variables entre temas es especialmente útil cuando un tema anterior ya recopiló información que un tema posterior necesita. Sus usuarios agradecerán no tener que volver a responder a las mismas preguntas de nuevo.
Recibir valores de otros temas
Cuando un tema define una variable (por ejemplo, mediante un nodo de pregunta), el copiloto formula al usuario la pregunta para completar el valor de la variable. Si el copiloto ya ha adquirido el valor en un tema anterior, no hay razón para volver a hacer la pregunta. En estos casos, puede establecer la variable en Recibir valores de otros temas. Cuando otro tema redirige a este, puede pasar el valro de una variable (o valores literales) a esta variable y omitir la pregunta. La experiencia del usuario que habla con el copiloto es perfecta.
En este ejemplo, usaremos dos temas, Saludo y Hablar con el cliente. Ambos temas piden el nombre del cliente. Sin embargo, si el Saludo tema se ejecuta primero, Hablar con el cliente tema omite su pregunta. En su lugar, usa el valor de la variable que se pasa desde el Saludo tema.
Este es el flujo de la conversación con el cliente tema:
Como se muestra en el panel del copiloto de prueba, si este tema se activa primero, pregunta al usuario: "¿Cómo debo llamarte?" Almacena el valor en una variable de cadena llamada userName
. La variable userName
también está configurada para obtener su valor de otros temas. El tema concluye con el mensaje "Espero que tengas un día maravilloso, {userName}".
Este es el flujo del tema de saludo:
Como se muestra en el panel del copiloto de prueba, si este tema se activa primero, pregunta al usuario: "¿Cómo se llama?" Almacena el valor en una variable de cadena llamada UserName
. El tema envía el mensaje: "¡Encantado de conocerle, {UserName}!" A continuación, se redirige a Hable con el cliente tema, que envía el mensaje: "Espero que esté teniendo un día maravilloso, {userName}". Tenga en cuenta, sin embargo, que el tema Hablar con el cliente omitió volver a preguntar el nombre del usuario. En su lugar, usó el valor de la variable UserName
pasada del tema Saludo.
Finalmente, aquí está esa segunda conversación nuevamente, esta vez desde la perspectiva de Talk to Customer tema:
Veamos los pasos para configurar un tema para recibir valores de otros temas. Usaremos nuestro ejemplo actual, pero los mismos pasos funcionarán siempre que un tema necesite obtener un valor de un tema anterior.
Configure el destino tema
El destino tema es el tema al que se redirige, el que recibirá valores de otros temas. En nuestro ejemplo, es Hable con el cliente.
Crea o ve a tu destino tema.
Agregue un nodo Pregunta e introduzca el mensaje
What should I call you?
.En Identificar, seleccione la entidad preconstruida Nombre de la persona.
Seleccione la variable para abrirla en el panel de propiedades de variables. Asígnele el nombre
userName
y luego seleccione Recibir valores de otros temas.En el cuadro de mensaje, escriba
I hope you're having a wonderful day,
.Seleccione el icono para insertar variable ({x}) y, a continuación, userName.
Seleccione el espacio después de la variable y escriba
!
.Guarde el tema.
Establecer el tema de origen
El tema de origen es el tema que realiza la redirección, la que proporciona el valor que se pasará al destino tema. En nuestro ejemplo, es Saludo.
Vaya al tema de origen.
Agregue un nodo de redireccionamiento y seleccione el tema de destino.
Seleccione + Agregar entrada y luego seleccione la variable del tema de destino al que desea pasar el valor.
Seleccione el icono > y luego seleccione la variable cuyo valor desea pasar.
El nodo de redireccionamiento debería tener el siguiente aspecto:
Guarde el tema.
Devolver valores a temas originales
Cuando se redirige un tema y se obtiene una variable haciendo una pregunta o de alguna otra forma, la variable se puede devolver al tema original. La variable pasa a formar parte del tema original y se puede utilizar como cualquier otra variable. Información que obtiene el copiloto y que por tanto está disponible en todos los temas, lo que reduce la necesidad de variables globales.
Continuemos con el ejemplo de la sección anterior. Haremos una nueva pregunta en Hablar con el cliente tema y luego devolveremos la respuesta al Saludo tema.
Configure la fuente tema para una variable devuelta
Cuando devuelve una variable a un tema, la fuente tema es el tema al que se redirige, el que proporciona el valor que se devolverá al tema original. En eset ejemplo, es Hable con el cliente.
Vaya al tema de origen.
Agregue un nodo Pregunta e introduzca el mensaje
What city do you live in?
.En Identificar, seleccione la entidad preconstruida Ciudad.
Seleccione la variable para abrirla en el panel de propiedades de variables. Asígnele el nombre
userCity
y luego seleccione Devolver valores a los temas originales.Guarde el tema.
Configurar el tema de destino para una variable devuelta
Cuando devuelve una variable a un tema, el destino tema es el tema que realiza la redirección, el que recibirá valores de otros temas. En nuestro ejemplo, es Saludo.
Vaya al tema de destino.
La variable que seleccionó en la fuente tema debería aparecer en el nodo Redirigir como una variable de salida.
Guarde el tema.