內建意圖是您可以指定的專屬 ID,用來告知 Google 助理您的動作可以執行特定類別的使用者要求。舉例來說,以下是 Google 助理與內建意圖配對的使用者查詢內容範例:
- 「玩遊戲」內建意圖:「Ok Google。玩記憶遊戲"
- 「取得星座」內建意圖:「Ok Google。取得我的星座運勢。"
在動作探索期間,Google 助理可使用動作的中繼資料 (包括您指定的內建意圖),向使用者推薦動作。為盡量減少對話往返次數,Google 助理也會嘗試掃描使用者查詢中的參數,並傳遞至動作。
如要查看 Google 助理支援的內建意圖完整清單 (包括參數和使用者查詢範例),請參閱內建意圖參考資料。
整合內建意圖
視動作建構方式而定,整合內建意圖的方法可能不同。
Dialogflow
如果您使用 Dialogflow 建立動作,則可透過 Dialogflow 主控台附加內建意圖。
如要透過 Dialogflow 附加內建意圖,請按照下列步驟操作:
- 開啟 Dialogflow 主控台並選取您的代理程式,然後前往「Intents」(意圖) 畫面。
建立或選取代理程式收到特定內建意圖時觸發的意圖。開啟「Events」(事件) 部分,然後按一下「Add Event」(新增事件)。
在「Events」(事件) 欄位中,輸入代理程式內建意圖事件的名稱 (例如
actions_intent_PLAY_GAME
)。點按「儲存」。
Actions SDK
如果您使用 Actions SDK 建構動作,則必須指定內建意圖與動作套件中的動作之間的對應關係。
如要透過 Actions SDK 附加內建意圖,請按照下列步驟操作:
- 在 Action 定義的名稱欄位中指定內建意圖。
- 按照「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
值 (相對於叫用時間)。attributes
和timeIndicator
參數沒有任何值,因為使用者的叫用詞組未包含這些資訊。
如果使用 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.
});
測試內建意圖的整合作業
如要測試整合結果,請按照下列步驟操作:
- 啟用測試動作時開啟動作模擬工具,或在裝置上開啟 Google 助理。
- 說出或輸入與該內建意圖相關聯的查詢。例如:「我想玩遊戲」。
- 畫面顯示的應用程式選項對話方塊中,找出你的動作。
- 選擇您的應用程式,將意圖傳送至您的應用程式。
使用內建意圖的最佳做法
使用內建意圖時,您應遵循下列最佳做法:
- 將內建意圖對應至特定動作:當特定內建意圖觸發動作時,請盡可能將使用者引導至動作中的特定意圖和功能。舉例來說,如果您的動作支援
PLAY_GAME
內建意圖,並收到該意圖,您就應立即將使用者傳送到動作的遊戲功能。避免再次詢問使用者是否要玩遊戲。 - 處理內建意圖參數:請務必使用 Google 助理傳送至執行要求的內建意圖參數值。避免再次提示使用者輸入這些值。