Webhook

為了讓您更靈活地建構動作，您可以委派邏輯 HTTPS Web 服務 (執行要求)。您的動作會觸發 Webhook 向 HTTPS 端點發出要求以下列舉幾個功能 執行要求包括：

• 根據使用者提供的資訊產生動態提示。
• 在外部系統中下單並確認成功。
• 正在透過後端資料驗證運算單元。

圖 1. 可能會觸發叫用意圖和場景 Webhook。

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回應 JSON

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

{
  "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要求 JSON

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

{
  "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.jsJSON

conv.user.locale

{
  "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要求 JSON回應 JSON

//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 

{
  "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"
    ]
  }
}

{
  "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要求 JSON

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

{
  "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回應 JSON

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']
        },
    ]
  }
}];

{
  "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回應 JSON

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

{
  "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回應 JSON

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

{
  "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要求 JSON

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

{
  "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回應 JSON

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

{
  "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"
    }
  }
}

開發選項

動作建立工具 動作 SDK

動作建構工具提供一個名為 Cloud Functions 編輯器的內嵌編輯器。 直接在 Google Cloud 控制台中 控制台。您也可以為所選主機建構及部署執行要求 ，並將 HTTPS 執行要求端點註冊為 Webhook 處理常式。

內嵌編輯器

重要事項：如果您要建構及部署 以內嵌式 Cloud Functions 編輯器執行執行要求，您就必須 將帳單帳戶連結至您的 Google Cloud 專案這項規定需要 自 2020 年 8 月 17 日起生效。如需連結帳單帳戶的操作說明 新增至 Google Cloud 專案 修改 專案的帳單設定。 詳情請見 配額與 級別更高的定價 可能不準確或不適當強烈建議您盡快連結帳單帳戶 避免服務中斷

如要使用 Cloud Functions 編輯器進行開發，請按照下列步驟操作：

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

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

提示：如果你已變更出貨資訊 前往模擬工具 我們會詢問您是否要將變更部署至程式碼 已部署的程式碼

外部 HTTPS 端點

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

重要事項：如果您要建構 以 Cloud Functions 部署執行要求 Firebase，您必須在 Google Cloud 中將帳單帳戶連結至您的專案。這個 ，規定自 2020 年 8 月 17 日起生效。有關連結的操作說明 將帳單帳戶新增至 Google Cloud 專案，請參閱 修改 專案的帳單設定。 詳情請見 配額與 級別更高的定價 可能不準確或不適當強烈建議您盡快連結帳單帳戶 避免服務中斷

設定環境

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

1. 下載並安裝 Node.js。

2. 設定並初始化 Firebase CLI。如果下列指令失敗， 如果發生 EACCES 錯誤，你可能需要變更 npm 權限。

   npm install -g firebase-tools
   

3. 使用您的 Google 帳戶驗證 Firebase 工具：

   firebase login
   

4. 啟動您儲存Actions 專案的專案目錄。 系統會要求選取要設定的 Firebase CLI 功能 和 Actions 專案一起建立選擇Functions和其他您可能會想使用的功能 例如 Firestore，然後按下 Enter 鍵確認並繼續操作：

   $ cd <ACTIONS_PROJECT_DIRECTORY>
   $ firebase init
   

5. 使用 Actions 專案來選取 Firebase 工具與 Actions 專案之間的關聯 使用方向鍵瀏覽專案清單：

   注意： 您可以選取「略過」並略過這個步驟。 [不要設定預設專案]，您必須完成這個步驟 稍後使用 firebase use PROJECT_ID 指令建立關聯。

6. 選擇專案後，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
   

7. 選擇是否要使用 ESLint 找出可能的錯誤並強制執行樣式，方法是輸入 Y 或 N：

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

8. 在提示中輸入 Y，取得專案依附元件：

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

   設定完成後，您會看到類似下方的輸出內容：

   ✔  Firebase initialization complete!
   

9. 安裝 @assistant/conversation 依附元件：

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

10. 取得執行要求依附元件，並部署執行要求函式：

    $ 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>
    

11. 複製執行要求網址，以便在下節使用。

註冊 Webhook 處理常式

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

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