履行遷移作業

設定意圖和情境後，您必須更新執行要求程式碼，以因應動作建構工具的要求和回應格式的異動。同時，我們也趁這個機會考慮運用 Actions Builder 的其他功能。本頁說明更新執行要求程式碼的一般步驟和注意事項。

考量執行要求

專案的執行要求程式碼取決於對話模型和開發平台的功能。Actions Builder 引進了新的對話模型和功能，可以改變對話的建立方式，且可能會改變專案執行要求的方式。本節說明 Actions Builder 與 Dialogflow 不同的功能，以及這些差異會如何改變執行執行要求程式碼的方式。

  • 對話實作方式異動

    • Dialogflow 使用意圖導向的對話式對話流程，系統會根據訓練詞組和上述意圖的輸入/輸出背景資訊來比對個別意圖。
    • Actions Builder 的對話流程會使用「場景」做為對話回合的容器。在單一場景中，特定意圖可以比對，就像 Dialogflow 的情境一樣。轉場效果會根據比對的意圖，定義要轉換的場景。

  • 可重複使用的 Webhook 函式

    • 在 Dialogflow 中，Webhook 處理常式會與個別意圖相連結。如果需要其他邏輯，您必須建立另一個意圖來處理新函式。
    • Webhook 處理常式在 Actions Builder 中有自訂處理常式名稱。這項功能可讓您在專案的多個場景中呼叫函式。

  • 其他叫用 Webhook 的方式

    • 在 Dialogflow 中，每種意圖方法各有一個 Webhook 需要額外的意圖，以便在專案的執行要求中促成更對話的邏輯。
    • 動作建構工具可讓您從場景中的多個位置發出 Webhook 呼叫：可根據進入、根據條件、版位填充、自訂和系統意圖比對等方式。

更新出貨代碼

每項動作的執行要求程式碼都會因動作的複雜程度和用途而有所差異，不過更新程式碼時需採取一般步驟：

  1. 下載並安裝最新版本的用戶端程式庫。

    npm install @assistant/conversation

  2. 更新程式碼中的 require 陳述式。例如：

    const {
  SimpleResponse,
  BasicCard,
  Image,
} = require('actions-on-google');

    上述程式碼已更新為：

    const {
  conversation,
  Simple,
  Card,
  Image,
} = require('@assistant/conversation');

  3. 重構程式碼以使用新方法。

    • 意圖處理常式：app.intent → app.handle
    • 回覆/提示：conv.ask → conv.add
    • 途徑/裝置功能：conv.surface.capabilities.has('actions.capability.SCREEN_OUTPUT') → conv.device.capabilities.includes('RICH_RESPONSE')
    • 資料儲存空間：conv.data → conv.session.params

    • 回應類型：

      • SimpleResponse → Simple
      • BasicCard → Card
      • Suggestions → Suggestion

    • 意圖參數：conv.parameters[KEY] → conv.intent.parameters[KEY].resolved

    • 情境/場景轉場效果：conv.contexts.set(content_name, 5); → conv.scene.next.name = 'context_name'

    • 結束對話：conv.close(response) → conv.add.response; conv.scene.next.name = 'actions.page.END_CONVERSATION'

  4. 更新回應代碼以運用 Builder 的新回應基元。例如：

    conv.ask(new Suggestions (['a', 'b']));

    上述程式碼已更新為：

    for (suggestion of ['a', 'b']) {
  conv.add.(new Suggestion({title: suggestion}))
}

如需完整的方法清單，請參閱下方的執行要求代碼轉譯對應。

請參考以下頁面，比較要求與回應酬載：

設定 Webhook

更新執行要求後，請在專案的場景中啟用 Webhook 呼叫。雖然遷移工具會遷移 Dialogflow 意圖的 Webhook 設定，但由於重構執行要求程式碼和 Webhook 函式可能會改變，因此您仍須查看這些設定。

在 Dialogflow 中，Webhook 會在意圖中啟用，而執行要求程式碼則會包含意圖比對相符時要執行的處理常式和函式。在動作建構工具中，Webhook 可在叫用意圖或場景中觸發，進而傳送要求至執行要求端點。執行要求包含 Webhook 處理常式，會在要求中處理 JSON 酬載。您可以在下列情況觸發 Webhook：

  • 叫用意圖相符之後
  • 場景處於進入階段時
  • 場景條件階段中的條件評估結果為 True
  • 場景的插槽登記階段期間
  • 在場景的輸入階段中比對意圖後

從 Dialogflow 遷移至 Actions Builder 時，請務必考量對話流程中的變更，因為這樣做可能會影響您進行 Webhook 呼叫的時機和位置。

如要啟用 Webhook 呼叫，請按照下列步驟操作：

  1. 選取要呼叫 Webhook 的場景。

  2. 選擇要啟用 Webhook 的狀態。您可以對下列一或多個狀態啟用 Webhook：

    • 入場時
    • 條件
    • 運算單元填充
    • 使用者意圖處理
    • 系統意圖處理

  3. 勾選「Call your Webhook」選項。

  4. 輸入您在執行要求代碼中定義的 Webhook 處理常式。

  5. 點按「儲存」。

  6. 前往「測試」，試用 Webhook 呼叫和執行要求變更。

履行代碼轉譯對應

下表列出了 Dialogflow 執行要求程式碼語法如何轉譯為 Actions Builder 程式碼。如需完整方法清單，請參閱動作建構工具和 SDK 參考資料文件。

Dialogflow 動作建構工具
conv.data conv.session.params
conv.ask conv.add
conv.close conv.scene.next.name = 'actions.scene.END_CONVERSATION'
conv.user.storage conv.user.params
conv.input.raw conv.intent.query
conv.parameters conv.intent.params[key].resolved
conv.arguments.get('MEDIA_STATUS')
mediaStatus.status==='FINISHED'		 conv.intent.params['MEDIA_STATUS']
mediaStatus.resolved==='FINISHED'
活動 系統意圖處理：
MEDIA_STATUS_FINISHED
MEDIA_STATUS_FAILED
conv.device.capabilities.has("actions.capability.SCREEN_OUTPUT") conv.device.capabilities.includes("RICH_RESPONSE")
app.intent app.handler
app.middleware app.middleware
簡單回覆 prompt -firstSimple
複合式回應 prompt -content -card: object -image: object -table: object -media: object -suggestions -link

如要瞭解其他工具，請參閱下方資訊：

上一頁
專案遷移