Webhook

Để có thêm tính linh hoạt trong việc tạo Hành động, bạn có thể uỷ quyền logic cho các dịch vụ web HTTPS (thực hiện). Các Hành động của bạn có thể kích hoạt webhook để đưa ra yêu cầu đến một điểm cuối HTTPS. Sau đây là một số ví dụ về những việc bạn có thể làm trong quá trình thực hiện:

  • Tạo câu lệnh động dựa trên thông tin do người dùng cung cấp.
  • Đặt hàng trong một hệ thống bên ngoài và xác nhận thành công.
  • Xác thực các vị trí bằng dữ liệu phụ trợ.
Hình 1. Lời gọi ý định và cảnh có thể kích hoạt webhook.

Điều kiện kích hoạt và trình xử lý webhook

Các Thao tác của bạn có thể kích hoạt một webhook trong các ý định hoặc cảnh gọi, gửi yêu cầu đến điểm cuối thực hiện của bạn. Yêu cầu thực hiện của bạn có chứa các trình xử lý webhook xử lý tải trọng JSON trong yêu cầu. Bạn có thể kích hoạt webhook trong những trường hợp sau:

  • Sau khi một ý định gọi khớp
  • Trong giai đoạn nhập của một cảnh
  • Sau khi một điều kiện được đánh giá là đúng trong giai đoạn điều kiện của cảnh
  • Trong giai đoạn điền thông tin vào ô của một cảnh
  • Sau khi một ý định trùng khớp xảy ra ở giai đoạn đầu vào của cảnh

Khi bạn kích hoạt một webhook trong Hành động của mình, Trợ lý Google sẽ gửi một yêu cầu có tải trọng JSON đến dịch vụ thực hiện của bạn. Yêu cầu này chứa tên của trình xử lý cần dùng để xử lý sự kiện. Điểm cuối thực hiện đơn hàng có thể định tuyến sự kiện đến trình xử lý thích hợp để thực hiện logic và trả về phản hồi tương ứng bằng tải trọng JSON.

Tải trọng

Các đoạn mã sau đây cho thấy các yêu cầu mẫu mà Hành động của bạn gửi đến dịch vụ thực hiện và phản hồi mà dịch vụ thực hiện gửi lại. Hãy xem tài liệu tham khảo để biết thêm thông tin.

Ví dụ về yêu cầu

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "example_session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Ví dụ về phản hồi

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello World.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Tương tác trong thời gian chạy

Các phần sau đây mô tả những tác vụ phổ biến mà bạn có thể thực hiện trong trình xử lý webhook.

Gửi câu lệnh

Bạn có thể tạo câu lệnh bằng văn bản đơn giản, văn bản đa dạng thức, thẻ và thậm chí cả câu lệnh HTML đầy đủ được hỗ trợ bởi một ứng dụng web có Canvas tương tác. Tài liệu về lời nhắc có đầy đủ thông tin về cách tạo lời nhắc khi xử lý một sự kiện webhook. Các đoạn mã sau đây cho thấy một lời nhắc dạng thẻ:

Node.js

app.handle('rich_response', conv => {
  conv.add('This is a card rich response.');
  conv.add(new Card({
    title: 'Card Title',
    subtitle: 'Card Subtitle',
    text: 'Card Content',
    image: new Image({
      url: 'https://developers.google.com/assistant/assistant_96.png',
      alt: 'Google Assistant logo'
    })
  }));
});

JSON phản hồi

{
  "session": {
    "id": "example_session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "content": {
      "card": {
        "title": "Card Title",
        "subtitle": "Card Subtitle",
        "text": "Card Content",
        "image": {
          "alt": "Google Assistant logo",
          "height": 0,
          "url": "https://developers.google.com/assistant/assistant_96.png",
          "width": 0
        }
      }
    },
    "firstSimple": {
      "speech": "This is a card rich response.",
      "text": ""
    }
  }
}

Đọc các tham số về ý định

Khi thời gian chạy Trợ lý so khớp một ý định, thời gian chạy này sẽ trích xuất mọi tham số đã xác định. Thuộc tính ban đầu là những gì người dùng cung cấp dưới dạng dữ liệu đầu vào và thuộc tính được phân giải là những gì NLU phân giải dữ liệu đầu vào thành dựa trên quy cách loại.

Node.js

conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved

JSON yêu cầu

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "intent_name",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {},
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Đọc ngôn ngữ của người dùng

Giá trị này tương ứng với chế độ cài đặt ngôn ngữ của người dùng cho Trợ lý Google.

Node.js

conv.user.locale

JSON

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Đọc và ghi bộ nhớ

Hãy xem tài liệu về bộ nhớ để biết thông tin đầy đủ về cách sử dụng các tính năng lưu trữ.

Node.js

//read
conv.session.params.key
conv.user.params.key
conv.home.params.key

// write
conv.session.params.key = value
conv.user.params.key = value
conv.home.params.key = value

JSON yêu cầu

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    },
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

JSON phản hồi

{
  "session": {
    "id": "session_id",
    "params": {
      "key": "value"
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "Hello world.",
      "text": ""
    }
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED",
      "key": "value"
    }
  },
  "home": {
    "params": {
      "key": "value"
    }
  }
}

Kiểm tra các chức năng của thiết bị

Bạn có thể kiểm tra khả năng của thiết bị để mang đến nhiều trải nghiệm hoặc luồng trò chuyện.

Node.js

const supportsRichResponse = conv.device.capabilities.includes("RICH_RESPONSE");
const supportsLongFormAudio = conv.device.capabilities.includes("LONG_FORM_AUDIO");
const supportsSpeech = conv.device.capabilities.includes("SPEECH");
const supportsInteractiveCanvas = conv.device.capabilities.includes("INTERACTIVE_CANVAS");

JSON yêu cầu

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "actions.intent.MAIN",
    "params": {},
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "UNSPECIFIED",
    "slots": {}
  },
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [],
    "languageCode": ""
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO",
      "INTERACTIVE_CANVAS"
    ]
  }
}

Để biết danh sách đầy đủ các chức năng của nền tảng, hãy xem tài liệu tham khảo về Capability.

Ghi đè loại thời gian chạy

Các loại thời gian chạy cho phép bạn sửa đổi thông số kỹ thuật về loại trong thời gian chạy. Bạn có thể sử dụng tính năng này để tải dữ liệu từ các nguồn khác nhằm điền sẵn các giá trị hợp lệ của một loại. Ví dụ: bạn có thể sử dụng các chế độ ghi đè kiểu thời gian chạy để thêm các lựa chọn động vào một câu hỏi khảo sát hoặc thêm một mục hằng ngày vào một trình đơn.

Để sử dụng các loại thời gian chạy, bạn sẽ kích hoạt một webhook từ Hành động gọi một trình xử lý trong quá trình thực hiện. Từ đó, bạn có thể điền thông số session.typeOverrides vào một phản hồi gửi lại cho Thao tác của mình. Các chế độ có sẵn bao gồm TYPE_MERGE để giữ lại các mục nhập kiểu hiện có hoặc TYPE_REPLACE để thay thế các mục nhập hiện có bằng các mục nhập ghi đè.

Node.js

conv.session.typeOverrides = [{
    name: type_name,
    mode: 'TYPE_REPLACE',
    synonym: {
      entries: [
        {
          name: 'ITEM_1',
          synonyms: ['Item 1', 'First item']
        },
        {
          name: 'ITEM_2',
          synonyms: ['Item 2', 'Second item']
       },
       {
          name: 'ITEM_3',
          synonyms: ['Item 3', 'Third item']
        },
        {
          name: 'ITEM_4',
          synonyms: ['Item 4', 'Fourth item']
        },
    ]
  }
}];

JSON phản hồi

{
  "session": {
    "id": "session_id",
    "params": {},
    "typeOverrides": [
      {
        "name": "type_name",
        "synonym": {
          "entries": [
            {
              "name": "ITEM_1",
              "synonyms": [
                "Item 1",
                "First item"
              ]
            },
            {
              "name": "ITEM_2",
              "synonyms": [
                "Item 2",
                "Second item"
              ]
            },
            {
              "name": "ITEM_3",
              "synonyms": [
                "Item 3",
                "Third item"
              ]
            },
            {
              "name": "ITEM_4",
              "synonyms": [
                "Item 4",
                "Fourth item"
              ]
            }
          ]
        },
        "typeOverrideMode": "TYPE_REPLACE"
      }
    ]
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  }
}

Cung cấp tính năng thiên vị lời nói

Tính năng thiên vị lời nói cho phép bạn chỉ định các gợi ý cho NLU để cải thiện khả năng so khớp ý định. Bạn có thể chỉ định tối đa 1.000 mục.

Node.js

conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'

JSON phản hồi

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": "This is an example prompt."
    }
  },
  "expected": {
    "speech": "['value_1', 'value_2']",
    "language": "locale_string"
  }
}

Chuyển cảnh

Ngoài việc xác định các hiệu ứng chuyển đổi tĩnh trong dự án Actions, bạn có thể khiến các hiệu ứng chuyển đổi cảnh xảy ra trong thời gian chạy.

Node.js

app.handle('transition_to_hidden_scene', conv => {
  // Dynamic transition
  conv.scene.next.name = "HiddenScene";
});

JSON phản hồi

{
  "session": {
    "id": "session_id",
    "params": {}
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {},
    "next": {
      "name": "HiddenScene"
    }
  }
}

Đọc các vị trí trong cảnh

Trong quá trình điền thông tin vào vị trí, bạn có thể sử dụng phương thức thực hiện để xác thực vị trí hoặc kiểm tra trạng thái điền thông tin vào vị trí (SlotFillingStatus).

Node.js

conv.scene.slotFillingStatus  // FINAL means all slots are filled
conv.scene.slots  // Object that contains all the slots
conv.scene.slots['slot_name'].<property_name> // Accessing a specific slot's properties

Ví dụ: giả sử bạn muốn trích xuất múi giờ từ một phản hồi. Trong ví dụ này, tên vùng quảng cáo là datetime1. Để lấy múi giờ, bạn sẽ sử dụng:

conv.scene.slots['datetime1'].value.time_zone.id

JSON yêu cầu

{
  "handler": {
    "name": "handler_name"
  },
  "intent": {
    "name": "",
    "params": {
      "slot_name": {
        "original": "1",
        "resolved": 1
      }
    },
    "query": ""
  },
  "scene": {
    "name": "SceneName",
    "slotFillingStatus": "FINAL",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "SLOT_UNSPECIFIED",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  },
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    },
    "typeOverrides": []
  },
  "user": {
    "locale": "en-US",
    "params": {
      "verificationStatus": "VERIFIED"
    }
  },
  "home": {
    "params": {}
  },
  "device": {
    "capabilities": [
      "SPEECH",
      "RICH_RESPONSE",
      "LONG_FORM_AUDIO"
    ]
  }
}

Vô hiệu hoá các vùng trong cảnh

Bạn có thể vô hiệu hoá các vị trí và yêu cầu người dùng cung cấp một giá trị mới.

Node.js

conv.scene.slots['slot_name'].status = 'INVALID'

JSON phản hồi

{
  "session": {
    "id": "session_id",
    "params": {
      "slot_name": 1
    }
  },
  "prompt": {
    "override": false,
    "firstSimple": {
      "speech": "This is an example prompt.",
      "text": ""
    }
  },
  "scene": {
    "name": "SceneName",
    "slots": {
      "slot_name": {
        "mode": "REQUIRED",
        "status": "INVALID",
        "updated": true,
        "value": 1
      }
    },
    "next": {
      "name": "actions.scene.END_CONVERSATION"
    }
  }
}

Tuỳ chọn phát triển

Actions Builder cung cấp một trình chỉnh sửa nội tuyến có tên là trình chỉnh sửa Cloud Functions, cho phép bạn tạo và triển khai một Cloud Function cho Firebase ngay trong bảng điều khiển. Bạn cũng có thể tạo và triển khai dịch vụ thực hiện đơn hàng cho dịch vụ lưu trữ mà bạn chọn, đồng thời đăng ký điểm cuối thực hiện đơn hàng HTTPS làm trình xử lý webhook.

Trình chỉnh sửa nội dòng

Cách phát triển bằng trình chỉnh sửa Cloud Functions:

  1. Tạo tệp sdk/webhooks/ActionsOnGoogleFulfillment.yaml và xác định trình xử lý cho Hành động của bạn và hàm đám mây nội tuyến dùng để thực hiện. 
    handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc
inlineCloudFunction:
  executeFunction: ActionsOnGoogleFulfillment
  2. Tạo thư mục sdk/webhooks/ActionsOnGoogleFulfillment, rồi thêm tệp index.js triển khai các trình xử lý đã xác định trước đó và tệp package.json xác định các yêu cầu npm cho mã của bạn. 
    // index.js
const {conversation} = require('@assistant/conversation');
const functions = require('firebase-functions');

const app = conversation();

app.handle('questionOnEnterFunc', conv => {
  conv.add('questionOnEnterFunc triggered on webhook');
});

app.handle('fruitSlotValidationFunc', conv => {
  conv.add('fruitSlotValidationFunc triggered on webhook');
});

exports.ActionsOnGoogleFulfillment = functions.https.onRequest(app);
    
    // package.json
{
  "name": "ActionsOnGoogleFulfillment",
  "version": "0.1.0",
  "description": "Actions on Google fulfillment",
  "main": "index.js",
  "dependencies": {
    "@assistant/conversation": "^3.0.0",
    "firebase-admin": "^5.4.3",
    "firebase-functions": "^0.7.1"
  }
}

Điểm cuối HTTPS bên ngoài

Phần này mô tả cách thiết lập Cloud Functions cho Firebase làm dịch vụ thực hiện cho Thao tác đàm thoại. Tuy nhiên, bạn có thể triển khai dịch vụ thực hiện đơn hàng cho dịch vụ lưu trữ mà bạn chọn.

Thiết lập môi trường

Bạn nên sử dụng cấu trúc dự án sau đây khi dùng Cloud Functions cho Firebase làm dịch vụ thực hiện:

ProjectFolder        - Root folder for the project
  sdk                - Actions project configuration files
  functions          - Cloud functions for Firebase files

Để thiết lập môi trường, hãy làm theo các bước sau:

  1. Tải và cài đặt Node.js.

  2. Thiết lập và khởi chạy Giao diện dòng lệnh (CLI) của Firebase. Nếu lệnh sau không thực hiện được và trả về lỗi EACCES, thì bạn có thể phải thay đổi quyền npm.

    npm install -g firebase-tools

  3. Xác thực công cụ firebase bằng Tài khoản Google của bạn:

    firebase login

  4. Khởi động thư mục dự án nơi bạn đã lưu dự án Hành động. Bạn sẽ được yêu cầu chọn những tính năng của Firebase CLI mà bạn muốn thiết lập cho dự án Actions của mình. Chọn Functions và các tính năng khác mà bạn có thể muốn sử dụng, chẳng hạn như Firestore, sau đó nhấn Enter để xác nhận và tiếp tục:

    $ cd <ACTIONS_PROJECT_DIRECTORY>
$ firebase init

  5. Liên kết công cụ Firebase với dự án Actions bằng cách chọn công cụ đó bằng các phím mũi tên để di chuyển trong danh sách dự án:

  6. Sau khi bạn chọn dự án, công cụ Firebase sẽ bắt đầu thiết lập Functions và hỏi bạn muốn sử dụng ngôn ngữ nào. Chọn bằng các phím mũi tên rồi nhấn Enter để tiếp tục.

    === Functions Setup
A functions directory will be created in your project with a Node.js
package pre-configured. Functions can be deployed with firebase deploy.

? What language would you like to use to write Cloud Functions? (Use arrow keys)
> JavaScript
TypeScript

  7. Chọn xem bạn có muốn dùng ESLint để phát hiện các lỗi có thể xảy ra và thực thi kiểu bằng cách nhập Y hoặc N hay không:

    ? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)

  8. Lấy các phần phụ thuộc của dự án bằng cách nhập Y vào lời nhắc:

    ? Do you want to install dependencies with npm now? (Y/n)

    Sau khi thiết lập xong, bạn sẽ thấy kết quả tương tự như sau:

    ✔  Firebase initialization complete!

  9. Cài đặt phần phụ thuộc @assistant/conversation:

    $ cd <ACTIONS_PROJECT_DIRECTORY>/functions
$ npm install @assistant/conversation --save

  10. Lấy các phần phụ thuộc của yêu cầu thực hiện và triển khai hàm thực hiện:

    $ npm install
$ firebase deploy --only functions

    Quá trình triển khai sẽ mất vài phút. Sau khi hoàn tất, bạn sẽ thấy kết quả tương tự như sau. Bạn sẽ cần URL hàm để nhập vào Dialogflow.

    ✔  Deploy complete!
    
Project Console: https://console.firebase.google.com/project/<PROJECT_ID>/overview
Function URL (<FUNCTION_NAME>): https://us-central1-<PROJECT_ID>.cloudfunctions.net/<FUNCTION_NAME>

  11. Sao chép URL thực hiện để sử dụng trong phần tiếp theo.

Đăng ký trình xử lý webhook

  1. Tạo tệp sdk/webhooks/ActionsOnGoogleFulfillment.yaml và xác định trình xử lý cho Thao tác và URL cho các yêu cầu webhook. 
    httpsEndpoint:
  baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment
  endpointApiVersion: 2
handlers:
- name: questionOnEnterFunc
- name: fruitSlotValidationFunc