Tạo phương thức thực hiện bằng thư viện ứng dụng Node.js của Actions on Google (Dialogflow)

Bạn nên dùng Thư viện ứng dụng Actions on Google Node.js để truy cập và tương tác với nền tảng Actions on Google nếu đang tạo một webhook thực hiện đơn hàng trong JavaScript.

Giới thiệu

Thư viện ứng dụng Node.js là một thư viện phương thức thực hiện cho Actions on Google, cung cấp các tính năng sau:

  • Hỗ trợ tất cả các tính năng của Actions on Google, bao gồm phản hồi dạng văn bản và nội dung đa phương tiện, đăng nhập vào tài khoản, lưu trữ dữ liệu, giao dịch, v.v.
  • Cung cấp một lớp trừu tượng tương thích trong JavaScript bao bọc API webhook HTTP/JSON của cuộc trò chuyện.
  • Xử lý thông tin giao tiếp cấp thấp giữa phương thức thực hiện của bạn và nền tảng Actions on Google.
  • Có thể cài đặt bằng các công cụ quản lý gói quen thuộc, chẳng hạn như npm hoặc yarn.
  • Cho phép bạn dễ dàng triển khai webhook thực hiện đơn hàng trên các nền tảng điện toán không máy chủ, chẳng hạn như Cloud Functions cho Firebase hoặc AWS Lambda. Bạn cũng có thể lưu trữ webhook thực hiện đơn hàng trên nhà cung cấp dịch vụ đám mây hoặc trên môi trường tự lưu trữ và tự quản lý.
  • Tương thích với Node.js phiên bản 6.0.0 trở lên.

Bạn có thể sử dụng thư viện ứng dụng cùng với tính năng tích hợpDialogflow cho Actions on Google hoặc với Actions SDK.

Để xem mã mẫu đầy đủ để sử dụng thư viện ứng dụng, bạn có thể truy cập trang mẫu.

Xem tài liệu tham khảo API

Tài liệu tham khảo API được lưu trữ trên trang GitHub Hành động trên thư viện ứng dụng Node.js của Google.

Bạn cũng có thể tạo bản sao cục bộ của tệp đối chiếu bằng cách chạy lệnh sau từ thư mục mà bạn đã tải mã thư viện ứng dụng xuống:

yarn docs

Tài liệu đã tạo sẽ nằm trong thư mục docs của thư mục mà bạn đã tải mã thư viện ứng dụng xuống.

Tìm hiểu cách hoạt động

Trước khi sử dụng thư viện ứng dụng, bạn nên hiểu cách webhook của phương thức thực hiện đơn hàng sử dụng thư viện ứng dụng để xử lý yêu cầu của người dùng mà Actions on Google gửi đến phương thức thực hiện của bạn.

Khi tạo một webhook về phương thức thực hiện trong JavaScript, bạn có thể triển khai và lưu trữ mã trong môi trường điện toán không máy chủ, chẳng hạn như Chức năng đám mây cho Firebase của Google hoặc AWS Lambda. Bạn cũng có thể tự lưu trữ mã mà không cần phải làm gì thêm bằng cách sử dụng khung web Express.

Trong môi trường thời gian chạy, webhook thực hiện nhiệm vụ có thể gọi các hàm trong thư viện ứng dụng để xử lý yêu cầu của người dùng và gửi lại phản hồi cho Actions on Google để kết xuất thành dữ liệu đầu ra của người dùng.

Dưới đây là thông tin tóm tắt ngắn gọn về các tác vụ chính mà webhook của phương thức thực hiện xử lý với sự hỗ trợ của thư viện ứng dụng:

Hình 1. Cấu trúc cấp cao của thư viện ứng dụng Node.js
  1. Nhận yêu cầu của người dùng: Khi người dùng gửi truy vấn đến Trợ lý Google, nền tảng Actions on Google sẽ gửi một yêu cầu HTTP đến webhook thực hiện yêu cầu của bạn; yêu cầu này bao gồm một tải trọng JSON chứa ý định và các dữ liệu khác như văn bản thô trong hoạt động đầu vào của người dùng, cũng như các chức năng trên nền tảng của thiết bị. Để biết thêm ví dụ về nội dung tải trọng JSON, hãy xem hướng dẫn về định dạng webhook đối vớiDialogflow và định dạng webhook cuộc trò chuyện.
  2. Phát hiện định dạng lệnh gọi khung: Đối với các khung được hỗ trợ, thư viện ứng dụng sẽ tự động phát hiện định dạng lệnh gọi của khung (ví dụ: nếu yêu cầu đến từ khung web Express hoặc từ AWS Lambda) và biết cách xử lý liền mạch hoạt động giao tiếp với nền tảng Actions on Google.
  3. Xử lý trình xử lý dịch vụ: Thư viện ứng dụng đại diện cho API webhook HTTP/JSON của cuộc trò chuyện cho Dialogflow và SDK Hành động dưới dạng một chức năng dịch vụ. Webhook thực hiện đơn hàng của bạn sử dụng dịch vụ thích hợp để tạo một bản sao app chung. Thực thể app đóng vai trò là trình xử lý các yêu cầu HTTP và giúp hiểu rõ giao thức cụ thể của dịch vụ.
  4. Xử lý cuộc trò chuyện: Thư viện ứng dụng biểu thị thông tin về mỗi cuộc trò chuyện dưới dạng đối tượng Conversation được đính kèm vào thực thể app. Webhook cho phương thức thực hiện của bạn có thể sử dụng đối tượng Conversation để truy xuất dữ liệu được lưu trữ giữa nhiều cuộc trò chuyện hoặc thông tin trạng thái, gửi câu trả lời cho người dùng hoặc đóng micrô.
  5. Xử lý phần mềm trung gian: Thư viện ứng dụng cho phép bạn tạo phần mềm trung gian dịch vụ trò chuyện của riêng mình, bao gồm một hoặc nhiều hàm mà bạn xác định rằng thư viện ứng dụng sẽ tự động chạy trước khi gọi trình xử lý ý định. Webhook cho phương thức thực hiện của bạn có thể sử dụng phần mềm trung gian để thêm các thuộc tính hoặc lớp trợ giúp vào đối tượng Conversation.
  6. Xử lý trình xử lý ý định: Thư viện ứng dụng cho phép bạn xác định các trình xử lý cho ý định mà webhook thực hiện của bạn hiểu được. Đối với Dialogflow, thư viện ứng dụng chuyển yêu cầu đến trình xử lý ý định chính xác bằng cách ánh xạ đến chuỗi chính xác của tên ý định được xác định trong bảng điều khiển Dialogflow. Đối với SDK Actions, hành động này được định tuyến dựa trên thuộc tính intent được gửi từ Actions on Google.
  7. Gửi câu trả lời cho người dùng: Để tạo câu trả lời, phương thức thực hiện webhook sẽ gọi hàm Conversation#ask(). Hàm ask() có thể được gọi nhiều lần để tạo dần phản hồi. Thư viện ứng dụng chuyển đổi tuần tự phản hồi thành một yêu cầu HTTP với tải trọng JSON và gửi phản hồi đó đến Actions on Google. Hàm close() có hành vi tương tự như ask() nhưng sẽ đóng cuộc trò chuyện.

Thiết lập môi trường phát triển cục bộ

Trước khi triển khai webhook của phương thức thực hiện, hãy nhớ cài đặt thư viện ứng dụng.

Cài đặt thư viện ứng dụng

Cách dễ nhất để cài đặt thư viện ứng dụng vào môi trường phát triển cục bộ là sử dụng một trình quản lý gói, chẳng hạn như npm hoặc yarn.

Để cài đặt, hãy chạy một trong các lệnh sau trên thiết bị đầu cuối:

  • Nếu sử dụng npm: npm install actions-on-google
  • Nếu sử dụng sợi: yarn add actions-on-google

Thiết lập thư mục dự án

Tuỳ thuộc vào vị trí bạn dự định triển khai webhook thực hiện webhook (Chức năng đám mây của Google cho Firebase, AWS Lambda hoặc Express tự lưu trữ), có thể bạn sẽ cần tạo một cấu trúc thư mục dự án cụ thể để lưu tệp.

Ví dụ: nếu đang sử dụng Cloud Functions cho Firebase, bạn có thể thiết lập các thư mục dự án bắt buộc bằng cách thực hiện các bước như mô tả trong bài viết Thiết lập Node.js và Firebase CLI và Khởi chạy Firebase cho Cloud Functions. Đối với Cloud Functions cho Firebase, bạn thường viết webhook của phương thức thực hiện trong tệp /functions/index.js.

Tạo một thực thể ứng dụng

Actions on Google sử dụng các định dạng thông báo cụ thể để trao đổi yêu cầu và phản hồi bằng webhook thực hiện nhiệm vụ, tuỳ thuộc vào việc bạn đang xây dựng một Hành động trò chuyện bằng Dialogflow, Actions SDK hay xây dựng Hành động trong nhà thông minh.

Để thể hiện các giao thức yêu cầu và phản hồi khác nhau này, thư viện ứng dụng cung cấp 3 hàm dịch vụ:

Giao thức webhook cho cuộc trò chuyện được cả hai dịch vụ trò chuyện (Dialogflow và Actions SDK) sử dụng, nhưng mỗi dịch vụ lại gói các thông báo theo cách khác nhau.

Bạn sẽ dùng một dịch vụ để tạo một thực thể app. Thực thể app đóng gói trạng thái chung và logic phương thức thực hiện cho webhook của bạn, đồng thời xử lý hoạt động giao tiếp giữa Actions on Google và phương thức thực hiện của bạn bằng giao thức dành riêng cho dịch vụ.

Bạn có thể định cấu hình các thuộc tính của thực thể app và gọi các phương thức của thực thể đó để định hướng hành vi của webhook thực hiện nhiệm vụ. Bạn cũng có thể dễ dàng kết nối thực thể app vào môi trường điện toán không máy chủ, chẳng hạn như Cloud Functions cho Firebase. Các hàm này chấp nhận các hàm JavaScript làm trình xử lý cho các yêu cầu HTTP.

Để tạo một thực thể app trong webhook thực hiện nhiệm vụ, hãy làm theo các bước sau:

  1. Gọi hàm require() để nhập mô-đun "actions-on-google" và tải dịch vụ mà bạn muốn. Ví dụ: đoạn mã sau đây cho biết cách bạn có thể tải dịch vụ dialogflow và một số phần tử dùng để tạo phản hồi, đồng thời chỉ định đối tượng đó cho một hằng số có tên là dialogflow:

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

    Ở đây, actions-on-google đề cập đến một phần phụ thuộc được chỉ định trong tệp package.json trong thư mục dự án (bạn có thể tham khảo tệp package.json ví dụ này để biết ví dụ).

    Khi có được thực thể app, bạn có thể tuỳ ý chỉ định các lớp đại diện cho phản hồi đa dạng thức, ý định của trình trợ giúp và các chức năng khác của Actions on Google mà bạn muốn sử dụng. Để biết danh sách đầy đủ các lớp hợp lệ mà bạn có thể tải, hãy xem tài liệu tham khảo cho các mô-đun phản hồi cuộc trò chuyện và ý định của trình trợ giúp.

  2. Tạo một thực thể app bằng cách gọi dịch vụ mà bạn đã tải. Ví dụ:

    const app = dialogflow();

  3. Để định cấu hình thực thể app khi khởi chạy, bạn có thể cung cấp một đối tượng options làm đối số đầu tiên khi gọi dịch vụ. (Hãy xem DialogflowOptions để biết thêm thông tin chi tiết.) Ví dụ: đoạn mã sau đây cho biết cách ghi nhật ký tải trọng JSON thô qua yêu cầu hoặc phản hồi của người dùng bằng cách đặt cờ { debug: true }:

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

Thiết lập trình xử lý cho sự kiện

Để xử lý các sự kiện liên quan đến Hành động trên Google do thư viện ứng dụng tạo ra trong vòng đời của hoạt động tương tác của người dùng với Hành động của bạn, bạn sẽ sử dụng thư viện ứng dụng để tạo trình xử lý nhằm xử lý yêu cầu của người dùng và gửi lại các phản hồi.

Bạn có thể tạo các hàm đóng vai trò là trình xử lý cho các loại sự kiện chính sau đây mà thư viện ứng dụng nhận dạng được:

  • Sự kiện ý định: Ý định là giá trị nhận dạng riêng biệt mà Actions on Google gửi đến phương thức thực hiện của bạn bất cứ khi nào người dùng yêu cầu một chức năng cụ thể. Nếu bạn đang sử dụng Dialogflow, thì việc này tương ứng với việc Dialogflow khớp một truy vấn của người dùng với một ý định trong nhân viên hỗ trợ Dialogflow của bạn.
  • Sự kiện lỗi: Khi xảy ra lỗi JavaScript hoặc thư viện ứng dụng, bạn có thể sử dụng hàm catch của thực thể app để xử lý ngoại lệ lỗi một cách phù hợp. Bạn nên triển khai một hàm catch duy nhất để xử lý tất cả các lỗi mà phương thức thực hiện của bạn quan tâm.
  • Sự kiện dự phòng: Sự kiện dự phòng xảy ra khi người dùng gửi một truy vấn mà Actions on Google không thể nhận ra. Bạn có thể sử dụng hàm fallback của thực thể app để đăng ký một trình xử lý dự phòng chung. Trình xử lý này sẽ được kích hoạt nếu không có trình xử lý ý định nào được so khớp với yêu cầu thực hiện sắp tới. Bạn nên triển khai một hàm fallback duy nhất để xử lý tất cả các sự kiện dự phòng. Nếu bạn đang sử dụng Dialogflow, Dialogflow có thể kích hoạt một ý định dự phòng cụ thể khi không có ý định nào khác khớp. Bạn nên tạo một trình xử lý ý định tương ứng cho ý định dự phòng đó.

Bất cứ khi nào người dùng gửi yêu cầu đến Hành động của bạn, thực thể app sẽ tạo một đối tượng Conversation đại diện cho phiên trò chuyện đó. Đối tượng này được truy cập thông qua tên biến conv được truyền vào hàm xử lý ý định làm đối số hàm đầu tiên. Thông thường, bạn sẽ dùng đối tượng conv trong trình xử lý để gửi phản hồi cho người dùng.

Truy vấn của người dùng cũng có thể bao gồm các tham số mà Hành động của bạn có thể trích xuất và sử dụng để tinh chỉnh phản hồi.

  • Nếu đang sử dụng SDK Hành động, bạn cần xác định các thông số trong Gói hành động. Để xem ví dụ về cách trích xuất tham số từ ý định, vui lòng xem mã mẫu của Eliza.
  • Nếu đang sử dụng Dialogflow, bạn có thể truy cập vào các giá trị thông số thông qua biến params. Để xem ví dụ về cách xử lý ý định bằng thông số trong Dialogflow, vui lòng xem phần Thông số truy cập và ngữ cảnh.

Thiết lập trình xử lý cho ý định

Để đặt trình xử lý cho một ý định, hãy gọi hàm intent() của thực thể app. Ví dụ: nếu bạn đang sử dụng Dialogflow, thì đây là hàm DialogflowApp#intent(). Trong các đối số, hãy chỉ định tên ý định và cung cấp một hàm xử lý.

Nếu đang sử dụng Dialogflow, bạn không cần phải đặt trình xử lý cho mọi ý định trong nhân viên hỗ trợ của mình. Thay vào đó, bạn có thể tận dụng trình xử lý phản hồi tích hợp sẵn của Dialogflow để tự động xử lý các ý định mà không cần triển khai các hàm của trình xử lý của riêng bạn. Ví dụ: bạn có thể uỷ quyền ý định chào mừng mặc định cho Dialogflow theo cách này.

Ví dụ sau đây cho thấy các trình xử lý ý định cho ý định "chào" và "tạm biệt". Các hàm xử lý ẩn danh của đối số này sẽ nhận một đối số conv và gửi lại một phản hồi chuỗi đơn giản cho người dùng thông qua hàm conv.ask():

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

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

Lưu ý rằng hàm close() tương tự như ask() ngoại trừ việc hàm này đóng micrô và cuộc trò chuyện kết thúc.

Để tìm hiểu thêm về cách xây dựng trình xử lý cho ý định, hãy xem bài viết Tạo trình xử lý ý định.

Thiết lập trình xử lý cho các sự kiện lỗi

Để thiết lập trình xử lý cho các lỗi, hãy gọi hàm catch() của thực thể app. (Ví dụ: nếu bạn đang sử dụng Dialogflow, thì đây là hàm DialogflowApp#catch().)

Ví dụ sau đây cho thấy một trình xử lý lỗi phát hiện đơn giản gửi lỗi đến đầu ra của bảng điều khiển và gửi lại một phản hồi chuỗi đơn giản để nhắc người dùng thông qua hàm conv.ask():

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

Thiết lập trình xử lý cho các sự kiện dự phòng

Để đặt trình xử lý dự phòng chung khi không có ý định nào phù hợp với yêu cầu thực hiện sắp tới, hãy gọi hàm fallback() của thực thể app. (Ví dụ: nếu bạn đang sử dụng Dialogflow, thì đây là hàm DialogflowApp#fallback().)

Ví dụ sau đây cho thấy một trình xử lý dự phòng đơn giản gửi lại một phản hồi chuỗi đơn giản để nhắc người dùng thông qua hàm conv.ask():

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

Tạo trình xử lý ý định

Phần này đề cập đến một số trường hợp sử dụng phổ biến khi bạn triển khai trình xử lý ý định bằng thư viện ứng dụng. Để xem cách thư viện ứng dụng khớp với ý định, hãy tham khảo phần "Xử lý ý định" trong phần Tìm hiểu cách hoạt động của trình xử lý ý định.

Truy cập thông số và ngữ cảnh

Nếu đang sử dụng Dialogflow, bạn có thể xác định thông số và ngữ cảnh trong nhân viên hỗ trợ Dialogflow để duy trì thông tin trạng thái và kiểm soát quy trình trò chuyện.

Tham số rất hữu ích khi thu thập các từ, cụm từ hoặc giá trị quan trọng trong truy vấn của người dùng. Dialogflow trích xuất các tham số tương ứng từ truy vấn của người dùng trong thời gian chạy và bạn có thể xử lý các giá trị tham số này trong webhook thực hiện nhiệm vụ để xác định cách phản hồi người dùng.

Bất cứ khi nào người dùng gửi yêu cầu đến Hành động của bạn, thực thể DialogflowApp sẽ tạo một đối tượng parameters đại diện cho các giá trị thông số mà Dialogflow đã trích xuất từ yêu cầu đó. Đối tượng này được truy cập thông qua tên biến params.

Đoạn mã sau đây cho biết cách truy cập vào thuộc tính name từ đối tượng params khi người dùng gửi yêu cầu:

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

Dưới đây là một đoạn mã thay thế có chức năng tương tự. Dấu ngoặc nhọn ({}) thực hiện quá trình giải cấu trúc JavaScript để lấy thuộc tính name từ đối tượng parameters và sử dụng thuộc tính đó làm biến cục bộ:

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

Trong đoạn mã sau, tên thông số là full-name nhưng được huỷ cấu trúc và gán cho một biến cục bộ có tên là name:

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

Ngữ cảnh là một tính năng nâng cao của Dialogflow. Bạn có thể sử dụng ngữ cảnh để quản lý trạng thái, luồng và nhánh của cuộc trò chuyện. Thư viện ứng dụng cung cấp quyền truy cập vào một ngữ cảnh thông qua đối tượng DialogflowConversation#contexts. Đoạn mã sau đây cho biết cách bạn có thể thiết lập ngữ cảnh theo phương thức lập trình trong webhook thực hiện nhiệm vụ và cách truy xuất đối tượng ngữ cảnh:

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

Truy cập vào kết quả về ý định của trình trợ giúp

Để thuận tiện, thư viện ứng dụng cung cấp các lớp ý định trợ giúp để gói các loại dữ liệu người dùng phổ biến mà Hành động thường yêu cầu. Trong đó bao gồm các lớp biểu thị kết quả của nhiều ý định trợ giúp trong Actions on Google. Bạn sẽ sử dụng ý định của trình trợ giúp khi muốn Trợ lý Google xử lý những phần của cuộc trò chuyện mà trong đó người dùng phải cung cấp thông tin đầu vào để tiếp tục cuộc trò chuyện.

Ví dụ: Kết quả của trình trợ giúp xác nhận

Ý định của trình trợ giúp xác nhận cho phép bạn yêu cầu người dùng xác nhận có/không và nhận câu trả lời. Đoạn mã sau đây cho biết cách webhook của bạn có thể tuỳ chỉnh phản hồi dựa trên các kết quả mà ý định của trình trợ giúp xác nhận trả về. Để biết ví dụ hoàn chỉnh hơn, hãy xem tài liệu tham khảo về lớp 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.`);
  }
});

Đoạn mã sau đây cho thấy cách phương thức thực hiện webhook có thể tuỳ chỉnh phản hồi dựa trên thông tin đầu vào của người dùng cho một băng chuyền. Thành phần băng chuyền cho phép Hành động của bạn hiển thị một số lựa chọn để người dùng lựa chọn. Để biết ví dụ hoàn chỉnh hơn, hãy xem tài liệu tham khảo về lớp 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!`);
  }
});

Định cấu hình đối tượng phản hồi cuộc trò chuyện

Thư viện ứng dụng cung cấp các lớp phản hồi cuộc trò chuyện đại diện cho câu trả lời đa dạng thức hoặc các phần tử đa phương tiện mà Hành động của bạn có thể gửi. Bạn thường gửi các thành phần hoặc phản hồi này khi người dùng không cần cung cấp bất kỳ thông tin đầu vào nào để tiếp tục cuộc trò chuyện.

Ví dụ: Hình ảnh

Đoạn mã sau đây cho thấy cách phương thức thực hiện webhook có thể gửi một Image trong một phản hồi mà thư viện sẽ tự động đính kèm vào phản hồi 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',
  }));
});

Thực hiện lệnh gọi hàm không đồng bộ

Thư viện ứng dụng Node.js của Actions on Google được thiết kế để lập trình không đồng bộ. Trình xử lý ý định có thể trả về một lời hứa và khả năng phân giải khi webhook của phương thức thực hiện được tạo xong một phản hồi.

Đoạn mã sau đây cho biết cách bạn có thể thực hiện một lệnh gọi hàm không đồng bộ để trả về một đối tượng lời hứa, sau đó phản hồi bằng tin nhắn nếu webhook thực hiện đơn hàng của bạn nhận được ý định "chào". Trong đoạn mã này, lời hứa hẹn đảm bảo rằng webhook của phương thức thực hiện chỉ trả về phản hồi trò chuyện sau khi lời hứa cho lệnh gọi API bên ngoài đã được giải quyết.

Trong ví dụ này, chúng ta sử dụng một API giả để lấy dữ liệu thời tiết.

/**
 * 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ạn mã được sắp xếp hợp lý sau đây có tác dụng tương tự, nhưng sử dụng tính năng async await được giới thiệu trong ECMA 2017 (Node.js phiên bản 8). Để sử dụng mã này với Cloud Functions cho Firebase, hãy đảm bảo bạn đang sử dụng phiên bản firebase-tools chính xác và có cấu hình chính xác.

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

Lưu trữ dữ liệu trò chuyện

Thư viện ứng dụng cho phép webhook của phương thức thực hiện đơn hàng lưu dữ liệu trong các cuộc trò chuyện để sử dụng sau này. Sau đây là các đối tượng chính mà bạn có thể sử dụng để lưu trữ dữ liệu:

Đoạn mã sau đây cho thấy cách phương thức thực hiện webhook có thể lưu trữ dữ liệu trong một thuộc tính tuỳ ý mà bạn xác định (someProperty) và đính kèm dữ liệu đó vào đối tượng Conversation#user.storage. Để biết ví dụ hoàn chỉnh hơn, hãy xem tài liệu tham khảo về lớp Conversation#user.storage.

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

Bạn có thể sử dụng đối tượng Conversation#user để lấy thông tin về người dùng, bao gồm cả giá trị nhận dạng chuỗi và thông tin cá nhân. Một số trường như conv.user.name.display và conv.user.email lần lượt yêu cầu yêu cầu conv.ask(new Permission) cho NAME và conv.ask(new SignIn) cho tính năng Đăng nhập bằng Google.

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

Mở rộng quy mô bằng phần mềm trung gian

Bạn có thể mở rộng thư viện ứng dụng thông qua phần mềm trung gian.

Lớp phần mềm trung gian bao gồm một hoặc nhiều hàm mà bạn xác định mà thư viện ứng dụng sẽ tự động chạy trước khi gọi trình xử lý ý định. Việc sử dụng lớp phần mềm trung gian cho phép bạn sửa đổi thực thể Conversation và thêm chức năng bổ sung.

Dịch vụ Dialogflow và SDK Hành động hiển thị hàm app.middleware() cho phép bạn thêm các thuộc tính hoặc lớp trợ giúp vào thực thể Conversation.

Đoạn mã sau đây cho thấy một ví dụ về cách bạn có thể sử dụng phần mềm trung gian:

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

Xuất ứng dụng

Để hiển thị webhook của phương thức thực hiện trong một khung web hoặc nền tảng điện toán không máy chủ, bạn phải xuất đối tượng app dưới dạng một webhook có thể truy cập công khai. Thư viện ứng dụng hỗ trợ triển khai cho một số môi trường ngay từ đầu.

Các đoạn mã sau đây cho biết cách bạn có thể xuất app trong nhiều thời gian chạy:

Ví dụ: Cloud Functions cho Firebase

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

Ví dụ: Trình chỉnh sửa nội tuyến Dialogflow

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

// ... app code here

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

Ví dụ: Máy chủ Express tự lưu trữ (đơn giản)

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

// ... app code here

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

Ví dụ: Máy chủ Express tự lưu trữ (nhiều tuyến)

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

Ví dụ: Cổng API AWS Lambda

// ... app code here

exports.fulfillment = app;