裝置可能具備目前一組特徵 無法涵蓋的特殊功能,例如可閃爍裝置燈的「閃爍我的燈」特徵。您可以為裝置定義自訂動作,指定傳送至裝置的指令以觸發特殊功能。
如要定義自訂裝置動作,您需要下列項目:
- 與使用者查詢比對的模式
- 與比對相符的查詢建立關聯的自訂裝置動作
- 如果裝置支援這項操作,系統會朗讀給使用者的文字
- 傳回到裝置的指令名稱,以及所有參數
將這項資訊放入動作套件,即可建立自訂裝置動作。動作套件會定義 Google 助理回應的格式。與 Actions SDK 不同的是,自訂裝置動作是在本機執行,您不會指定處理要求和提供回應的端點。自訂裝置動作本質上不屬於對話性質。
建立動作套件
以以下範例說明建立用來定義測試指令的檔案 (例如 actions.json
):閃爍 LED 燈。 從上一步下載的程式碼範例複製程式碼:
cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/grpc/
cp ~/assistant-sdk-python/google-assistant-sdk/actions.json .
{ "manifest": { "displayName": "Blinky light", "invocationName": "Blinky light", "category": "PRODUCTIVITY" }, "actions": [ { "name": "com.example.actions.BlinkLight", "availability": { "deviceClasses": [ { "assistantSdkDevice": {} } ] }, "intent": { "name": "com.example.intents.BlinkLight", "parameters": [ { "name": "number", "type": "SchemaOrg_Number" }, { "name": "speed", "type": "Speed" } ], "trigger": { "queryPatterns": [ "blink ($Speed:speed)? $SchemaOrg_Number:number times", "blink $SchemaOrg_Number:number times ($Speed:speed)?" ] } }, "fulfillment": { "staticFulfillment": { "templatedResponse": { "items": [ { "simpleResponse": { "textToSpeech": "Blinking $number times" } }, { "deviceExecution": { "command": "com.example.commands.BlinkLight", "params": { "speed": "$speed", "number": "$number" } } } ] } } } } ], "types": [ { "name": "$Speed", "entities": [ { "key": "SLOWLY", "synonyms": [ "slowly", "slow" ] }, { "key": "NORMALLY", "synonyms": [ "normally", "regular" ] }, { "key": "QUICKLY", "synonyms": [ "quickly", "fast", "quick" ] } ] } ] }
上一個範例使用以下資訊來定義自訂裝置動作:
- 與使用者查詢比對的模式 (閃爍 N 次)
- 基於機構目的,與相符查詢 (
com.example.actions.BlinkLight
) 建立關聯的自訂裝置動作 - 如果裝置支援動作,系統會向使用者朗讀文字 (閃爍 N 次)
- 傳回裝置的指令名稱 (
com.example.commands.BlinkLight
),以及任何參數 (數字,可能有助於說明速度)
如要定義查詢模式,請注意下列事項:
- 您可以在查詢模式中使用 schema.org 定義的類型。
types [...]
陣列會定義自訂類型清單 (例如$Speed
)。- 您可以在查詢模式中使用自訂類型。使用者可以說出自訂類型中的任何同義詞,以符合查詢模式。
- 如果同義詞相符,類型例項 (
speed
) 會傳回正規化鍵 (SLOWLY
)。舉例來說,不同燈具中可以支援不同的閃爍速度。 - 要求的 TTS 模式部分可以選用。例如,在查詢模式中使用
($Speed:speed)?
,即可將這個部分設定為選用。 - 回應中的
$type.raw
(例如$speed.raw
) 會替換為使用者實際叫用的字詞。
如需許多欄位的說明,請參閱 ActionPackage 說明文件。
部署動作套件
在動作套件中建構自訂裝置動作後,即可開放 Google 助理存取動作套件。
雖然您可以在裝置上執行本節所述的步驟,但在開發系統上操作可能會比較簡單。下列指令不需要虛擬環境執行。
下載
gactions
指令列工具。移除
gactions
工具所在目錄中的任何現有憑證。rm creds.data
使用
gactions
CLI 將動作套件儲存至 Google。將project_id
替換成您的 Actions Console 專案 ID。./gactions update --action_package actions.json --project project_id
。首次執行這個指令時,系統會提供您網址並要求您登入。請複製網址並貼到瀏覽器中 (任何系統都不需要這麼做)。 該頁面會要求你登入 Google 帳戶。登入在先前的 步驟。
在您核准 API 的權限要求之後,瀏覽器內會出現一組代碼,例如「4/XXXX」。複製以下程式碼並貼到終端機中:
Enter the authorization code:
如果授權成功,您會看到類似以下的回應:
Your app for the Assistant for project my-devices-project was successfully updated with your actions.
使用
gactions
CLI 將動作套件部署至測試模式。執行這個指令之前,您必須至少將動作套件儲存到 Google 至少一次。測試模式只會在使用者帳戶上啟用動作套件。./gactions test --action_package actions.json --project project_id
您目前無法使用動作模擬工具測試專案。
如要更新動作套件,請使用
gactions update
指令。
修改樣本
請在裝置上執行此章節中的步驟。
nano pushtotalk.py
為自訂動作新增處理常式。請注意,下列處理常式已新增至上述範例動作套件的程式碼範例。
... device_handler = device_helpers.DeviceRequestHandler(device_id) @device_handler.command('com.example.commands.BlinkLight') def blink(speed, number): logging.info('Blinking device %s times.' % number) delay = 1 if speed == "SLOWLY": delay = 2 elif speed == "QUICKLY": delay = 0.5 for i in range(int(number)): logging.info('Device is blinking.') # GPIO.output(25, 1) time.sleep(delay) # GPIO.output(25, 0) time.sleep(1)
執行範例
執行原始碼。
python pushtotalk.py
嘗試查詢。就上述範例而言,請嘗試下列做法:
閃爍 5 次。
請注意,查詢必須符合動作套件中的查詢模式。