La biblioteca cliente de Actions on Google para Node.js es la forma recomendada de acceder y, luego, interactuar con la plataforma de Actions on Google si creas un webhook de entrega en JavaScript.
Introducción
La biblioteca cliente de Node.js es una biblioteca de entregas para Actions on Google que proporciona las siguientes características:
- Admite todas las funciones de Actions on Google, incluidos el texto y las respuestas multimedia enriquecidas, el acceso a la cuenta, el almacenamiento de datos, las transacciones y mucho más.
- Proporciona una capa idiomática de abstracción en JavaScript que une la API de webhook HTTP/JSON de conversación.
- Controla los detalles de bajo nivel de la comunicación entre tu entrega y la plataforma de Actions on Google.
- Se puede instalar con herramientas de administración de paquetes conocidas, como
npmoyarn. - Te permite implementar con facilidad tu webhook de entrega en plataformas de procesamiento sin servidores, como Cloud Functions para Firebase o AWS Lambda. También puedes alojar el webhook de entrega en un proveedor de servicios en la nube o en un entorno autoadministrado y alojado.
- Es compatible con Node.js 6.0.0 y versiones posteriores.
Puedes usar la biblioteca cliente junto con la integración de Dialogflow para Actions on Google o con el SDK de Actions.
Para ver muestras de código completas a fin de usar la biblioteca cliente, puedes visitar la página de muestras.
Cómo ver la referencia de la API
La referencia de la API se aloja en la página de GitHub de la biblioteca cliente de Actions on Google para Node.js.
También puedes generar una copia local de la referencia si ejecutas el siguiente comando desde el directorio en el que descargaste el código de la biblioteca cliente:
yarn docs
Los documentos generados estarán disponibles en la carpeta docs del directorio en el que descargaste el código de la biblioteca cliente.
Comprende el funcionamiento
Antes de usar la biblioteca cliente, es útil comprender cómo tu webhook de entrega usa la biblioteca cliente para procesar las solicitudes de los usuarios que Actions on Google envía a tu entrega.
Cuando creas un webhook de entrega en JavaScript, puedes implementar y alojar tu código en un entorno de computación sin servidores, como Cloud Functions para Firebase o AWS Lambda de Google. También puedes alojar el código por tu cuenta sin trabajo adicional mediante el marco de trabajo web Express.
Dentro del entorno de ejecución, el webhook de entregas puede llamar a funciones en la biblioteca cliente para procesar las solicitudes de los usuarios y enviar respuestas a Actions on Google a fin de procesarlas en resultados de usuario.
A continuación, se resumen brevemente las tareas clave que tu webhook de entregas maneja con la ayuda de la biblioteca cliente:
- Recepción de solicitudes de usuario: Cuando un usuario realiza una consulta al Asistente de Google, la plataforma de Actions on Google envía una solicitud HTTP a tu webhook de entrega; la solicitud incluye una carga útil de JSON que contiene el intent y otros datos, como el texto sin procesar de la entrada del usuario y las capacidades de la superficie del dispositivo del usuario. Para obtener más ejemplos sobre el contenido de la carga útil JSON, consulta las guías de formato de webhook de Dialogflow y de formato de conversación de conversación.
- Detección de formato de llamadas del framework: Para los frameworks compatibles, la biblioteca cliente detecta automáticamente el formato de llamada del framework (por ejemplo, si la solicitud provino del framework web exprés o de AWS Lambda) y sabe cómo manejar sin problemas la comunicación con la plataforma de Actions on Google.
- Procesamiento del controlador de servicios: La biblioteca cliente representa la API de webhook de HTTP/JSON de la conversación para el SDK de Dialogflow y Actions como función del servicio. El webhook de entrega usa el servicio adecuado para crear una instancia global de
app. La instanciaappactúa como un controlador para solicitudes HTTP y comprende el protocolo específico del servicio. - Procesamiento de conversaciones: La biblioteca cliente representa la información por conversación como un objeto
Conversationadjunto a la instanciaapp. Tu webhook de entrega puede usar el objetoConversationpara recuperar datos almacenados en conversaciones entre conversaciones o información de estado, enviar respuestas a los usuarios o cerrar el micrófono. - Procesamiento de Middleware: La biblioteca cliente te permite crear tu propio middleware de servicios de conversación, que consiste en una o más funciones que defines que la biblioteca cliente se ejecuta automáticamente antes de llamar al controlador del intent. Tu webhook de entrega puede usar tu middleware para agregar propiedades o clases de ayuda al objeto
Conversation. - Procesamiento del controlador de intents: La biblioteca cliente te permite definir controladores para intents que comprende el webhook de entrega. Para Dialogflow, la biblioteca cliente enruta la solicitud al controlador del intent correcto mediante la asignación a la string exacta del nombre del intent definido en la consola de Dialogflow. Para el SDK de Actions, se enruta según la propiedad
intentque se envía desde Actions on Google. - Envía respuestas a los usuarios: Para crear respuestas, el webhook de entrega llama a la función
Conversation#ask(). Se puede llamar a la funciónask()varias veces para compilar la respuesta de forma incremental. La biblioteca cliente serializa la respuesta en una solicitud HTTP con una carga útil de JSON y la envía a Actions on Google. La funciónclose()tiene un comportamiento similar aask(), pero cierra la conversación.
Configura el entorno de desarrollo local
Antes de implementar tu webhook de entrega, asegúrate de instalar la biblioteca cliente.
Instala la biblioteca cliente
La manera más fácil de instalar la biblioteca cliente en tu entorno de desarrollo local es usar un administrador de paquetes, como npm o yarn.
Para instalarlo, ejecuta uno de estos comandos desde la terminal:
- Si usa npm:
npm install actions-on-google - Si usa hilo:
yarn add actions-on-google
Configura las carpetas del proyecto
Según dónde planees implementar el webhook de entrega (Cloud Functions de Firebase para Firebase, AWS Lambda o Express autoalojado), es posible que debas crear una estructura de carpeta de proyecto específica para guardar los archivos.
Por ejemplo, si usas Cloud Functions para Firebase, puedes configurar
las carpetas de proyecto necesarias mediante los pasos que se describen en
Configura Node.js y Firebase CLI , y
Inicializa Firebase para Cloud Functions. En el caso de Cloud Functions para Firebase, por lo general, debes escribir el webhook de entrega en el archivo /functions/index.js.
Cómo compilar una instancia de app
Actions on Google usa formatos de mensajería específicos para intercambiar solicitudes y respuestas con tu webhook de entrega, según si compilas una acción conversacional mediante Dialogflow o el SDK de Actions, o bien si compilas una acción de casa inteligente.
Para representar estos diferentes protocolos de solicitud y respuesta, la biblioteca cliente proporciona tres funciones de servicio:
Los dos servicios de conversación (SDK de Dialogflow y Actions) utilizan el protocolo de webhook de conversación, pero cada servicio une los mensajes de forma diferente.
Debes usar un servicio para crear una instancia de app. La instancia app encapsula el estado global y la lógica de entrega de tu webhook y controla la comunicación entre Actions on Google y tu entrega mediante el protocolo específico del servicio.
Puedes configurar las propiedades de la instancia app y llamar a sus métodos para dirigir el comportamiento del webhook de entregas. También puedes conectar fácilmente la instancia de app a un entorno de computación sin servidores, como Cloud Functions para Firebase, que acepta funciones de JavaScript como controladores para las solicitudes HTTP.
Para compilar una instancia de app en el webhook de entrega, sigue estos pasos:
Llama a la función
require()para importar el módulo "actions-on-google" y cargar el servicio que desees. Por ejemplo, en el siguiente fragmento, se muestra cómo podrías cargar el serviciodialogflowy algunos elementos utilizados para compilar respuestas y asignarlos a una constante llamadadialogflow:// Import the service function and various response classes const { dialogflow, actionssdk, Image, Table, Carousel, } = require('actions-on-google');.En este caso,
actions-on-googlese refiere a una dependencia que se especifica en un archivopackage.jsonde la carpeta de tu proyecto (puedes consultar este archivopackage.jsonde ejemplo para ver un ejemplo).Cuando obtienes una instancia de
app, tienes la opción de especificar las clases que representan respuestas enriquecidas, intents de ayuda y otras funciones de Actions on Google que deseas usar. Para ver la lista completa de clases válidas que puedes cargar, consulta la documentación de referencia de los módulos de respuesta de conversación y intents de ayuda.Llama al servicio que cargaste para crear una instancia de
app. Por ejemplo:const app = dialogflow();
.Para configurar la instancia
appdurante la inicialización, puedes proporcionar un objetooptionscomo primer argumento cuando llames al servicio. (ConsultaDialogflowOptionspara obtener más detalles). Por ejemplo, en el siguiente fragmento, se muestra cómo registrar la carga útil de JSON sin procesar desde la solicitud o respuesta del usuario mediante la configuración de la marca{ debug: true }:
const app = dialogflow({
debug: true
});
Configura controladores para eventos
A fin de procesar los eventos relacionados con Actions on Google creados por la biblioteca cliente durante el ciclo de vida de la interacción del usuario con tu acción, usarás la biblioteca cliente para compilar controladores que procesen las solicitudes de los usuarios y envíen respuestas.
Puedes crear funciones que actúen como controladores para estos tipos principales de eventos que la biblioteca cliente reconoce:
- Eventos de intent: Los intents son identificadores únicos que Actions on Google envía a tu entrega cada vez que un usuario solicita alguna funcionalidad específica. Si usas Dialogflow, esto corresponde a Dialogflow, que hace coincidir una consulta del usuario con un intent en tu agente de Dialogflow.
- Eventos de error: Cuando se produce un error de JavaScript o de la biblioteca cliente, puedes usar la función
catchde la instanciaapppara procesar la excepción de error de forma adecuada. Debes implementar una funcióncatchúnica para controlar todos los errores importantes para tu entrega. - Eventos de resguardo: Un evento de resguardo ocurre cuando el usuario envía una consulta que Actions on Google no puede reconocer. Puedes usar la función
fallbackde la instanciaapppara registrar un controlador de resguardo genérico que se activará si no se encontró una coincidencia para ningún controlador de intents en la solicitud de entrega entrante. Debes implementar una funciónfallbackúnica para controlar todos los eventos de resguardo. Si usas Dialogflow, Dialogflow puede activar un intent de resguardo específico cuando no hay otro intent coincidente. Debes crear el controlador del intent correspondiente para ese intent de resguardo.
Cada vez que el usuario envía una solicitud a tu acción, la instancia de app crea un objeto Conversation que representa esa sesión de conversación. Se puede acceder a este objeto a través del nombre de la variable conv que se pasa en la función del controlador de intents como el primer argumento de la función. Por lo general, usarás el objeto conv en tus controladores para enviarle una respuesta al usuario.
Las búsquedas del usuario también pueden incluir parámetros que tu acción puede extraer y usar para definir mejor las respuestas.
- Si usas el SDK de Actions, debes definir los parámetros en el paquete de acciones. Para ver un ejemplo de cómo puedes extraer parámetros de los intents, consulta la muestra de código de Eliza.
- Si usas Dialogflow, puedes acceder a los valores del parámetro a través de la variable
params. Para ver ejemplos del manejo de intents con parámetros en Dialogflow, consulta Parámetros de acceso y contextos.
Cómo configurar controladores para intents
Para configurar el controlador de un intent, llama a la función intent() de tu instancia de app. Por ejemplo, si usas Dialogflow, esta es la función DialogflowApp#intent(). En los argumentos, especifica el nombre del intent y proporciona una función de controlador.
Si usas Dialogflow, no necesitas configurar controladores para cada intent en tu agente. En cambio, puedes aprovechar el controlador de respuestas integrado de Dialogflow para controlar automáticamente los intents sin implementar tus propias funciones de controlador. Por ejemplo, el intent de bienvenida predeterminado se puede delegar a Dialogflow de esta manera.
En el siguiente ejemplo, se muestran los controladores de intent para los intents "greeting" y "bye". Sus funciones de controlador anónimas toman un argumento conv y envían una respuesta de string simple al usuario a través de la función conv.ask():
app.intent('Default Welcome Intent', (conv) => {
conv.ask('How are you?');
});
app.intent('bye', (conv) => {
conv.close('See you later!');
});
Ten en cuenta que la función close() es similar a ask(), excepto que cierra el micrófono y la conversación finaliza.
Si quieres obtener más información para compilar controladores para intents, consulta Cómo crear tu controlador de intents.
Configura controladores para eventos de error
Para establecer que los controladores tengan errores, llama a la función catch() de tu instancia de app. (Por ejemplo, si usas Dialogflow, esta es la función DialogflowApp#catch()).
En el siguiente ejemplo, se muestra un controlador de errores de captura simple que envía el error al resultado de la consola y envía una respuesta de string simple para notificar al usuario a través de la función conv.ask():
app.catch((conv, error) => {
console.error(error);
conv.ask('I encountered a glitch. Can you say that again?');
});
Configura controladores para eventos de resguardo
Para establecer un controlador de resguardo genérico cuando no hay coincidencias de intents para la solicitud entrante de entrega, llama a la función fallback() de la instancia app. (Por ejemplo, si usas Dialogflow, esta es la función DialogflowApp#fallback()).
En el siguiente ejemplo, se muestra un controlador de resguardo simple que envía una respuesta de string simple para pedirle al usuario a través de la función conv.ask():
app.fallback((conv) => {
conv.ask(`I couldn't understand. Can you say that again?`);
});
Compila tu controlador de intents
En esta sección, se abarcan algunos casos de uso comunes cuando implementas controladores de intents con la biblioteca cliente. Para ver cómo la biblioteca cliente coincide con el intent, consulta la sección "Procesamiento del controlador de intents" en Comprende cómo funciona.
Accede a parámetros y contextos
Si usas Dialogflow, puedes definir parámetros y contextos en tu agente de Dialogflow para mantener la información del estado y controlar el flujo de la conversación.
Los parámetros son útiles para capturar palabras, frases o valores importantes en las consultas de los usuarios. Dialogflow extrae los parámetros correspondientes de las consultas del usuario en el tiempo de ejecución, y puedes procesar estos valores de parámetros en tu webhook de entrega a fin de determinar cómo responder a los usuarios.
Cada vez que el usuario envía una solicitud a tu acción, la instancia de DialogflowApp crea un objeto parameters que representa los valores de los parámetros que Dialogflow extrajo de esa solicitud. Se puede acceder a este objeto a través del nombre de la variable params.
En el siguiente fragmento, se muestra cómo puedes acceder a la propiedad name desde el objeto params cuando el usuario envía una solicitud:
app.intent('Default Welcome Intent', (conv, params) => {
conv.ask(`How are you, ${params.name}?`);
});
Este es un fragmento alternativo que hace lo mismo. Las llaves ({}) realizan la desestructuración de JavaScript para tomar la propiedad name del objeto parameters y usarla como una variable local:
app.intent('Default Welcome Intent', (conv, {name}) => {
conv.ask(`How are you, ${name}?`);
});
En el siguiente fragmento, el nombre del parámetro es full-name, pero
está desestructurado y se asigna a una variable local llamada name:
app.intent('Default Welcome Intent', (conv, {'full-name': name}) => {
conv.ask(`How are you, ${name}?`);
});
Los contextos son una función avanzada de Dialogflow. Puedes usar contextos para administrar el estado de la conversación, el flujo y la ramificación. La biblioteca cliente proporciona acceso a un contexto a través del objeto DialogflowConversation#contexts. En el siguiente fragmento, se muestra cómo puedes establecer un contexto de manera programática en tu webhook de entrega y cómo recuperar el objeto de contexto:
app.intent('intent1', (conv) => {
const lifespan = 5;
const contextParameters = {
color: 'red',
};
conv.contexts.set('context1', lifespan, contextParameters);
// ...
conv.ask('...');
});
app.intent('intent2', (conv) => {
const context1 = conv.contexts.get('context1');
const contextParameters = context1.parameters;
// ...
conv.ask('...');
});
app.intent('intent3', (conv) => {
conv.contexts.delete('context1');
// ...
conv.ask('...');
});
Cómo acceder a los resultados de intents de ayuda
Para mayor comodidad, la biblioteca cliente proporciona clases de intents de ayuda que unen tipos comunes de datos del usuario que las acciones solicitan con frecuencia. Estas incluyen clases que representan los resultados de los diversos intents auxiliares de Actions on Google. Debes usar intents auxiliares cuando desees que Asistente de Google controle partes de la conversación en las que el usuario debe proporcionar entradas para continuar la conversación.
Ejemplo: Resultados del asistente de confirmación
El intent auxiliar de confirmación te permite pedir una confirmación de sí o no al usuario y obtener la respuesta resultante.
En el siguiente fragmento, se muestra cómo el webhook puede personalizar su respuesta en función de los resultados que muestra el intent auxiliar de confirmación. Para ver un ejemplo más completo, consulta la documentación de referencia de la clase Confirmation.
// Create Dialogflow intent with `actions_intent_CONFIRMATION` event
app.intent('get_confirmation', (conv, input, confirmation) => {
if (confirmation) {
conv.close(`Great! I'm glad you want to do it!`);
} else {
conv.close(`That's okay. Let's not do it now.`);
}
});
Ejemplo: Resultados de carrusel
En el siguiente fragmento, se muestra cómo el webhook de entrega puede personalizar su respuesta en función de la entrada del usuario para un carrusel. El componente de carrusel permite que tu acción presente una selección de opciones para que elijan los usuarios. Para ver un ejemplo más completo, consulta la documentación de referencia de la clase Carousel.
app.intent('carousel', (conv) => {
conv.ask('Which of these looks good?');
conv.ask(new Carousel({
items: {
car: {
title: 'Car',
description: 'A four wheel vehicle',
synonyms: ['automobile', 'vehicle'],
},
plane: {
title: 'Plane',
description: 'A flying machine',
synonyms: ['aeroplane', 'jet'],
}
}
}));
});
// Create Dialogflow intent with `actions_intent_OPTION` event
app.intent('get_carousel_option', (conv, input, option) => {
if (option === 'one') {
conv.close(`Number one is a great choice!`);
} else {
conv.close(`Number ${option} is a great choice!`);
}
});
Configura objetos de respuesta de conversación
La biblioteca cliente proporciona clases de respuesta de conversación que representan respuestas enriquecidas o elementos multimedia que la acción puede enviar. Por lo general, envías estas respuestas o elementos cuando los usuarios no necesitan aportar para continuar la conversación.
Ejemplo: Imagen
En el siguiente fragmento, se muestra cómo el webhook de entrega puede enviar un Image en una respuesta que la biblioteca adjuntará automáticamente a una respuesta de BasicCard:
app.intent('Default Welcome Intent', (conv) => {
conv.ask('Hi, how is it going?');
conv.ask(`Here's a picture of a cat`);
conv.ask(new Image({
url: '/web/fundamentals/accessibility/semantics-builtin/imgs/160204193356-01-cat-500.jpg',
alt: 'A cat',
}));
});
Realiza llamadas a funciones asíncronas
La biblioteca cliente de Actions on Google para Node.js se diseñó para la programación asíncrona. El controlador del intent puede mostrar una promesa que se resuelve cuando el webhook de entrega termina de generar una respuesta.
En el siguiente fragmento, se muestra cómo realizar una llamada a una función asíncrona para mostrar un objeto de promesa y, luego, responder con un mensaje si el webhook de entregas recibe el intent de “saludo”. En este fragmento, la promesa garantiza que tu webhook de entrega muestre una respuesta de conversación solo después de que se resuelva la promesa para la llamada a la API externa.
En este ejemplo, usamos una API falsa para obtener los datos del clima.
/**
* Make an external API call to get weather data.
* @return {Promise<string>}
*/
const forecast = () => {
// ...
};
app.intent('Default Welcome Intent', (conv) => {
return forecast().then((weather) => {
conv.ask('How are you?');
conv.ask(`Today's weather is ${weather}.`);
});
});
El siguiente fragmento de código optimizado tiene el mismo efecto, pero usa la función async await que se introdujo en ECMA 2017 (versión 8 de Node.js). Si quieres usar
este código con Cloud Functions para Firebase, asegúrate de usar la
versión correcta de las herramientas de Firebase
y tener la configuración correcta.
app.intent('Default Welcome Intent', async (conv) => {
const weather = await forecast();
conv.ask('How are you?');
conv.ask(`Today's weather is ${weather}.`);
});
Almacena datos de conversaciones
La biblioteca cliente permite que el webhook de entrega guarde datos en conversaciones para usarlos en el futuro. Los objetos clave que puedes usar para el almacenamiento de datos incluyen los siguientes:
DialogflowConversation#dataoActionsSdkConversation#data: guarda los datos en formato JSON durante la sesión de una sola conversación entre el usuario y la acción.Conversation#user.storage: Guarda datos en formato JSON en varias sesiones de conversación.
En el siguiente fragmento, se muestra cómo el webhook de entrega puede almacenar datos en una propiedad arbitraria que definiste (someProperty) y adjuntarla al objeto Conversation#user.storage. Para ver un ejemplo más completo, consulta la documentación de referencia de la clase Conversation#user.storage.
app.intent('Default Welcome Intent', (conv) => {
conv.user.storage.someProperty = 'someValue';
conv.ask('...');
});
Puedes usar el objeto Conversation#user para obtener información sobre el usuario, incluidos un identificador de string y tu información personal. Algunos campos, como conv.user.name.display y conv.user.email, requieren la solicitud de conv.ask(new Permission) para NAME y conv.ask(new SignIn) para el Acceso con Google, respectivamente.
const {Permission} = require('actions-on-google');
app.intent('Default Welcome Intent', (conv) => {
if (conv.user.last.seen) {
conv.ask('Welcome back! How are you?');
} else {
conv.ask('Nice to meet you! How are you doing?');
}
});
app.intent('permission', (conv) => {
conv.ask(new Permission({
context: 'To greet you personally',
permissions: 'NAME',
}));
});
// Create Dialogflow intent with `actions_intent_PERMISSION` event
app.intent('get_permission', (conv, input, granted) => {
if (granted) {
conv.close(`Hi ${conv.user.name.display}!`);
} else {
// User did not grant permission
conv.close(`Hello!`);
}
});
Escalamiento con middleware
Puedes extender la biblioteca cliente a través del middleware.
La capa de middleware consta de una o más funciones que defines, la cual la biblioteca cliente ejecuta automáticamente antes de llamar al controlador del intent. Usar una capa de middleware te permite modificar la instancia de Conversation y agregar funcionalidades adicionales.
Los servicios del SDK de Dialogflow y Actions exponen una función app.middleware() que te permite agregar propiedades o clases auxiliares a la instancia Conversation.
En el siguiente fragmento, se muestra un ejemplo de cómo podrías usar middleware:
class Helper {
constructor(conv) {
this.conv = conv;
}
func1() {
this.conv.ask(`What's up?`);
}
}
app.middleware((conv) => {
conv.helper = new Helper(conv);
});
app.intent('Default Welcome Intent', (conv) => {
conv.helper.func1();
});
Exporte su aplicación
Si deseas exponer tu webhook de entrega en un framework web o una plataforma de computación sin servidores, debes exportar el objeto app como un webhook de acceso público. La biblioteca cliente admite la implementación en varios entornos listos para usar.
En los siguientes fragmentos, se muestra cómo puedes exportar app dentro de los diferentes entornos de ejecución:
Ejemplo: Cloud Functions para Firebase
const functions = require('firebase-functions');
// ... app code here
exports.fulfillment = functions.https.onRequest(app);
Ejemplo: Editor directo de Dialogflow
const functions = require('firebase-functions');
// ... app code here
// Exported function name must be 'dialogflowFirebaseFulfillment'
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);
Ejemplo: Servidor Express autoalojado (simple)
const express = require('express');
const bodyParser = require('body-parser');
// ... app code here
express().use(bodyParser.json(), app).listen(3000);
Ejemplo: Servidor Express autoalojado (varias rutas)
const express = require('express');
const bodyParser = require('body-parser');
// ... app code here
const expressApp = express().use(bodyParser.json());
expressApp.post('/fulfillment', app);
expressApp.listen(3000);
Ejemplo: Puerta de enlace de la API de AWS Lambda
// ... app code here exports.fulfillment = app;