Uso de variables

Artículo
04/02/2024

Importante

Las capacidades y características de Power Virtual Agents son ahora parte de Microsoft Copilot Studio tras importantes inversiones en IA generativa e integraciones mejoradas en Microsoft Copilot.

Algunos artículos y capturas de pantalla pueden hacer referencia a Power Virtual Agents mientras actualizamos la documentación y el contenido de capacitación.

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.

Aplicación web
Clásico

Las variables pueden existir en tres 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.

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 que tienen 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

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

Captura de pantalla de un nodo Pregunta, con el nombre y el tipo de la variable predeterminada resaltados.

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.

Captura de pantalla de un nodo Pregunta con el menú Elegir información para identificar el menú abierto y la entidad Nombre de persona resaltada.

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

Captura de pantalla que muestra el uso de un valor literal para una variable denominada productName.

Captura de pantalla que muestra un valor literal de una variable de entrada en un nodo de redireccionamiento.

El nodo intenta interpretar los valores literales como cadena, número o tipo 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 de propiedades de variable.

Para abrir el panel de variables, en la barra de menú de tema, seleccione Variables.

Captura de pantalla del panel Variables en el lienzo de creación de Microsoft Copilot Studio, con el botón Variables resaltado.

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 de propiedades de la variable, seleccione una variable en el panel de variables. También puede abrir el panel de propiedades de la variable seleccionando una variable en cualquier nodo.

Captura de pantalla del panel Propiedades de variable.

Variables del sistema

Cada copiloto viene con variables de sistema integradas que brindan información adicional sobre una conversación.

Captura de pantalla de variables del sistema en un tema de copiloto

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, debe referirse a ella como System.User.DisplayName.

Name	Type	Oculto	Definición
Canal de actividades	opción	visible	El ID de canal de la conversación actual
Activity.ChannelData	cualquiera	hidden	Un objeto que contiene contenido específico del canal
Activity.ChannelId	string	hidden	El ID de canal de la conversación actual, como cadena
Activity.From.Id	string	hidden	El ID único específico del canal para el remitente
Activity.From.Name	string	hidden	El nombre descriptivo del remitente específico del canal
Activity.Name	string	visible	El nombre del evento
Activity.Text	string	visible	El mensaje más reciente enviado por el usuario
Activity.Type	opción	visible	Tipo de actividad
Activity.TypeId	string	hidden	Tipo de actividad, como una cadena
Activity.Value	cualquiera	hidden	Valor con extremo abierto
Bot.Name	string	visible	El nombre de su copiloto
Channel.DisplayName	string	hidden	El nombre para mostrar del canal
Conversation.Id	string	visible	El id. exclusivo de la conversación actual
LastActivity.Id	string	visible	El id. de la actividad previamente enviada
LastMessage.Id	string	visible	El id. del mensaje anterior enviado por el usuario
LastMessage.Text	string	visible	El mensaje anterior enviado por el usuario
Recognizer.TriggerMessage.Id	string	visible	El id. del mensaje de usuario que activó el tema actual
Recognizer.TriggerMessage.Text	string	visible	El mensaje de usuario que activó el tema actual
User.DisplayName	string	visible	El nombre para mostrar del usuario que inició sesión

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:

Captura de pantalla del flujo de la conversación del tema Hablar con el cliente.

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:

Captura de pantalla del flujo de la conversación del tema Saludar.

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:

Captura de pantalla del flujo de conversación Hablar con el cliente cuando se activa primero el tema Saludar.

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.
Agregue un nodo Mensaje.
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.

Entidad y tipo de variable

Microsoft Copilot Studio usa entidades para identificar un tipo específico de información de las respuestas de un usuario. Un tipo de variable se asocia a la información identificada cuando se guarda. El tipo de variable es análogo a la entidad.

Cada entidad o tipo de variable corresponde a un tipo base, como se muestra en la tabla siguiente. El tipo base determina los operadores que puede usar cuando construye una expresión lógica con la variable correspondiente. También determina si puede enviar una variable a un flujo o Bot Framework Skills como parámetro de entrada.

Por ejemplo, un tipo base booleano se asigna a un operador "es igual a" y los valores posibles son Verdadero o Falso. Un tipo base de número le proporciona operadores numéricos como "es igual a", "es mayor que" o "es mayor o igual que", etc.

Entity	Tipo base de variable
Opciones de selección múltiple	String
Respuesta completa del usuario	String
Edad	Number
Booleana	Booleana
City	String
Color	String
Continente	String
País o región	String
Fecha y hora	String
Duration	String
Email	String
Evento	String
Lenguaje	String
Money	String
Number	String
Ordinal	String
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	String

Crear una variable

En el lienzo de creación de bots, agregue un nodo de pregunta. Se crea automáticamente una variable en el nodo.

Vaya a la página de Temas de su bot y abra el tema al que desea agregar una variable.
Seleccione Agregar nodo (+), luego, Formular una pregunta.

Se crea automáticamente una variable que contiene la respuesta del usuario.

Seleccionar la entidad que se va a usar

De forma predeterminada, se crea un nodo de pregunta con opciones de opción múltiple. Para usar una entidad predefinida o personalizada diferente, elija qué identificar del nodo.

Captura de pantalla de la selección de una entidad

Cambiar el nombre de una variable

Las variables creadas automáticamente vienen con un nombre predeterminado. Para cambiar el nombre de una variable, seleccione el nombre de la variable, escriba un nombre nuevo y seleccione Listo.

Captura de pantalla del cambio de nombre de una variable

Usar variables en nodos de acción

Cuando usa una variable en un nodo de acción, si su tipo base coincide con un tipo de parámetro que se especifica para un flujo o capacidad de Bot Framework, puede alimentarlo a ese parámetro. La salida de los nodos de acción genera nuevas variables.

Captura de pantalla del uso de una entidad en un nodo de acción

Usa valores literales en los nodos de acción

Puede escribir un valor literal en el campo de entrada de variable en un nodo de acción en lugar de seleccionar una variable del menú.

Captura de pantalla que muestra el uso de valores literales para entradas de acción.

Nodo analizar valor

El nodo Analizar valor le permite convertir un valor de un tipo en un valor de otro tipo. Al agregar un nodo a tema, seleccione Agregar nodo (+), luego Gestión de variables y Analizar valor.

Captura de pantalla de cómo agregar un nodo, seleccionar la administración de variables y luego analizar el valor.

Los escenarios clave que utilizan el nodo Analizar valor se centran en convertir JSON sin procesar o variables sin tipo (cuyo valor o estructura no se conoce hasta el tiempo de ejecución; por ejemplo, ChannelData) en tipos concretos.

El proceso comienza cuando se llama a un Flujo, que a su vez llama a una API. La API devuelve un resultado. Por lo general, necesitaría analizar esta respuesta y devolver una o más variables primitivas a Microsoft Copilot Studio. Con el nodo Analizar valor, puede enviar el resultado completo de la API como una cadena:

{
    "Name": "Gary",
    "Position": "PM",
    "Company": "Microsoft",
    "FormerPositions": [{
            "Position": "Engineer"
        }
    ]
}

La variable de cadena que tiene ahora se puede convertir en una variable de registro, con soporte completo de intellisense en Power Fx, utilizando este nuevo nodo. Un ejemplo con datos de muestra ayudará a ilustrar este proceso.

Ejemplo de uso del nodo Analizar valor

Agregue un nodo Analizar valor y seleccione la variable que desea analizar.
Seleccione el tipo de datos. En este caso, elija "De datos de muestra".
Ahora puede proporcionar JSON haciendo clic en 'Obtener esquema de JSON de muestra'. Al hacer clic aquí, se abre un editor donde puede pegar el ejemplo.
Finalmente, especifique en qué variable desea colocar el valor analizado. Por lo general, crearía una nueva variable para esto.

Tenga en cuenta que la variable de salida ahora es del tipo correcto: Registro.

Ahora puede usar su nueva variable. En el editor de Power Fx, puede ver que obtiene IntelliSense completo para las diversas propiedades.

Captura de pantalla que muestra el acceso a intellisense completo para varias propiedades a través del editor Power FX.

Además de analizar cadenas JSON, un uso clave del nodo de valor Parse será para analizar UntypedObjects en tiempo de ejecución. El más común de ellos será cuando reciba un evento y necesite analizar el valor del evento. O quizás desee analizar la propiedad System.Activity.ChannelData, que varía en tiempo de ejecución según el canal.

En el siguiente ejemplo, si el evento provenía de Teams, necesitaría usar la documentación para desarrolladores de Teams para encontrar un ejemplo de cómo se verá el evento entrante y luego usarlo a partir de datos de muestra como se describe en esta sección.

Captura de pantalla que muestra un evento procedente de Teams.

Pasar variables entre temas

Al redirigir a otros temas, puede pasar valores a variables en el tema de destino u obtener variables de este. Pasar variables entre temas es especialmente útil cuando ya tiene información que el tema necesita. Sus usuarios agradecerán no tener que volver a responder a la pregunta. Esto también es útil cuando refactoriza y separa los temas en componentes reutilizables y desea pasar variables a través de los temas.

Nota

Las variables de tipo Custom Entity, Date and Time, Duration y Multiple-choice no se puede pasar de un tema a otro.

Recibir valores de otros temas

Cuando un tema define una variable (por ejemplo, mediante un nodo de pregunta), el bot formula al usuario la pregunta para completar el valor de la variable. Si el bot ya ha adquirido el valor, no hay razón para volver a hacer la pregunta. En estos casos, puede definir la variable como Recibir valores de otros temas. Cuando otro tema redirige a este, puede pasar una variable (o valores literales) en esta variable y omitir la pregunta. La experiencia para el usuario que habla con el bot es fluida.

Para recibir valores de otros temas, establezca la propiedad de la variable:

En el nodo Pregunta, seleccione la variable de la que desea recibir valores de otros temas.
En el panel Propiedades de las variables, en Tema (alcance limitado), seleccione Recibir valores de otros temas.
Guarde el tema.
Vaya a un tema al que desee redirigir. Siga los pasos en Redirigir a otro tema para redirigir al tema correcto.
Seleccione +Agregar entrada de información para el tema de destino.
Seleccione una variable en el tema redirigido al que desea pasar la variable.
En Escribir o selecciona un valor, seleccione la variable en el tema actual que desea pasar al tema redirigido.

La variable se muestra en el nodo redirigido.

Devolver valores a temas originales

Cuando un tema formula una pregunta, u obtiene de otro modo una variable de una acción, la variable se puede devolver al tema original que se redirigió a ella.

En este caso, la variable también pasa a formar parte del tema original y se puede utilizar como cualquier otra variable. Esto lo ayuda a construir el tema para que la información que obtiene el bot esté disponible en todos los temas, lo que reduce la necesidad de variables globales.

Para devolver una variable al tema original, establezca la propiedad de la variable:

En el nodo Pregunta, seleccione la variable de la que desea recibir valores de otros temas.
En el panel Propiedades de las variables, en Tema (alcance limitado), seleccione Devolver valores a temas originales.
Guarde el tema.
Vaya a un tema al que desee redirigir. Siga los pasos en Redirigir a otro tema para redirigir al tema correcto.

La variable que se devuelve al tema se muestra en el tema redirigido. Utilice la variable devuelta en su tema.

Usar el panel Variables

Use el panel Variables para seleccionar el estado de recepción o devolución de múltiples variables a la vez.

En la barra de menú del tema, seleccione Variables.
Para cada una de las variables del tema, seleccione si desea que los valores se pasen, reciban, o ambos, entre temas.

Usar valores literales en entradas variables

Puede pasar valores literales y variables a un tema. Para pasar un valor literal, escriba el valor que desea utilizar como entrada en lugar de seleccionar una variable.

Captura de pantalla del lienzo de creación que muestra una entrada literal en una variable de entrada en un nodo de redireccionamiento