Alexa.SecurityPanelController.Alertインターフェース1.1


Alexa.SecurityPanelController.Alertインターフェース1.1

AlexaスキルにAlexa.SecurityPanelController.Alertインターフェースを実装すると、ユーザーはAlexa搭載デバイスからのサウンドで、セキュリティシステムのエンドポイントを強化できます。スキルがチャープ音やサイレンなどのセキュリティアラートを出力し、Alexaが対応するサウンドを再生します。ユーザーは、Alexaアプリで各セキュリティアラートを有効または無効にできます。

セキュリティパネルが大規模なセキュリティシステムの一部である場合、スキルは、Alexa.ContactSensorAlexa.MotionSensorAlexa.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を定義します。検出応答で、サポートする一方または両方のプロパティを指定します。

プロパティ 説明 必須

delayState

入室および退室の遅延と、関連するプレイリストを定義します。サイレンが再生中でない場合、Alexaは入室および退室の遅延アラートを再生します。

オブジェクト

delayState.state

エンドポイントの現在の遅延状態を示します。状態がENTRY_DELAYEXIT_DELAYのいずれかの場合、Alexaは関連する遅延アラートを再生します。状態がNONEの場合、Alexaは遅延サウンドをキャンセルまたは停止します。
有効な値: ENTRY_DELAYEXIT_DELAYNONE

文字列

delayState.delayInSeconds

遅延サウンドの再生時間を秒で指定します。セキュリティシステムの入室または退室遅延時間と同じ値を設定してください。delayState.stateENTRY_DELAYEXIT_DELAYのいずれかの場合に指定します。
Amazonでは、遅延時間を30秒以上に設定することを推奨しています。
有効な値: 0~300。

整数

delayState.playlistId

アラートの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。
delayState.playOrderを指定している場合、Alexaはこのプロパティを無視します。delayState.playlistIddelayState.playOrderがいずれも指定されていない場合、Alexaは、検出応答alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。

文字列

delayState.playOrder

オーディオアラートの順序付きリストです。
delayState.playlistIddelayState.playOrderがいずれも指定されていない場合、Alexaは、検出応答alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。

PlaylistItemオブジェクトの配列

sirenState

サイレン状態と関連するプレイリストを定義します。サイレンアラートは、遅延アラートよりも優先されます。

オブジェクト

sirenState.state

エンドポイントの現在のサイレン状態を示します。状態がONの場合、Alexaは関連するサイレンアラートを再生します。状態がOFFの場合、Alexaはサイレンサウンドをキャンセルまたは停止します。
有効な値: ONOFF

文字列

sirenState.playlistId

アラートの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。
sirenState.playOrderを指定している場合、Alexaはこのプロパティを無視します。sirenState.playlistIdsirenState.playOrderがいずれも指定されていない場合、Alexaは、検出応答alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。
有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。

文字列

sirenState.playOrder

オーディオアラートの順序付きリストです。
sirenState.playlistIdsirenState.playOrderがいずれも指定されていない場合、Alexaは、検出応答alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。

PlaylistItemオブジェクトの配列

PlaylistItemオブジェクト

プロパティ 説明 必須

assetId

再生するオーディオを指定します。オーディオアセットは、検出応答Configurationオブジェクトで定義します。

文字列

loopCount

オーディオアセットを再生する回数です。デフォルトは1回です。

整数

loopPauseInMilliseconds

複数回のループ回数を指定する場合、loopPauseInMillisecondsには各ループの間隔をミリ秒で定義します。一時停止しない場合は、ゼロに設定します。デフォルトはゼロです。

整数

検出

Alexa.SecurityPanelController.Alertをサポートするエンドポイントは、Alexa.Discoveryの標準検出メカニズムを使用して表します。

Alexaからスキルに状態レポートリクエストが送信されたら、レポートするプロパティのretrievabletrueに設定します。変更レポートでAlexaにプロアクティブにレポートするプロパティのproactivelyReportedtrueに設定します。

SECURITY_PANELMOTION_SENSORSMARTLOCK、その他適切な表示カテゴリーを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

Alexaにデバイスの健全性を通知する場合、Alexa.EndpointHealthインターフェースも実装してください。

configurationオブジェクト

機能配列のAlexa.SecurityPanelController.Alertエントリには、通常の検出応答フィールドのほかに、次のフィールドを持つconfigurationオブジェクトを含めます。

プロパティ 説明 必須

assets

ユーザーに再生するオーディオのリストです。

オブジェクトの配列

assets[].id

オーディオの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。
有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。

文字列

assets[].url

オーディオファイルの場所です。オーディオファイルは、インターネットにアクセス可能なポート443のHTTPSエンドポイント側でホスティングする必要があります。URLが壊れている場合、Alexaはオーディオを再生しません。

文字列

playlists

再生するオーディオアラートのリストです。

オブジェクトの配列

playlists[].id

プレイリストの一意のIDです。Amazonでは、ランダム生成されたバージョン4のUUIDを使用することを推奨しています。
有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。

文字列

playlists[].playOrder

オーディオアラートの順序付きリストです。

PlaylistItemオブジェクトの配列

alerts

エンドポイントがサポートするオーディオアラートのリストです。ユーザーはAlexaアプリでこれらのアラートを確認し、各アラートの有効/無効を選択することができます。Alexaは、Chimeイベントを受信すると、これらのサウンドを再生します。

オブジェクトの配列

alerts[].type

アラートのタイプを識別します。
有効な値: CHIMESIRENENTRY_DELAYEXIT_DELAY

  • CHIME – 接触センサーなどのセンサーがトリガーする聞き取り可能なトーン音です。このサウンドが最もよく再生されるのは、窓やドアが開いたときです。Alexaは、ほかのサウンドが再生されていない場合にこのトーン音を再生します。再生時間を約1秒に設定します。
  • SIREN – 侵入者を検知した場合にトリガーされる、けたたましい大音量のアラームサウンドです。再生時間を10分以内に設定します。
  • ENTRY_DELAY – ユーザーにアラームが鳴る前にエンドポイントを解除するよう知らせるリマインダーチャープ音です。再生時間を約1分に設定します。
  • EXIT_DELAY – ユーザーにアラームが鳴る前にエンドポイントを作動開始するよう知らせるリマインダーチャープ音です。再生時間を約1分に設定します。

文字列

alerts[].defaultPlaylistId

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イベントのペイロードの詳細を示しています。

プロパティ 説明 必須

playlistId

プレイリストの一意のIDです。プレイリストは、検出応答Configurationオブジェクトで定義します。
playOrderを指定している場合、Alexaはこのプロパティを無視します。playlistIdplayOrderがいずれも指定されていない場合、Alexaは、alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。

文字列

playOrder

オーディオアラートの順序付きリストです。
playlistIdplayOrderがいずれも指定されていない場合、Alexaは、検出応答alertsオブジェクトで定義されたデフォルトのプレイリストを再生します。

PlaylistItemオブジェクトの配列

timestamp

イベントが発生した時間です。Alexaは、タイムスタンプに5秒以上前または未来の時間が指定されたChimeイベントを無視します。
ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。

文字列

HTTPステータスコード

次の表は、スキルがAlexaイベントゲートウェイから受け取る可能性のあるHTTPステータスコードの一覧です。エラーを受け取った場合は、payloadオブジェクトにcodeフィールドとdescriptionフィールドが含まれます。これらのフィールドはログ記録の目的でのみ使用してください。

ステータス ペイロードのコード 説明

202 Accepted

リクエストは認可され、メッセージは構文的に有効なイベントでした。ゲートウェイはイベントを受け付け、論理的な検証と処理に進みます。

400 Bad Request

INVALID_REQUEST_EXCEPTION

メッセージが無効です。フィールドがない、値が正しくない、正しいJSON形式ではないことが原因です。ドキュメントと照合して、メッセージにすべての必須フィールドが含まれていることを確認します。

401 Unauthorized

INVALID_ACCESS_TOKEN_EXCEPTION

メッセージに認可トークンが含まれていないか、トークンが無効、有効期限切れ、形式が正しくないのいずれかです。トークンを更新して、リクエストを再試行してください。ユーザーがスキルを無効にすると、アクセストークンも無効になります。この場合は、ユーザーが認可を取り消したため、変更レポートの送信も停止できます。

403 Forbidden

SKILL_NEVER_ENABLED_EXCEPTION

イベントゲートウェイへのアクセスが許可されていません。イベントを正しいリージョンのエンドポイントに送信していることを確認してください。たとえば、北米のイベントは北米のエンドポイントに送信します。

403 Forbidden

INSUFFICIENT_PERMISSION_EXCEPTION

トークンに必要な権限がありません。スキルにAlexaイベントを送信する権限があることを確認してください。詳細については、Alexaイベントゲートウェイへのアクセス権限のリクエストを参照してください。

404 Not Found

ACCOUNT_NOT_FOUND_EXCEPTION

指定されたIDに関連付けられたアカウントレコードが存在しないか、期限が切れています。このエラーは、イベントの送信が遅すぎた場合や、無効なIDが指定された場合に発生する可能性があります。指定されたIDと認可コードが正しいことを確認してください。

404 Not Found

SKILL_NOT_FOUND_EXCEPTION

このトークンに関連付けられたスキルIDが見つかりませんでした。このエラーは、スキルが認定中などの異なるステージにある状況でユーザーのアクセストークンが生成された場合に発生します。このユーザーでスキルの無効化と有効化を行ってみてください。

413 Payload Too Large

REQUEST_ENTITY_TOO_LARGE_EXCEPTION

イベントペイロードのサイズが大きすぎます。1回のリクエストで許容されるエンドポイントの最大数は300です。より小さいペイロードでメッセージを送信してください。

429 Too Many Requests

THROTTLING_EXCEPTION

リクエスト数が多すぎます。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。

500 Internal Server Error

INTERNAL_SERVICE_EXCEPTION

Alexaでエラーが発生したため、メッセージは処理されませんでした。メッセージを再送してください。ただし、再送は最大3回までで、再送の間隔は1秒以上空けてください。問題が解消されない場合、Alexa開発者向け問い合わせ窓口にお問い合わせください。

503 Service Unavailable

SERVICE_UNAVAILABLE_EXCEPTION

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_DELAYEXIT_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
            }
        ]
    }
}


このページは役に立ちましたか?

最終更新日: 2024 年 07 月 03 日