デバイスには、現在のトレイト のセットでは対応できない特別な機能がある場合があります(たとえば、ライトを点滅させることができるデバイスの「blink my light」トレイトなど)。デバイス用のカスタム アクションを定義して、特別な機能をトリガーするためにデバイスに送信するコマンドを指定できます。
カスタム デバイス アクションを定義するには、次のものが必要です。
- ユーザークエリに対して照合するパターン
- 一致したクエリに関連付けるカスタム デバイス アクション
- デバイスがアクションをサポートしている場合にユーザーにテキストが読み上げられる
- デバイスに返されるコマンド名とパラメータ
カスタム デバイス アクションを作成するには、この情報をアクション パッケージに含めます。アクション パッケージは、アシスタントのレスポンスの形式を定義します。Actions SDK とは異なり、カスタム デバイス アクションはローカルで実行されます。リクエストを処理してレスポンスを提供するエンドポイントは指定しません。カスタム デバイス アクションは、本質的に会話型ではありません。
アクション パッケージを作成する
例として、LED の点滅のテストコマンドを定義するファイル(actions.json
など)を作成します。 前のステップでダウンロードしたサンプルコードからファイルをコピーします。
cd assistant-sdk-python/google-assistant-sdk/googlesamples/assistant/library/
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"
]
}
]
}
]
}
上記の例では、次の情報を使用してカスタム デバイス アクションを定義しています。
- ユーザークエリに対して照合するパターン(blink N 回)
- 整理のために、一致したクエリ(
com.example.actions.BlinkLight
)に関連付けるカスタム デバイス アクション - デバイスがアクションをサポートしている場合にユーザーにテキストが読み上げられる(Blinking N 回)
- デバイスに返送されるコマンド名(
com.example.commands.BlinkLight
)と、パラメータ(数値と速度の説明を含む)
クエリパターンを定義する際は、次の点に注意してください。
- クエリパターンでは schema.org で定義されているタイプを使用できます。
types [...]
配列は、カスタムタイプのリストを定義します(例:$Speed
)。- クエリパターンではカスタム型を使用できます。ユーザーは、クエリパターンに一致するために、カスタムタイプの任意の類義語を発話できます。
- 同義語が一致する場合、タイプ インスタンス(
speed
)は正規化されたキー(SLOWLY
)を返します。たとえば、異なる点滅速度をサポートする異なるライトがある場合、複数のエンティティを使用できます。 - リクエストの TTS パターンの一部は省略可能にできます。たとえば、クエリパターンで
($Speed:speed)?
を使用して、この部分をオプションにします。 - レスポンス TTS の
$type.raw
($speed.raw
など)は、ユーザーが実際に話した単語に置き換えられます。
これらのフィールドの詳細については、ActionPackage のドキュメントをご覧ください。
アクション パッケージをデプロイする
カスタム デバイス アクションをアクション パッケージでビルドすると、そのアクション パッケージをアシスタントからアクセスできるようになります。
このセクションの手順はデバイスでも行うことができますが、開発システムで行う方が簡単な場合があります。次のコマンドは仮想環境を必要としません。
gactions
コマンドライン ツールをダウンロードします。gactions
ツールと同じディレクトリから既存の認証情報を削除します。rm creds.data
gactions
CLI を使用して、アクション パッケージを Google に保存します。project_id
は、Actions Console のプロジェクト ID に置き換えます。./gactions update --action_package actions.json --project project_id
このコマンドを初めて実行すると、URL が表示され、ログインを求められます。URL をコピーしてブラウザに貼り付けます(これはどのシステムでも行うことができます)。 このページで、Google アカウントへのログインを求められます。前の ステップでプロジェクトを作成した 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 を使用して、アクション パッケージをテストモードにデプロイします。このコマンドを実行する前に、少なくとも 1 回、アクション パッケージを Google に保存する必要があります。テストモードでは、ユーザー アカウントでのみアクション パッケージが有効になります。./gactions test --action_package actions.json --project project_id
現時点では、アクション シミュレータを使用してこのプロジェクトをテストすることはできません。
アクション パッケージを更新するには、
gactions update
コマンドを使用します。(省略可)ローカライズされたアクション パッケージを作成すると、1 つのプロジェクトで同時にさまざまな言語とロケールをサポートできます。
サンプルを変更する
このセクションの手順はデバイスで行います。
nano hotword.py
カスタム アクション用のハンドラを追加します。上記のサンプル アクション パッケージを使用する場合は、以下のハンドラを使用できます。
import time # Add this to the imports near the top of the file ... if event.type == EventType.ON_DEVICE_ACTION: for command, params in event.actions: print('Do command', command, 'with params', str(params)) # Add the following lines after the existing line above: if command == "com.example.commands.BlinkLight": number = int( params['number'] ) for i in range(int(number)): print('Device is blinking.') # GPIO.output(25, 1) time.sleep(1) # GPIO.output(25, 0) time.sleep(1)
サンプルの実行
変更したソースコードを実行します。
python hotword.py --device-model-id my-model
クエリを試します。上記の例の場合、次のクエリを試してみます。
OK Google, 5 回点滅して。
使用するクエリは、アクション パッケージで指定したクエリパターンと一致する必要があります。