內建意圖 (Dialogflow)

內建意圖是您可以指定的專屬 ID,用來告知 Google 助理您的動作可以執行特定類別的使用者要求。舉例來說,以下是 Google 助理與內建意圖配對的使用者查詢內容範例:

  • 「玩遊戲」內建意圖:「Ok Google。玩記憶遊戲"
  • 「取得星座」內建意圖「Ok Google。取得我的星座運勢。"

動作探索期間,Google 助理可使用動作的中繼資料 (包括您指定的內建意圖),向使用者推薦動作。為盡量減少對話往返次數,Google 助理也會嘗試掃描使用者查詢中的參數,並傳遞至動作。

如要查看 Google 助理支援的內建意圖完整清單 (包括參數和使用者查詢範例),請參閱內建意圖參考資料

整合內建意圖

視動作建構方式而定,整合內建意圖的方法可能不同。

Dialogflow

如果您使用 Dialogflow 建立動作,則可透過 Dialogflow 主控台附加內建意圖。

如要透過 Dialogflow 附加內建意圖,請按照下列步驟操作:

  1. 開啟 Dialogflow 主控台並選取您的代理程式,然後前往「Intents」(意圖) 畫面。
  2. 建立或選取代理程式收到特定內建意圖時觸發的意圖。開啟「Events」(事件) 部分,然後按一下「Add Event」(新增事件)

    圖 1. 在 Dialogflow 控制台中新增 Dialogflow 事件。
  3. 在「Events」(事件) 欄位中,輸入代理程式內建意圖事件的名稱 (例如 actions_intent_PLAY_GAME)。

    圖 2. 在 Dialogflow 控制台中,將內建意圖附加至代理程式。
  4. 點按「儲存」

Actions SDK

如果您使用 Actions SDK 建構動作,則必須指定內建意圖與動作套件中的動作之間的對應關係。

如要透過 Actions SDK 附加內建意圖,請按照下列步驟操作:

  1. Action 定義的名稱欄位中指定內建意圖。
  2. 按照「Actions SDK 總覽」一文所述,使用 gactions 工具將動作套件上傳至 Actions 專案。

舉例來說,下列程式碼片段說明如何新增 CHECK_AIR_QUALITY 內建意圖:

{
   "actions":[
      {
         "description":"Default Welcome Intent",
         "name":"MAIN",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.MAIN"
         }
      },
      {
         "description":"Check Air Quality",
         "name":"CHECK_AIR_QUALITY",
         "fulfillment":{
            "conversationName":"conversation_1"
         },
         "intent":{
            "name":"actions.intent.CHECK_AIR_QUALITY"
         }
      }
   ],
   "conversations":{
      "conversation_1":{
         "name":"conversation_1",
         "url":"https://example.com/fulfillment",
         "fulfillmentApiVersion":2
      }
   }
}

處理內建意圖參數

透過內建意圖叫用動作時,您的執行要求可能會收到其他參數。意圖結構定義會將參數名稱及其類型定義為原始類型或 schema.org 實體。如要查看對話動作內建意圖的結構定義,請參閱內建意圖參考資料

內建意圖的參數為選用參數。如果您可以從使用者內建意圖的叫用中擷取出值,Google 助理就會處理將值填入參數。

舉例來說,actions.intent.CHECK_AIR_QUALITY 內建意圖的結構定義定義了四個選用參數:

參數名稱 類型
attributes 字串值。
location schema.org/Place 物件。
temporalCoverage schema.org/Duration 物件。
timeIndicator EnumeratedDuration (Google 專屬的擴充功能)。

以下程式碼片段舉例說明使用者說出「San Francisco 明天的空氣品質如何?」叫用您的動作時出現的對話 Webhook (JSON) 要求:

"inputs":[
      {
         "intent":"actions.intent.CHECK_AIR_QUALITY",
         "rawInputs":[
            {
               "inputType":"VOICE",
               "query":"what is the air quality in san francisco tomorrow"
            }
         ],
         "arguments":[
            {
               "name":"location",
               "structuredValue":{
                  "geo":{
                     "longitude":-122.41941550000001,
                     "latitude":37.7749295
                  },
                  "@context":"https://schema.org",
                  "@type":"Place",
                  "name":"san francisco"
               }
            },
            {
               "name":"temporalCoverage",
               "rawText":"2018-04-25",
               "textValue":"2018-04-25"
            }
         ]
      }
   ]

在這個例子中,參數採用下列值:

  • location 參數包含「San Francisco」的 schema.org/Place 值。
  • temporalCoverage 參數包含明天日期的 schema.org/Duration 值 (相對於叫用時間)。
  • attributestimeIndicator 參數沒有任何值,因為使用者的叫用詞組未包含這些資訊。

如果使用 Node.js 適用的 Actions on Google 用戶端程式庫,可擷取參數的值,如以下程式碼片段所示:

app.intent('actions.intent.CHECK_AIR_QUALITY', (conv) => {
  const attributes = conv.arguments.get('attributes');
  const location = conv.arguments.get('location');
  const temporal_coverage = conv.arguments.get('temporalCoverage');
  Const time_indicator = conv.arguments.get('timeIndicator')

  // Your Action logic. If you need to use any of the parameter values,
  // you should check first that it is defined. Arguments.get returns
  // undefined if it can't find a value for a parameter.

});

測試內建意圖的整合作業

如要測試整合結果,請按照下列步驟操作:

  1. 啟用測試動作時開啟動作模擬工具,或在裝置上開啟 Google 助理。
  2. 說出或輸入與該內建意圖相關聯的查詢。例如:「我想玩遊戲」。
  3. 畫面顯示的應用程式選項對話方塊中,找出你的動作。
  4. 選擇您的應用程式,將意圖傳送至您的應用程式。
圖 3. 「動作選取」對話方塊根據內建意圖詞組產生
圖 4. 叫用附加至內建意圖的動作。

使用內建意圖的最佳做法

使用內建意圖時,您應遵循下列最佳做法:

  • 將內建意圖對應至特定動作:當特定內建意圖觸發動作時,請盡可能將使用者引導至動作中的特定意圖和功能。舉例來說,如果您的動作支援 PLAY_GAME 內建意圖,並收到該意圖,您就應立即將使用者傳送到動作的遊戲功能。避免再次詢問使用者是否要玩遊戲。
  • 處理內建意圖參數:請務必使用 Google 助理傳送至執行要求的內建意圖參數值。避免再次提示使用者輸入這些值。