Kể từ ngày 13 tháng 6 năm 2023, Hành động trò chuyện không còn được dùng nữa. Để biết thêm thông tin, hãy xem phần Hành động trò chuyện ngừng hoạt động.

Trang này được dịch bởi Cloud Translation API.

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 sử dụng Thư viện ứng dụng Node.js trong Actions on Google để truy cập và tương tác với nền tảng Actions on Google nếu bạn đang tạo một webhook cho phương thức thực hiện 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 cả phản hồi bằng văn bản và nội dung đa phương tiện đa dạng thức, đăng nhập 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 hội thoại.
Xử lý thông tin giao tiếp cấp thấp giữa phương thức thực hiệ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.
Giúp bạn dễ dàng triển khai webhook cho phương thức thực hiện trên các nền tảng điện toán không máy chủ chẳng hạn như Cloud Functions for Firebase hoặc AWS Lambda. Bạn cũng có thể lưu trữ webhook thực hiện đơn hàng trên một nhà cung cấp dịch vụ đám mây hoặc trên một 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ích hợpDialogflow cho Actions on Google hoặc thông qua 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 Thư viện ứng dụng Actions on Google Node.js Trang GitHub.

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

yarn docs

Các tài liệu đã tạo sẽ có 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 tìm hiểu cách Webhook thực hiện đơn hàng sử dụng thư viện ứng dụng để xử lý các yêu cầu của người dùng Actions on Google sẽ gửi đến phương thức thực hiện của bạn.

Khi tạo webhook thực hiện đơn hàng trong JavaScript, bạn có thể triển khai và lưu trữ mã của mình trên một môi trường điện toán không có máy chủ như Cloud Functions for Firebase của Google hoặc AWS Lambda. Bạn cũng có thể tự lưu trữ mã mà không cần 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 đơn hàng có thể gọi các hàm trong thư viện ứng dụng khách để xử lý yêu cầu của người dùng và gửi phản hồi lại cho Actions on Google để kết xuất thành dữ liệu đầu ra của người dùng.

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

**Hình 1.** Cấu trúc cấp cao của thư viện ứng dụng Node.js

Nhận yêu cầu của người dùng: Khi người dùng gửi yêu cầu đến Trợ lý Google, nền tảng Actions on Google sẽ gửi một yêu cầu HTTP đến webhook của phương thức thực hiện; yêu cầu bao gồm tải trọng JSON chứa ý định và dữ liệu khác, chẳng hạn như dữ liệu thô văn bản của hoạt động đầu vào của người dùng và khả năng hiển thị trên thiết bị của người dùng. Để biết thêm ví dụ về nội dung tải trọng JSON, hãy xem Định dạng webhook thoạiDialogflow và định dạng webhook của cuộc trò chuyện hướng dẫn.
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 tự động phát hiện định dạng lệnh gọi của khung (ví dụ: liệu yêu cầu đến từ khung web của Express hoặc từ AWS Lambda) và biết cách xử lý thông tin liên lạc liền mạch với nền tảng Actions on Google.
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 hàm 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 thực thể app toàn cục. Thực thể app đóng vai trò là trình xử lý cho các yêu cầu HTTP và hiểu giao thức cụ thể của dịch vụ.
Xử lý cuộc trò chuyện: Thư viện ứng dụng đại diện cho thông tin cho 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 thực hiện đơn hàng của bạn có thể sử dụng đối tượng Conversation để truy xuất dữ liệu hoặc thông tin trạng thái được lưu trữ trên nhiều cuộc trò chuyện, gửi phản hồi cho người dùng hoặc tắt micrô.
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 là 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 đơn hàng có thể sử dụng phần mềm trung gian của bạn để thêm các cơ sở lưu trú hoặc các lớp trợ giúp vào đối tượng Conversation.
Xử lý trình xử lý ý định: Thư viện ứng dụng cho phép bạn xác định cho các ý định mà webhook thực hiện của bạn hiểu được. Đối với Dialogflow, thư viện ứng dụng sẽ chuyển yêu cầu đến đúng trình xử lý ý định 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ểnDialogflow. Đối với SDK Hành động, SDK đó được định tuyến dựa trên thuộc tính intent đã gửi từ Actions on Google.
Gửi phản hồi cho người dùng: Để tạo phản hồi, webhook thực hiện đơn hàng của bạn gọi hàm Conversation#ask(). Bạn có thể gọi hàm ask() nhiều lần để tạo phản hồi tăng dần. Chiến lược phát hành đĩa đơn thư viện ứng dụng chuyển đổi tuần tự phản hồi thành yêu cầu HTTP bằng tải trọng JSON rồi gửi đến Actions on Google. Hàm close() có hành vi tương tự như ask() nhưng đó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 cho phương thức thực hiện, trước tiê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 quy trình phát triển cục bộ của bạn là sử dụng 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 cửa sổ dòng lệnh:

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

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

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

Ví dụ: nếu bạn đ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 được mô tả trong 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 cho 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 nhắn tin cụ thể để trao đổi các yêu cầu và phản hồi với webhook cho phương thức thực hiện, tuỳ thuộc vào việc bạn có đang tạo một cuộc trò chuyện Thao tác bằng Dialogflow hoặc Actions SDK hoặc tạo một Hành động thông minh trong nhà.

Để biểu thị 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 ba hàm dịch vụ:

Giao thức webhook của 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ụ nhưng dịch vụ sẽ gói thông báo theo cách khác.

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 và tên người dùng 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 cách sử dụ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ể đó để hướng đến hành vi của webhook thực hiện. Bạn cũng có thể dễ dàng cắm thực thể app vào một môi trường điện toán không máy chủ, chẳng hạn như Cloud Functions cho Firebase, môi trường 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 cho phương thức thực hiện, hãy làm theo các bước sau:

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, và gán hằng số đó cho một hằng số có tên 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 một package.json tệp trong thư mục dự án (bạn có thể tham khảo tệp package.json ví dụ này chẳng hạn).

Khi lấy một 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 Hành động khác trên Google mà bạn muốn sử dụng. Đối với 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 để phản hồi cuộc trò chuyện và ý định của người trợ giúp các mô-đun.

Lưu ý: Thư viện ứng dụng được cập nhật thường xuyên. Vui lòng xem ghi chú phát hành mới nhất để biết mọi thay đổi về API.
Tạo một thực thể app bằng cách gọi dịch vụ bạn đã tải. Ví dụ:
```
const app = dialogflow();
```
Để định cấu hình thực thể app khi khởi chạy, bạn có thể cung cấp một options làm đối số đầu tiên khi bạn gọi dịch vụ. (Xem DialogflowOptions để biết thêm 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ô từ 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 Actions on Google do thư viện ứng dụng tạo trong thời gian 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, thì bạn sẽ sử dụng thư viện ứng dụng để xây dựng trình xử lý nhằm xử lý yêu cầu của người dùng và gửi lại 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 này mà thư viện ứng dụng nhận ra:

Sự kiện ý định: Ý định là các giá trị nhận dạng riêng biệt mà Actions on Google gửi đối với phương thức thực hiện bất cứ khi nào người dùng yêu cầu chức năng cụ thể nào đó. Nếu bạn đang sử dụng Dialogflow, thì điều này tương ứng với việc Dialogflow so khớp một cụm từ tìm kiếm của người dùng với một ý định trong trợ lý Dialogflow.
Sự kiện lỗi: Khi xảy ra lỗi JavaScript hoặc thư viện ứng dụng, bạn có thể dùng hàm catch của thực thể app để xử lý ngoại lệ về 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ả những 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 sẽ gửi truy vấn mà Actions on Google không nhận dạng được. 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 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 nội dung cụ thể ý định dự phòng khi không có ý định nào khác đượ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 Conversation đối tượng đại diện cho phiên trò chuyện đó. Đối tượng này được truy cập qua tên biến conv được chuyển vào hàm xử lý ý định dưới dạng đối số của hàm đầu tiên. Bạn thường sẽ sử dụng conv trong trình xử lý của mình để 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 câu trả lời.

Nếu đang sử dụng SDK Hành động, bạn sẽ xác định các thông số trong gói Hành động. Để xem ví dụ về cách bạn có thể trích xuất tham số từ ý định, hãy xem Mã mẫu 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 các thông số trong Dialogflow, hãy xem bài viết Thông số và ngữ cảnh truy cập.

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 app thực thể. Ví dụ: nếu bạn đang sử dụng Dialogflow, đây là DialogflowApp#intent() . Trong các đối số, hãy chỉ định tên ý định và cung cấp một hàm của trình 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 phản hồi tích hợp sẵn của Dialogflow trình xử lý để tự động xử lý các ý định mà không cần triển khai trình xử lý của riêng bạn . Ví dụ: ý định chào mừng mặc định có thể là đã uỷ quyền cho Dialogflow theo cách này.

Ví dụ sau đây cho thấy trình xử lý ý định cho lệnh 'chào mừng' và "tạm biệt" ý định. Các hàm trình xử lý ẩn danh sẽ lấy một đối số conv và gửi lại một chuỗi phản hồ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 Xây dựng 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 lỗi, hãy gọi hàm catch() của app thực thể. (Ví dụ: nếu bạn đang sử dụng Dialogflow, đây là DialogflowApp#catch() function.)

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 trên bảng điều khiển và gửi lại một phản hồi dạng chuỗi đơn giản để nhắc người dù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 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 cho yêu cầu đến để thực hiện, hãy gọi hàm fallback() của thực thể app của bạn. (Ví dụ: nếu bạn đang sử dụng Dialogflow, đây là DialogflowApp#fallback() function.)

Ví dụ sau đây cho thấy một trình xử lý dự phòng đơn giản sẽ gửi lại một phản hồi chuỗi để 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 với thư viện ứng dụng. Để xem mức độ so khớp của thư viện ứng dụng ý định, hãy tham khảo bài viết "Xử lý trình xử lý ý định" trong Tìm hiểu cách hoạt động.

Truy cập các tham số và ngữ cảnh

Nếu đang sử dụng Dialogflow, bạn có thể xác định tham 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 luồng trò chuyện.

Thông số rất hữu ích trong việc thu thập các từ, cụm từ hoặc giá trị quan trọng của người dùng truy vấn. Dialogflow trích xuất các thông số tương ứng từ truy vấn của người dùng tại thời gian chạy, đồng thời bạn có thể xử lý các giá trị thông số này trong webhook của phương thức thực hiện để 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 tạo một 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 bạn có thể truy cập vào thuộc tính name qua Đố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 huỷ 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 đối tượng cục bộ biến:

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

Trong đoạn mã sau, tên tham số là full-name nhưng lại đã 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à phân nhánh của cuộc trò chuyện. Thư viện ứng dụng cấp quyền truy cập vào một ngữ cảnh thông qua DialogflowConversation#contexts . Đoạn mã sau đây cho biết cách bạn có thể đặt ngữ cảnh theo phương thức lập trình trong webhook của phương thức thực hiện 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ả ý đị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 của người trợ giúp bao bọc các loại dữ liệu người dùng phổ biến mà Hành động thường yêu cầu. Các bao gồm các lớp trình bày kết quả cho nhiều loại Actions on Google ý định của trình trợ giúp. Bạn 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à người dùng phải hãy cung cấp ý kiến đóng góp để 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 câu trả lời. Đoạn mã sau đây cho biết cách webhook có thể tuỳ chỉnh phản hồi dựa trên dựa trên kết quả do ý định của trình trợ giúp xác nhận trả về. Đối với ví dụ hoàn chỉnh hơn, hãy xem Confirmation tài liệu tham khảo về lớp.

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

Ví dụ: Kết quả dạng băng chuyền

Đoạn mã sau đây cho thấy cách webhook thực hiện đơn hàng 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 chọn. Để biết thêm ví dụ đầy đủ, hãy xem Carousel tài liệu tham khảo về lớp.

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 lớp phản hồi cuộc hội thoại thể hiện 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 phản hồi hoặc thành phần 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 biết cách webhook của phương thức thực hiện đơn hàng có thể gửi Image trong câu trả lời sẽ được tự động đính kèm vào câu trả lời BasicCard. thư viện:

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 Actions on Google Node.js được thiết kế để lập trình không đồng bộ. Trình xử lý ý định của bạn có thể trả về lời hứa sẽ giải quyết khi Webhook cho phương thức thực hiện đã tạo xong phản hồi.

Đoạn mã sau đây cho biết cách bạn có thể thực hiện lệnh gọi hàm không đồng bộ đến trả về đối tượng lời hứa và sau đó trả lời bằng tin nhắn nếu webhook thực hiện đơn hàng của bạn nhận được lời chào ý định. Trong đoạn mã này, lời hứa đảm bảo rằng webhook thực hiện đơn hàng 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 phân giải.

Trong ví dụ này, chúng ta sẽ sử dụng một API giả mạo để 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ã đơn giản sau đây có cùng tác dụng, nhưng sử dụng async Tính năng await được ra mắt 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 thực hiện đơn hàng của bạn lưu dữ liệu trong các cuộc trò chuyện cho để sử dụng sau này. Sau đây là một số đối tượng chính mà bạn có thể dùng để lưu trữ dữ liệu:

DialogflowConversation#data hoặc ActionsSdkConversation#data: Lưu dữ liệu ở định dạng JSON trong suốt một phiên trò chuyện giữa người dùng và Hành động của bạn.
Conversation#user.storage: Lưu dữ liệu ở định dạng JSON trên nhiều phiên trò chuyện.

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

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

Bạn có thể sử dụng Conversation#user đối tượng để lấy thông tin về người dùng, bao gồm giá trị nhận dạng chuỗi và thông tin cá nhân. Một số trường nhất định như conv.user.name.display và conv.user.email 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, tương ứng.

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ô nhờ 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. thư viện ứng dụng 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 Conversation và thêm chức năng bổ sung.

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

Đoạn mã sau đây cho thấy 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 cho phương thức thực hiện của bạn cho 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 các môi trường thời gian chạy khác nhau:

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 cùng dòng 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;