對話動作已於 2023 年 6 月 13 日淘汰。詳情請參閱「對話動作已淘汰」。

本頁面由 Cloud Translation API 翻譯而成。

Webhook
透過集合功能整理內容你可以依據偏好儲存及分類內容。

為了讓您更靈活地建構動作，您可以委派邏輯 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 編輯器進行開發，請按照下列步驟操作：

開啟「動作」專案並前往「開發」分頁Webhook >變更執行要求方法。畫面上會顯示「Fulfillment methods」 (執行要求方法) 視窗。
選取「Inline Cloud Functions」，然後按一下「Confirm」(確認)。

，瞭解如何調查及移除這項存取權。

外部 HTTPS 端點

本節說明如何將 Cloud Functions for Firebase Conversational Action 的執行要求服務。不過，您就能要求傳送至您選擇的代管服務。

設定環境

如要設定環境，請按照下列步驟操作：

下載並安裝 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 use PROJECT_ID 指令建立關聯。

選擇專案後，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 處理常式

如要將 Cloud 函式端點註冊為 Webhook 處理常式，請按照下列步驟操作：

在 Actions 控制台中，依序按一下「開發」>「開發」Webhook。
按一下「變更執行要求方法」。「Fulfillment methods」 (執行要求方法) 視窗出現。
選取「Webhook」，然後按一下「確認」。
將網路服務網址貼到「Webhook」欄位中。
按一下 [儲存]。

Webhook 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Webhook 觸發條件和處理常式

酬載

要求範例

回應範例

執行階段互動

傳送提示

Node.js

回應 JSON

讀取意圖參數

Node.js

要求 JSON

讀取使用者語言代碼

Node.js

JSON

讀取及寫入儲存空間

Node.js

要求 JSON

回應 JSON

檢查裝置功能

Node.js

要求 JSON

執行階段類型覆寫

Node.js

回應 JSON

提供語音自訂調整功能

Node.js

回應 JSON

轉場效果場景

Node.js

回應 JSON

讀取場景版位

Node.js

要求 JSON

撤銷場景運算單元

Node.js

回應 JSON

開發選項

內嵌編輯器

外部 HTTPS 端點

設定環境

註冊 Webhook 處理常式

Webhook
透過集合功能整理內容你可以依據偏好儲存及分類內容。