Crie o fulfillment com a biblioteca de cliente Node.js para Actions on Google (Dialogflow)

A biblioteca de cliente Node.js do Actions on Google é a forma recomendada de acessar e interagindo com a plataforma Actions on Google, webhook de fulfillment em JavaScript.

Introdução

A biblioteca de cliente Node.js é uma biblioteca de fulfillment para Actions on Google que oferecem estes recursos:

  • é compatível com todos os recursos do Actions on Google, incluindo texto e respostas multimídia avançadas; login na conta, armazenamento de dados, transações e muito mais.
  • Fornece uma camada idiomática de abstração em JavaScript que envolve a API webhook HTTP/JSON de conversa.
  • Lida com os detalhes de baixo nível de comunicação entre o atendimento do pedido e na plataforma Actions on Google.
  • Podem ser instalados usando ferramentas de gerenciamento de pacotes conhecidas, como npm ou yarn.
  • Permite implantar facilmente o webhook de fulfillment em plataformas de computação sem servidor como o Cloud Functions para Firebase ou AWS Lambda. Também é possível hospedar seu webhook de fulfillment em um provedor de serviços de nuvem ou em um ambiente auto-hospedado e autogerenciado.
  • É compatível com o Node.js v6.0.0 e versões mais recentes.

Você pode usar a biblioteca de cliente em conjunto com o Integração do Dialogflow para o Actions on Google ou com o SDK do Actions.

Para conferir exemplos completos de código para usar a biblioteca de cliente, acesse a página de exemplos.

Acessar a Referência da API

A referência da API está hospedada na biblioteca de cliente Node.js do Actions on Google página do GitHub.

Você também pode gerar uma cópia local da referência executando o seguinte do diretório em que você fez o download da biblioteca de cliente código:

yarn docs

Os documentos gerados estarão disponíveis na pasta docs do diretório em que você fez o download do código da biblioteca de cliente.

Entenda como funciona

Antes de usar a biblioteca de cliente, é útil entender como seu O webhook de fulfillment usa a biblioteca de cliente para processar solicitações de usuários que O Actions on Google envia para o fulfillment.

Ao criar um webhook de fulfillment em JavaScript, é possível implantar e hospedar seu código em um ambiente de computação sem servidor, como o Cloud Functions para Firebase ou o AWS Lambda. Você também pode hospedar o código sem trabalho extra usando a Express Web Framework.

No ambiente de execução, o webhook de fulfillment pode chamar funções na biblioteca de cliente para processar solicitações do usuário e enviar respostas de volta para as Ações no Google para renderização na saída do usuário.

As principais tarefas que o webhook de fulfillment processa com a ajuda da estão resumidas abaixo:

Figura 1. Arquitetura de alto nível da biblioteca de cliente do Node.js
  1. Receber solicitações de usuários: quando alguém faz uma consulta ao Google Assistente, a plataforma Actions on Google envia uma solicitação HTTP ao webhook de fulfillment; a solicitação inclui um payload JSON que contém a intent e outros dados, como os dados brutos texto da entrada do usuário e os recursos de superfície do dispositivo do usuário. Para mais exemplos do conteúdo de payload JSON, consulte a Formato do webhook do Dialogflow e formato webhook de conversa guias.
  2. Detecção de formato de chamada de framework: para frameworks compatíveis, o a biblioteca de cliente detecta automaticamente o formato de chamada da estrutura (por exemplo, se a solicitação veio do framework da Web Express ou do AWS Lambda) e sabe como lidar com a comunicação com a plataforma Actions on Google.
  3. Processamento do gerenciador de serviços:a biblioteca de cliente representa a API de webhook HTTP/JSON de conversa para o Dialogflow e o SDK do Actions como serviço. O webhook de fulfillment usa o serviço apropriado para criar uma instância global de app. A instância app atua como um gerenciador de HTTP solicitações e entende o protocolo específico do serviço.
  4. Processamento de conversas:a biblioteca de cliente representa informações por conversa como um objeto Conversation anexado ao app. O webhook de fulfillment pode usar o objeto Conversation para recuperar dados armazenados entre conversas ou informações de estado, enviar respostas aos usuários ou feche o microfone.
  5. Processamento de middleware: a biblioteca de cliente permite criar seus um middleware próprio de serviços de conversação, que consiste em uma ou mais funções você define que a biblioteca de cliente é executada automaticamente antes de chamar o gerenciador de intents. O webhook de fulfillment pode usar o middleware para adicionar propriedades ou classes auxiliares ao objeto Conversation.
  6. Processamento do gerenciador de intents: a biblioteca de cliente permite definir gerenciadores de intents que o webhook de fulfillment entende. Para o Dialogflow, a biblioteca de cliente encaminha a solicitação para o gerenciador de intents correto pelo o mapeamento para a string exata do nome da intent definida no Console do Dialogflow No caso do SDK do Actions, ele é roteado com base na propriedade intent enviada. no Actions on Google.
  7. Enviar respostas aos usuários: para criar respostas, o webhook de fulfillment chama a função Conversation#ask(). A função ask() pode ser chamado várias vezes para construir a resposta de modo incremental. O serializa a resposta em uma solicitação HTTP com uma Payload JSON, que é enviado para o Actions on Google. A função close() tem um comportamento semelhante a ask(), mas encerra a conversa.

Configurar o ambiente de desenvolvimento local

Antes de implementar o webhook de fulfillment, instale primeiro o biblioteca de cliente.

Instale a biblioteca de cliente

A maneira mais fácil de instalar a biblioteca de cliente em seu ambiente de desenvolvimento local ambiente é usar um gerenciador de pacotes, como npm ou yarn.

Para instalar, execute um destes comandos no terminal:

  • Se estiver usando o npm: npm install actions-on-google
  • Se estiver usando fio: yarn add actions-on-google

Configurar as pastas do projeto

Dependendo de onde você planeja implantar o webhook de fulfillment (Cloud Functions do Google) para Firebase, AWS Lambda ou Express auto-hospedado), pode ser necessário criar um uma estrutura de pastas específica do projeto para salvar seus arquivos.

Por exemplo, se você estiver usando o Cloud Functions para Firebase, poderá configurar as pastas de projeto necessárias seguindo as etapas descritas em Configurar o Node.js e a CLI do Firebase e Inicializar o Firebase para Cloud Functions. No Cloud Functions para Firebase, você normalmente escreve o webhook de fulfillment no arquivo /functions/index.js.

Criar uma instância de app

O Actions on Google usa formatos de mensagens específicos para trocar solicitações e respostas com o webhook de fulfillment, dependendo se você está criando um ambiente Ação usando o Dialogflow ou o SDK do Actions ou criando uma ação de casa inteligente.

Para representar esses diferentes protocolos de solicitação e resposta, o fornece três funções de serviço:

O protocolo de webhook da conversa (em inglês) é usado por serviços de conversação (Dialogflow e Actions SDK), mas cada que agrupa as mensagens de maneira diferente.

Use um serviço para criar uma instância app. A instância app encapsula o estado global e a lógica de fulfillment do seu webhook e processa a comunicação entre o Actions on Google e o fulfillment usando o protocolo específico do serviço.

É possível configurar as propriedades da instância app e chamar os métodos dela para direcionar o comportamento do webhook de fulfillment. Você também pode conectar facilmente a instância app em um ambiente de computação sem servidor, como o Cloud Functions para Firebase, que aceita funções JavaScript como gerenciadores de solicitações HTTP.

Para criar uma instância app no webhook de fulfillment, siga estas etapas:

  1. Chame a função require() para importar o módulo "actions-on-google" e carregar o serviço que você quer. Por exemplo, o snippet a seguir mostra como você pode carregar o serviço dialogflow e alguns elementos usados para criar respostas; e a atribua a uma constante chamada dialogflow: 

    // Import the service function and various response classes
const {
  dialogflow,
  actionssdk,
  Image,
  Table,
  Carousel,
} = require('actions-on-google');

    Aqui, actions-on-google se refere a uma dependência especificada em uma arquivo package.json na sua na pasta do projeto. Você pode consultar este arquivo de exemplo package.json para ver um exemplo).

    Ao receber uma instância app, é possível, opcionalmente, especificar classes que representam respostas avançadas, intents auxiliares e outras funcionalidades do Actions on Google que você queira usar. Para conferir a lista completa de classes válidas que podem ser carregadas, consulte a documentação de referência dos módulos resposta de conversa e intent auxiliar.

  2. Crie uma instância app chamando o serviço que você carregou. Por exemplo: 

    const app = dialogflow();

  3. Para configurar a instância app na inicialização, forneça um objeto options como o primeiro argumento ao chamar o serviço. Consulte DialogflowOptions para mais detalhes. Por exemplo, o snippet a seguir mostra como registrar o payload JSON bruto do a solicitação ou resposta do usuário definindo a sinalização { debug: true }:

const app = dialogflow({
  debug: true
});

Definir manipuladores para eventos

Para processar eventos relacionados ao Actions on Google criados pela biblioteca de cliente durante a da interação do usuário com sua ação, você vai usar o biblioteca de cliente para compilar gerenciadores para processar solicitações de usuários e enviar de volta de resposta.

É possível criar funções que atuam como manipuladores para esses principais tipos de eventos que a biblioteca de cliente reconhece:

  • Eventos de intent:as intents são identificadores exclusivos enviados pelo Actions on Google. ao fulfillment sempre que um usuário solicitar uma funcionalidade específica. Se você estiver usando o Dialogflow, isso corresponde a uma correspondência de uma consulta do usuário com uma intent no seu agente do Dialogflow.
  • Eventos de erro: quando ocorre um erro de JavaScript ou de biblioteca de cliente, use a função catch da instância app para processar a exceção de erro. adequadamente. Implemente uma única função catch para processar todas erros importantes para seu fulfillment.
  • Eventos substitutos:um evento substituto ocorre quando o usuário envia uma consulta que o Actions on Google não consegue reconhecer. Você pode usar o app a função fallback da instância para registrar um gerenciador de fallback genérico que será acionado se nenhum gerenciador de intent corresponder ao cumprimento recebido solicitação. Implemente uma única função fallback para processar todas eventos substitutos. Se você estiver usando o Dialogflow, ele poderá acionar uma conversão de substituta quando nenhuma outra intent for correspondida. Crie um gerenciador de intent correspondente a essa intent substituta.

Sempre que o usuário envia uma solicitação para sua ação, a instância app cria um objeto Conversation que representa essa sessão de conversa. Esse objeto é acessado pelo nome da variável conv transmitido na função do gerenciador de intents como o primeiro argumento da função. Você normalmente usará o conv em seus manipuladores para enviar uma resposta ao usuário.

As consultas do usuário também podem incluir parâmetros que a Ação pode extrair e usar para refinar as respostas.

  • Se você estiver usando o SDK do Actions, defina os parâmetros no pacote de ações. Para conferir um exemplo de como extrair parâmetros de intents, consulte o exemplo de código da Eliza.
  • Se você estiver usando o Dialogflow, acesse os valores de parâmetros por meio da variável params. Para conferir exemplos de como processar intents com parâmetros no Dialogflow, consulte Acesso a parâmetros e contextos.

Definir gerenciadores para intents

Para definir o gerenciador de uma intent, chame a função intent() do app. instância. Por exemplo, se você estiver usando o Dialogflow, essa é a função DialogflowApp#intent(). Nos argumentos, especifique o nome da intent e forneça uma função de gerenciador.

Se você estiver usando o Dialogflow, não precisará definir gerenciadores para cada intent no com seu agente. Em vez disso, você pode aproveitar a resposta integrada do Dialogflow para processar intents automaticamente sem implementar seu próprio gerenciador . Por exemplo, o intent de boas-vindas padrão pode ser delegada ao Dialogflow dessa forma.

O exemplo a seguir mostra gerenciadores de intent para a "saudação" e "tchau" intents. As funções de gerenciador anônimas recebem um argumento conv e enviam de volta uma resposta de string simples ao usuário pela função conv.ask():

app.intent('Default Welcome Intent', (conv) => {
  conv.ask('How are you?');
});

app.intent('bye', (conv) => {
  conv.close('See you later!');
});

A função close() é semelhante a ask(), mas é fechada. o microfone e a conversa termina.

Para saber mais sobre como criar gerenciadores de intents, consulte Criar o gerenciador de intents.

Definir gerenciadores para eventos de erro

Para definir os gerenciadores de erros, chame a função catch() da sua instância app. Por exemplo, se você estiver usando o Dialogflow, esta é a DialogflowApp#catch() function.)

O exemplo a seguir mostra um gerenciador de erros de captura simples que envia o erro para saída do console e retorna uma resposta de string simples para enviar uma solicitação ao usuário por a função conv.ask():

app.catch((conv, error) => {
  console.error(error);
  conv.ask('I encountered a glitch. Can you say that again?');
});

Definir manipuladores para eventos substitutos

Para definir um gerenciador de fallback genérico quando nenhuma intent for correspondida para o solicitação recebida para fulfillment, chame a função fallback() de sua instância do app. Por exemplo, se você estiver usando o Dialogflow, esta é a DialogflowApp#fallback() function.)

O exemplo a seguir mostra um gerenciador de fallback simples que envia de volta um resposta de string para pedir ao usuário pela função conv.ask():

app.fallback((conv) => {
  conv.ask(`I couldn't understand. Can you say that again?`);
});

Criar o gerenciador de intents

Esta seção aborda alguns casos de uso comuns ao implementar processadores de intents com a biblioteca de cliente. Para ver como a biblioteca de cliente faz a correspondência a intent, consulte a seção "Processamento do gerenciador de intents" na seção Entenda como funciona.

Parâmetros e contextos de acesso

Se você estiver usando o Dialogflow, poderá definir parâmetros e contextos no agente do Dialogflow para manter informações de estado e controlar o fluxo da conversa.

Os parâmetros são úteis para capturar palavras, frases ou valores importantes nas consultas do usuário. O Dialogflow extrai os parâmetros correspondentes das consultas do usuário no momento da execução, e você pode processar esses valores de parâmetro no webhook de fulfillment para determinar como responder aos usuários.

Sempre que o usuário envia uma solicitação para sua ação, a instância DialogflowApp cria um parameters que representa os valores de parâmetro extraídos do Dialogflow solicitação. Esse objeto é acessado pelo nome da variável params.

O snippet a seguir mostra como acessar a propriedade name pelo Objeto params quando o usuário envia uma solicitação:

app.intent('Default Welcome Intent', (conv, params) => {
  conv.ask(`How are you, ${params.name}?`);
});

Veja um snippet alternativo que faz a mesma coisa. As chaves ({}) realizar a desestruturação do JavaScript. para pegar a propriedade name do objeto parameters e usá-la como um variável:

app.intent('Default Welcome Intent', (conv, {name}) => {
  conv.ask(`How are you, ${name}?`);
});

No snippet a seguir, o nome do parâmetro é full-name, mas é desestruturada e atribuída a uma variável local chamada name:

app.intent('Default Welcome Intent', (conv, {'full-name': name}) => {
  conv.ask(`How are you, ${name}?`);
});

Os contextos são um recurso avançado do o Dialogflow. É possível usar contextos para gerenciar o estado, o fluxo e a ramificação da conversa. A biblioteca cliente fornece acesso a um contexto por meio da DialogflowConversation#contexts objeto. O snippet a seguir mostra como definir um contexto de maneira programática no webhook de fulfillment e como recuperar o 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('...');
});

Acessar resultados de intents auxiliares

Por conveniência, a biblioteca de cliente fornece classes de intent auxiliar que envolvem tipos comuns de dados do usuário solicitados com frequência por ações. Elas incluem classes que representam os resultados das várias intenções auxiliares do Actions on Google. Use intents auxiliares quando quiser que o Google Assistente gerencie partes da conversa em que o usuário precisa fornecer entrada para continuar a conversa.

Exemplo: resultados do auxiliar de confirmação

A intent auxiliar de confirmação permite você pede uma confirmação sim/não do usuário e obtém a resposta resultante. O snippet a seguir mostra como o webhook pode personalizar a resposta com base nos resultados retornados pela intent auxiliar de confirmação. Para um exemplo mais completo, consulte o Confirmation documentação de referência da classe.

// 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.`);
  }
});

O snippet a seguir mostra como o webhook de fulfillment pode personalizar a resposta com base na entrada do usuário carrossel. O componente carrossel permite que sua ação apresenta uma seleção de opções para os usuários escolherem. Para uma exemplo completo, consulte a Carousel documentação de referência da classe.

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!`);
  }
});

Configurar objetos de resposta de conversa

A biblioteca de cliente fornece classes de resposta a conversas que representem respostas avançadas ou elementos multimídia que a Ação pode enviar. Normalmente, você envia essas respostas ou elementos quando os usuários não precisam fornecer entradas para continuar a conversa.

Exemplo: imagem

O snippet a seguir mostra como o webhook de fulfillment pode enviar uma Image em uma resposta que será automaticamente anexada a uma resposta BasicCard por biblioteca:

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',
  }));
});

Fazer chamadas de função assíncronas

A biblioteca de cliente Node.js do Actions on Google foi desenvolvida para e programação. O gerenciador de intents pode retornar uma promessa que é resolvida quando o webhook de fulfillment termina de gerar uma resposta.

O snippet a seguir mostra como você pode fazer uma chamada de função assíncrona para retornar um objeto de promessa e responder com uma mensagem se o webhook de fulfillment recebe a "saudação" intenção. Nesse snippet, a promessa garante que seu O webhook de fulfillment retorna uma resposta de conversa somente após a promessa para o uma chamada de API externa foi resolvida.

Neste exemplo, estamos usando uma API falsa para coletar os dados meteorológicos.

/**
 * 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}.`);
  });
});

O snippet de código simplificado a seguir tem o mesmo efeito, mas usa o recurso await async introduzido no ECMA 2017 (Node.js versão 8). Para usar esse código com o Cloud Functions para Firebase, verifique se você está usando a versão correta do firebase-tools e se tem a configuração correta.

app.intent('Default Welcome Intent', async (conv) => {
  const weather = await forecast();
  conv.ask('How are you?');
  conv.ask(`Today's weather is ${weather}.`);
});

Armazenar dados de conversa

A biblioteca de cliente permite que o webhook de fulfillment salvar dados em conversas para para usos futuros. Os principais objetos que podem ser usados para armazenamento de dados incluem:

O snippet a seguir mostra como o webhook de fulfillment pode armazenar dados em um propriedade arbitrária definida por você (someProperty) e anexá-la a Conversation#user.storage objeto. Para um exemplo mais completo, consulte a Conversation#user.storage documentação de referência da classe.

app.intent('Default Welcome Intent', (conv) => {
  conv.user.storage.someProperty = 'someValue';
  conv.ask('...');
});

Você pode usar o Conversation#user para obter informações sobre o usuário, incluindo um identificador de string e informações pessoais. Alguns campos, como conv.user.name.display e conv.user.email, exigem a solicitação de conv.ask(new Permission) para NAME e conv.ask(new SignIn) para o login do 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!`);
  }
});

Escalonamento com middleware

É possível estender a biblioteca de cliente usando um middleware.

A camada de middleware consiste em uma ou mais funções definidas, que a biblioteca de cliente executa automaticamente antes de chamar o gerenciador de intents. O uso de uma camada de middleware permite modificar o Conversation e adiciona funcionalidades extras.

Os serviços do Dialogflow e do SDK do Actions expõem uma função app.middleware() que permite adicionar propriedades ou classes auxiliares ao Conversation instância.

O snippet a seguir mostra um exemplo de como você pode usar o 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 o app

Para expor o webhook de fulfillment para um framework da Web ou plataforma de computação sem servidor, exporte o objeto app como um webhook acessível publicamente. O oferece suporte à implantação em diversos ambientes da caixa.

Os snippets a seguir mostram como exportar app em diferentes ambientes de execução:

Exemplo: Cloud Functions para Firebase

const functions = require('firebase-functions');
// ... app code here
exports.fulfillment = functions.https.onRequest(app);

Exemplo: editor inline do Dialogflow

const functions = require('firebase-functions');

// ... app code here

// Exported function name must be 'dialogflowFirebaseFulfillment'
exports.dialogflowFirebaseFulfillment = functions.https.onRequest(app);

Exemplo: servidor Express auto-hospedado (simples)

const express = require('express');
const bodyParser = require('body-parser');  

// ... app code here

express().use(bodyParser.json(), app).listen(3000);

Exemplo: servidor Express auto-hospedado (vários trajetos)

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);

Exemplo: gateway de API AWS Lambda

// ... app code here

exports.fulfillment = app;