為了讓您更靈活地建構動作，您可以委派邏輯 HTTPS Web 服務 (執行要求)。您的動作會觸發 Webhook 向 HTTPS 端點發出要求以下列舉幾個功能 執行要求包括：
- 根據使用者提供的資訊產生動態提示。
- 在外部系統中下單並確認成功。
- 正在透過後端資料驗證運算單元。
Webhook 觸發條件和處理常式
您的動作可在叫用意圖或場景中觸發 Webhook 會向您的執行要求端點傳送要求。您的執行要求包含 Webhook 在要求中處理 JSON 酬載的處理常式。您可以在 下列情況：
- 成功比對叫用意圖後
- 在進入舞台的場景中
- 某個條件在場景的條件階段評估為 true 之後
- 場景的運算單元填充階段
- 在情境的輸入階段發生意圖比對後
當你在動作中觸發 Webhook 時，Google 助理會傳送要求 並將 JSON 酬載套用至您的執行要求，其中包含 處理事件所用的處理常式名稱。您的執行要求端點 將事件轉送至適當的處理常式，執行邏輯並傳回 與 JSON 酬載相關的回應。
酬載
下列程式碼片段為動作傳送的要求示例 以及執行要求傳回的回應。詳情請參閱 參考說明文件 可能不準確或不適當
要求範例
{
"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"
]
}
}
回應範例
{
"session": {
"id": "example_session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "Hello World.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "actions.scene.END_CONVERSATION"
}
}
}
執行階段互動
以下各節將說明您可以在 Webhook 處理常式
傳送提示
您可以用簡單的文字、RTF 格式和資訊卡建立提示，甚至可以完全模糊處理 由網頁應用程式支援的 HTML 提示和互動畫布。提示說明文件提供 提供有關如何在處理 Webhook 事件時建立提示的完整資訊。 下列程式碼片段為卡片提示：
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
{
"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": ""
}
}
}
讀取意圖參數
當 Google 助理執行階段符合意圖時，就會擷取 參數。原始屬性是使用者提供的輸入內容 已解析屬性，NLU 會根據類型 規格。
Node.js
conv.intent.params['param_name'].original
conv.intent.params['param_name'].resolved
要求 JSON
{
"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"
]
}
}
讀取使用者語言代碼
這個值對應的是使用者針對 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"
]
}
}
讀取及寫入儲存空間
請參閱儲存空間說明文件，進一步瞭解如何 且會使用多項儲存空間功能
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
{
"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
{
"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"
}
}
}
檢查裝置功能
您可以查看裝置功能，藉此提供不同的體驗。 對話流程
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
{
"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"
]
}
}
如需完整的表面功能清單，請參閱 Capability
參照。
執行階段類型覆寫
執行階段類型可讓您在執行階段修改類型規格。您可以使用 功能，載入其他來源的資料以填入類型的有效值。適用對象 舉例來說，您可以使用執行階段類型覆寫功能，在問卷調查中加入動態選項 問題，或在菜單加入每日項目。
如要使用執行階段類型，您必須透過動作觸發 Webhook，呼叫
執行要求。接著，您可以填入
session.typeOverrides 參數，以回應動作。可用
模式包括 TYPE_MERGE 以保留現有的類型項目，或 TYPE_REPLACE
以覆寫值取代現有項目
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
{
"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."
}
}
}
提供語音自訂調整功能
語音自訂調整功能可讓您指定 NLU 的提示，以便改善意圖比對成效。個人中心 最多可以指定 1000 個項目。
Node.js
conv.expected.speech = ['value_1', 'value_2']
conv.expected.language = 'locale_string'
回應 JSON
{
"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"
}
}
轉場效果場景
除了在 Actions 專案中定義靜態轉換外， ，因此場景轉換會在執行階段發生
Node.js
app.handle('transition_to_hidden_scene', conv => {
// Dynamic transition
conv.scene.next.name = "HiddenScene";
});
回應 JSON
{
"session": {
"id": "session_id",
"params": {}
},
"prompt": {
"override": false,
"firstSimple": {
"speech": "This is an example prompt.",
"text": ""
}
},
"scene": {
"name": "SceneName",
"slots": {},
"next": {
"name": "HiddenScene"
}
}
}
讀取場景版位
在運算單元填充期間，您可以使用執行要求來驗證運算單元，或查看
運算單元填充狀態 (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
舉例來說，假設您想要從回應中擷取時區。於
在這個範例中，版位名稱為 datetime1。若要取得時區，您應
而是使用：
conv.scene.slots['datetime1'].value.time_zone.id
要求 JSON
{
"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"
]
}
}
撤銷場景運算單元
您可以撤銷版位，讓使用者提供新值。
Node.js
conv.scene.slots['slot_name'].status = 'INVALID'
回應 JSON
{
"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"
}
}
}
開發選項
動作建構工具提供一個名為 Cloud Functions 編輯器的內嵌編輯器。 直接在 Google Cloud 控制台中 控制台。您也可以為所選主機建構及部署執行要求 ，並將 HTTPS 執行要求端點註冊為 Webhook 處理常式。
內嵌編輯器
如要使用 Cloud Functions 編輯器進行開發，請按照下列步驟操作：
- 建立「
sdk/webhooks/ActionsOnGoogleFulfillment.yaml」檔案。 並為動作定義處理常式和使用的內嵌 Cloud 函式 執行要求handlers: - name: questionOnEnterFunc - name: fruitSlotValidationFunc inlineCloudFunction: executeFunction: ActionsOnGoogleFulfillment - 建立資料夾
sdk/webhooks/ActionsOnGoogleFulfillment， 並新增實作處理常式的index.js檔案 先前定義的，以及定義 npm 的package.json檔案 瞭解程式碼的需求// 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" } }
外部 HTTPS 端點
本節說明如何將 Cloud Functions for Firebase Conversational Action 的執行要求服務。不過，您就能 要求傳送至您選擇的代管服務。
設定環境
使用 Cloud Functions 時，建議您採用以下專案結構 Firebase 做為執行要求服務：
ProjectFolder - Root folder for the project sdk - Actions project configuration files functions - Cloud functions for Firebase files
如要設定環境，請按照下列步驟操作：
- 下載並安裝 Node.js。
設定並初始化 Firebase CLI。如果下列指令失敗， 如果發生
EACCES錯誤，你可能需要變更 npm 權限。npm install -g firebase-tools使用您的 Google 帳戶驗證 Firebase 工具：
firebase login啟動您儲存Actions 專案的專案目錄。 系統會要求選取要設定的 Firebase CLI 功能 和 Actions 專案一起建立選擇
Functions和其他您可能會想使用的功能 例如 Firestore，然後按下 Enter 鍵確認並繼續操作：$ cd <ACTIONS_PROJECT_DIRECTORY> $ firebase init使用 Actions 專案來選取 Firebase 工具與 Actions 專案之間的關聯 使用方向鍵瀏覽專案清單：
選擇專案後，Firebase 工具會啟動函式 。使用方向鍵選取項目 然後按下 Enter 鍵繼續。
=== 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
選擇是否要使用 ESLint 找出可能的錯誤並強制執行樣式，方法是輸入 Y 或 N：
? Do you want to use ESLint to catch probable bugs and enforce style? (Y/n)
在提示中輸入 Y，取得專案依附元件：
? Do you want to install dependencies with npm now? (Y/n)
設定完成後，您會看到類似下方的輸出內容：
✔ Firebase initialization complete!安裝 @assistant/conversation 依附元件：
$ cd <ACTIONS_PROJECT_DIRECTORY>/functions $ npm install @assistant/conversation --save取得執行要求依附元件，並部署執行要求函式：
$ npm install $ firebase deploy --only functions部署作業需要幾分鐘才能完成。完成後，您會看到類似的內容 如下：您需要函式網址才能輸入 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>複製執行要求網址，以便在下節使用。
註冊 Webhook 處理常式
- 建立
sdk/webhooks/ActionsOnGoogleFulfillment.yaml檔案並定義 動作的處理常式以及 Webhook 要求的網址。httpsEndpoint: baseUrl: https://my.web.hook/ActionsOnGoogleFulfillment endpointApiVersion: 2 handlers: - name: questionOnEnterFunc - name: fruitSlotValidationFunc