Alexa.SecurityPanelController.Alertインターフェース1.1
AlexaスキルにAlexa.SecurityPanelController.Alertインターフェースを実装すると、ユーザーはAlexa搭載デバイスからのサウンドで、セキュリティシステムのエンドポイントを強化できます。スキルがチャープ音やサイレンなどのセキュリティアラートを出力し、Alexaが対応するサウンドを再生します。ユーザーは、Alexaアプリで各セキュリティアラートを有効または無効にできます。
セキュリティパネルが大規模なセキュリティシステムの一部である場合、スキルは、Alexa.ContactSensor、Alexa.MotionSensor、Alexa.SecurityPanelControllerのインターフェースを実装することもできます。
Alexa.SecurityPanelController.Alertインターフェースがサポートする言語については、Alexaインターフェースとサポートしている言語の一覧を参照してください。Alexaメッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。メッセージプロパティの定義については、Alexaインターフェースのメッセージとプロパティを参照してください。
サポートされるアラート
Alexa.SecurityPanelController.Alertインターフェースは、セキュリティシステムサウンドを再現する以下のアラートをサポートします。
- サイレン – セキュリティシステムがアラームを鳴らすと再生されます。Alexaは、オプションで繰り返し再生の間隔を指定すると、オーディオクリップを複数回ループ再生できます。最大再生時間は10分です。
- 入室遅延アラート – ユーザーにサイレンが鳴る前にシステムを解除するよう知らせるリマインダーチャープ音です。最大再生時間は、セキュリティシステムの遅延時間と同じに設定する必要があります。
- 退室遅延アラート – ユーザーにシステムが作動開始する前に退出するよう知らせるリマインダーチャープ音です。最大再生時間は、セキュリティシステムの遅延時間と同じに設定する必要があります。
- チャイム – 接触センサーなどのセンサーがトリガーする聞き取り可能なトーン音です。このサウンドが最もよく再生されるのは、窓やドアが開いたときです。Alexaは、ほかのサウンドが再生されていない場合にこのトーン音を再生します。チャイムの再生時間は1秒で、5秒後に期限が切れます。
スキルが複数のアラートを出力した場合、Alexaは、サイレン、入室遅延アラート、退室遅延アラート、チャイムの優先順位で再生します。
発話
Alexa.SecurityPanelController.Alertインターフェースには発話は定義されません。ただし、スキルがAlexa.SecurityPanelControllerインターフェースとAlexa.SecurityPanelController.Alertインターフェースをサポートしている場合、スキルは、ユーザーがAlexa.SecurityPanelControllerプリビルド音声対話モデルを使ってセキュリティシステムを作動開始または解除したときに、Alexa.SecurityPanelController.Alertイベントを送信します。
以下に、ユーザー発話の例を示します。
Alexa, arm my home.
Alexa starts playing the exit delay sound.
Alexa, disarm my home.
Alexa stops playing the siren or entry delay sound.
Alexa, arme ma maison.
Alexa stops playing the exit delay sound.
Alexa, désarme ma maison.
Alexa stops playing the siren or entry delay sound.
Alexa, stelle mein Haus scharf.
Alexa stops playing the exit delay sound.
Alexa, entschärfe mein Zuhause.
Alexa stops playing the siren or entry delay sound.
Alexa, arma la mia casa.
Alexa stops playing the exit delay sound.
Alexa, disarma la mia casa.
Alexa stops playing the siren or entry delay sound.
アレクサ、警備を開始して
Alexaは退室遅延サウンドの再生を停止します。
アレクサ、警備を解除して
Alexaはサイレンまたは入室遅延サウンドの再生を停止します。
Alexa, arma minha casa.
Alexa stops playing the exit delay sound.
Alexa, desarme minha casa.
Alexa stops playing the siren or entry delay sound.
Alexa, arma mi casa.
Alexa stops playing the exit delay sound.
Alexa, desarma mi casa.
Alexa stops playing the siren or entry delay sound.
プロパティとオブジェクト
Alexa.SecurityPanelController.Alertインターフェースには、次のプロパティとオブジェクトが含まれます。
出力可能なプロパティ
Alexa.SecurityPanelController.Alertインターフェースは、出力可能なプロパティとして、sirenState、入室と退室のdelayStateを定義します。検出応答で、サポートする一方または両方のプロパティを指定します。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
入室および退室の遅延と、関連するプレイリストを定義します。サイレンが再生中でない場合、Alexaは入室および退室の遅延アラートを再生します。 |
オブジェクト |
✕ |
|
|
エンドポイントの現在の遅延状態を示します。状態が |
文字列 |
◯ |
|
|
遅延サウンドの再生時間を秒で指定します。セキュリティシステムの入室または退室遅延時間と同じ値を設定してください。 |
整数 |
✕ |
|
|
アラートの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。 |
文字列 |
✕ |
|
|
オーディオアラートの順序付きリストです。 |
|
✕ |
|
|
サイレン状態と関連するプレイリストを定義します。サイレンアラートは、遅延アラートよりも優先されます。 |
オブジェクト |
✕ |
|
|
エンドポイントの現在のサイレン状態を示します。状態が |
文字列 |
◯ |
|
|
アラートの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。 |
文字列 |
✕ |
|
|
オーディオアラートの順序付きリストです。 |
|
✕ |
PlaylistItemオブジェクト
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
再生するオーディオを指定します。オーディオアセットは、検出応答の |
文字列 |
◯ |
|
|
オーディオアセットを再生する回数です。デフォルトは1回です。 |
整数 |
✕ |
|
|
複数回のループ回数を指定する場合、 |
整数 |
✕ |
検出
Alexa.SecurityPanelController.Alertをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。
Alexaからスキルに状態レポートリクエストが送信されたら、レポートするプロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするプロパティのproactivelyReportedをtrueに設定します。
SECURITY_PANEL、MOTION_SENSOR、SMARTLOCK、その他適切な表示カテゴリーを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。
Alexaにデバイスの健全性を通知する場合、Alexa.EndpointHealthインターフェースも実装してください。
configurationオブジェクト
機能配列のAlexa.SecurityPanelController.Alertエントリには、通常の検出応答フィールドのほかに、次のフィールドを持つconfigurationオブジェクトを含めます。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
ユーザーに再生するオーディオのリストです。 |
オブジェクトの配列 |
◯ |
|
|
オーディオの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。 |
文字列 |
◯ |
|
|
オーディオファイルの場所です。オーディオファイルは、インターネットにアクセス可能なポート443のHTTPSエンドポイント側でホスティングする必要があります。URLが壊れている場合、Alexaはオーディオを再生しません。 |
文字列 |
◯ |
|
|
再生するオーディオアラートのリストです。 |
オブジェクトの配列 |
◯ |
|
|
プレイリストの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。 |
文字列 |
✕ |
|
|
オーディオアラートの順序付きリストです。 |
|
✕ |
|
|
エンドポイントがサポートするオーディオアラートのリストです。ユーザーはAlexaアプリでこれらのアラートを確認し、各アラートの有効／無効を選択することができます。Alexaは、 |
オブジェクトの配列 |
◯ |
|
|
アラートのタイプを識別します。
|
文字列 |
◯ |
|
|
Amazon Echoデバイスのプレイリストを識別する一意のIDです。 |
文字列 |
◯ |
検出応答の例
以下は、Alexa.SecurityPanelController.AlertインターフェースをサポートするセキュリティパネルへのAlexa.Discover.Responseメッセージの例です。
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "一意の識別子、バージョン4 UUIDが望ましい"
},
"payload": {
"endpoints": [{
"endpointId": "エンドポイントの一意のID",
"manufacturerName": "エンドポイントのメーカー名",
"description": "Alexaアプリに表示される説明",
"friendlyName": "Alexaアプリに表示されるセキュリティパネル名",
"displayCategories": ["SECURITY_PANEL"],
"additionalAttributes": {
"manufacturer": "エンドポイントのメーカー名",
"model": "デバイスのモデル",
"serialNumber": "デバイスのシリアル番号",
"firmwareVersion": "デバイスのファームウェアバージョン",
"softwareVersion": "デバイスのソフトウェアバージョン",
"customIdentifier": "デバイスのカスタム識別子"
},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.SecurityPanelController.Alert",
"version": "1.1",
"properties": {
"supported": [{
"name": "delayState"
},
{
"name": "sirenState"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"assets": [{
"id": "UUID.1",
"url": "https://example.com/url-of-the-stream-to-play.1.mp3"
},
{
"id": "UUID.2",
"url": "https://example.com/url-of-the-stream-to-play.2.mp3"
},
{
"id": "UUID.3",
"url": "https://example.com/url-of-the-stream-to-play.3.mp3"
}
],
"playlists": [{
"id": "UUID.entry.delay.1",
"playOrder": [{
"assetId": "UUID.1",
"loopCount": 10,
"loopPauseInMilliseconds": 1000
},
{
"assetId": "UUID.2",
"loopCount": 5,
"loopPauseInMilliseconds": 500
}
]
},
{
"id": "UUID.playlist-chime.1",
"playOrder": [{
"assetId": "UUID.1"
}]
},
{
"id": "UUID.playlist-siren.1",
"playOrder": [{
"assetId": "UUID.3"
}]
}
],
"alerts": [{
"type": "ENTRY_DELAY",
"defaultPlaylistId": "UUID.entry.delay.1"
},
{
"type": "EXIT_DELAY",
"defaultPlaylistId": "UUID.entry.delay.1"
},
{
"type": "SIREN",
"defaultPlaylistId": "UUID.playlist-siren.1"
},
{
"type": "CHIME",
"defaultPlaylistId": "UUID.playlist-chime.1"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.SecurityPanelController",
"version": "3",
"properties": {
"supported": [{
"name": "armState"
},
{
"name": "burglaryAlarm"
},
{
"name": "fireAlarm"
}
],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"supportedArmStates": [{
"value": "ARMED_AWAY"
},
{
"value": "ARMED_STAY"
},
{
"value": "DISARMED"
}
],
"supportedAuthorizationTypes": [{
"type": "FOUR_DIGIT_PIN"
}]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3.1",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}]
}]
}
}
}
ディレクティブとイベント
Alexa.SecurityPanelController.Alertインターフェースは、次のイベントを定義します。
Chimeイベント
Alexaに、チャイム、サイレン、入室／退室遅延などのセキュリティ関連イベントをプロアクティブに知らせるため、AlexaイベントゲートウェイにChimeイベントを送信します。詳細については、イベントゲートウェイにイベントを送信するを参照してください。セキュリティイベントが発生するとすぐにイベントを送信します。Alexaは、5秒以上前のイベントを無視します。
Chimeイベントの例
以下は、接触センサースキルがAlexaにチャイムアラートを再生するよう、Chimeイベントを送信している例です。
Chimeイベントのペイロード
次の表は、Chimeイベントのペイロードの詳細を示しています。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
プレイリストの一意のIDです。プレイリストは、検出応答の |
文字列 |
✕ |
|
|
オーディオアラートの順序付きリストです。 |
|
✕ |
|
|
イベントが発生した時間です。Alexaは、タイムスタンプに5秒以上前または未来の時間が指定されたChimeイベントを無視します。 |
文字列 |
◯ |
HTTPステータスコード
次の表は、スキルがAlexaイベントゲートウェイから受け取る可能性のあるHTTPステータスコードの一覧です。エラーを受け取った場合は、payloadオブジェクトにcodeフィールドとdescriptionフィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。
| ステータス | ペイロードのコード | 説明 |
|---|---|---|
|
|
— |
リクエストは認可され、メッセージは構文的に有効なイベントでした。ゲートウェイはイベントを受け付け、論理的な検証と処理に進みます。 |
|
|
|
メッセージが無効です。フィールドがない、値が正しくない、正しいJSON形式ではないことが原因です。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。 |
|
|
|
メッセージに認可トークンが含まれていないか、トークンが無効、有効期限切れ、形式が正しくないのいずれかです。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。この場合は、ユーザーが認可を取り消したため、変更レポートの送信も停止できます。 |
|
|
|
イベントゲートウェイへのアクセスが許可されていません。イベントを正しいリージョンのエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信します。 |
|
|
|
トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。 |
|
|
|
指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。 |
|
|
|
このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにある状況でユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。 |
|
|
|
イベントペイロードのサイズが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。 |
|
|
|
リクエスト数が多すぎます。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。 |
|
|
|
Alexaでエラーが発生したため、メッセージは処理されませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。 |
|
|
|
Alexaがメッセージを受け取れませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。 |
応答本文401 Unauthorizedの例
以下は、エラー応答の例です。
HTTP/1.1 400 Bad Request
Date: Wed, 07 Mar 2018 20:25:31 GMT
Connection: close
{
"header": {
"namespace": "System",
"name": "Exception",
"messageId": "90c3fc62-4b2d-460c-9c8b-77251f1698a0"
},
"payload": {
"code": "INVALID_ACCESS_TOKEN_EXCEPTION",
"description": "アクセストークンが無効、有効期限切れ、形式が正しくないのいずれかです。"
}
}
状態レポート
Alexaはエンドポイントの状態についての情報をリクエストするために、ReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態および変更レポートについてを参照してください。
StateReport応答の例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "StateReport",
"messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞",
"correlationToken": "＜リクエストに一致するopaque相関トークン＞",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2ベアラートークン"
},
"endpointId": "＜エンドポイントID＞"
},
"payload": {}
},
"context": {
"properties": [{
"namespace": "Alexa.SecurityPanelController.Alert",
"name": "delayState",
"value": {
"state": "EXIT_DELAY",
"playlistId": "UUID.entry.delay.1"
},
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.SecurityPanelController",
"name": "armState",
"value": "ARMED_AWAY",
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
変更レポート
エンドポイントの状態の変化をプロアクティブに出力するには、Alexa.ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、状態および変更レポートについてを参照してください。
delayStateプロパティとsirenStateプロパティの値を変更したら、ChangeReportを送信します。Alexaは、状態がONのときにサイレンアラートを再生し、状態がOFFのときにアラートを停止します。同様に、Alexaは、状態がENTRY_DELAY、EXIT_DELAYのいずれかの場合に遅延アラートを再生し、状態がNONEの場合にアラートを停止します。
ChangeReportイベントの例
{
"event": {
"header": {
"namespace": "Alexa",
"name": "ChangeReport",
"messageId": "＜一意の識別子、バージョン4 UUIDが望ましい＞",
"payloadVersion": "3"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2ベアラートークン"
},
"endpointId": "＜エンドポイントID＞"
},
"payload": {
"change": {
"cause": {
"type": "PHYSICAL_INTERACTION"
},
"properties": [{
"namespace": "Alexa.SecurityPanelController.Alert",
"name": "delayState",
"value": {
"state": "ENTRY_DELAY",
"playlistId": "UUID.entry.delay.1"
},
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
}]
}
}
},
"context": {
"properties": [{
"namespace": "Alexa.SecurityPanelController.Alert",
"name": "sirenState",
"value": {
"state": "OFF"
},
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
},
{
"namespace": "Alexa.EndpointHealth",
"name": "connectivity",
"value": {
"value": "OK"
},
"timeOfSample": "2023-05-01T23:23:23.23Z",
"uncertaintyInMilliseconds": 0
}
]
}
}
関連トピック
- Alexa.CameraStreamController
- Alexa.ContactSensor
- Alexa.DoorbellEventSource
- Alexa.LockController
- Alexa.MotionSensor
- Alexa.SecurityPanelController
最終更新日: 2024 年 07 月 03 日