Alexa.LockControllerインターフェース



Alexa.LockControllerインターフェース

Alexa.LockControllerインターフェースは、ロック可能なエンドポイントを制御するために使用するメッセージを記述しています。

LockControllerインターフェースでサポートされているロケールについては、機能インターフェースの一覧を参照してください。

発話

Alexa.LockControllerインターフェースを使用する場合、音声対話モデルは既にビルドされています。以下に、ユーザーの発話の例を示します。

アレクサ、玄関に鍵をかけて。
アレクサ、裏口の鍵を開けて。

ユーザーがこのような発話をしたら、Alexaがそれに対応するディレクティブをスキルに送信します。

検出

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

表示カテゴリーにはSMARTLOCKを使用します。表示カテゴリーの一覧は、表示カテゴリーを参照してください。

検出の例

{
    "event": {
        "header": {
            "namespace": "Alexa.Discovery",
            "name": "Discover.Response",
            "payloadVersion": "3",
            "messageId": "<メッセージID>"
        },
        "payload": {
            "endpoints":[
                {
                    "endpointId": "<エンドポイントの一意のID>",
                    "description": "サンプルメーカーのスマートロック",
                    "manufacturerName": "サンプルメーカー",
                    "friendlyName": "玄関ドア",
                    "displayCategories": ["SMARTLOCK"],
                    "cookie": {},
                    "capabilities": [
                      {
                        "type": "AlexaInterface",
                        "interface": "Alexa.LockController",
                        "version": "3",
                        "properties": {
                          "supported": [
                            {
                              "name": "lockState"
                            }
                          ],
                          "proactivelyReported": true,
                          "retrievable": true
                        }
                      },
                      {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [
                                {
                                    "name": "connectivity"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                      }
                    ]
                },
                {
                    "endpointId": "<エンドポイントの一意のID>",
                    "description": "サンプルメーカーのスマートロック",
                    "manufacturerName": "サンプルメーカー",
                    "friendlyName": "裏口",
                    "displayCategories": ["SMARTLOCK"],
                    "cookie": {},
                    "capabilities": [
                      {
                        "type": "AlexaInterface",
                        "interface": "Alexa.LockController",
                        "version": "3",
                        "properties": {
                          "supported": [
                            {
                              "name": "lockState"
                            }
                          ],
                          "proactivelyReported": true,
                          "retrievable": true
                        }
                      },
                      {
                        "type": "AlexaInterface",
                        "interface": "Alexa.EndpointHealth",
                        "version": "3",
                        "properties": {
                            "supported": [
                                {
                                    "name": "connectivity"
                                }
                            ],
                            "proactivelyReported": true,
                            "retrievable": true
                        }
                      }
                    ]
                }
            ]
        }
    }
}

ディレクティブ

Lockディレクティブ

エンドポイントのロックをユーザーがリクエストできるように、Lockディレクティブをサポートします。

以下は、ユーザーの発話の例です。

ユーザー: アレクサ、玄関に鍵をかけて。

Lockディレクティブペイロードの詳細

Lockディレクティブのペイロードは空です。

Lockディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Lock応答イベント

Lockディレクティブを正しく処理したら、ハードウェアでタスクを完了できる速度に応じて応答します。

ハードウェアが5秒以内にロックを完了できる場合は、Responseイベントを送信します。ハードウェアがロックを完了するまでに5秒よりも長くかかる場合は、DeferredResponseイベントを送信し、ロックが完了したときにResponseイベントを送信します。

次のいずれかの方法で応答できます。

  • 同期的に、Lambda関数からAlexaにResponseイベントを送信します。
  • 非同期的に、AlexaイベントゲートウェイにResponseイベントを送信します。非同期的に応答する場合、認可トークンにscopeを含めてユーザーを識別し、相関トークンを含めて応答先のディレクティブを識別する必要があります。

応答のコンテキストでlockStateプロパティの値を指定します。

高速ロックの応答イベントの例

次の例では、5秒以内に完了するLockディレクティブに対する応答を示します。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.LockController",
                "name": "lockState",
                "value": "LOCKED",
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    },
}

低速ロックのDeferredResponseイベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

低速ロックのResponseイベントの例

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {
        }
    },
    "context": {
      "properties": [
            {
              "namespace": "Alexa.LockController",
              "name": "lockState",
              "value": "LOCKED",
              "timeOfSample": "2017-02-03T16:20:50Z",
              "uncertaintyInMilliseconds": 0
            }
       ]
    },
}

Lockディレクティブのエラー処理

Lockディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

Unlockディレクティブ

エンドポイントのロック解除をユーザーがリクエストできるように、Unlockディレクティブをサポートします。

以下は、ユーザーの発話の例です。

ユーザー: アレクサ、玄関の鍵を開けて。

Unlockディレクティブペイロードの詳細

Unlockディレクティブのペイロードは空です。

Unlockディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "payloadVersion": "3",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

Unlock応答イベント

Unlockディレクティブを正しく処理したら、ハードウェアでタスクを完了できる速度に応じて応答します。

ハードウェアが5秒以内にロック解除を完了できる場合は、Responseイベントを送信します。ハードウェアがロック解除を完了するまでに5秒よりも長くかかる場合は、DeferredResponseイベントを送信し、ロック解除が完了したときにResponseイベントを送信します。

次のいずれかの方法で応答できます。

  • 同期的に、Lambda関数からAlexaにResponseイベントを送信します。
  • 非同期的に、AlexaイベントゲートウェイにResponseイベントを送信します。非同期的に応答する場合、認可トークンにscopeを含めてユーザーを識別し、相関トークンを含めて応答先のディレクティブを識別する必要があります。

応答のコンテキストでlockStateプロパティの値を指定します。

高速ロック解除の応答イベントの例

次の例では、5秒以内に完了するUnlockディレクティブに対する応答を示します。

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "payloadVersion": "3",
            "messageId": "abc-123-def-456",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {}
    },
    "context": {
        "properties": [
            {
                "namespace": "Alexa.LockController",
                "name": "lockState",
                "value": "UNLOCKED",
                "timeOfSample": "2017-02-03T16:20:50Z",
                "uncertaintyInMilliseconds": 1000
            }
        ]
    },
}

低速ロック解除のDeferredResponseイベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "abc-123-def-456",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

低速ロック解除のResponseイベントの例

{
    "event": {
        "header": {
            "namespace": "Alexa",
            "name": "Response",
            "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
            "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
            "payloadVersion": "3"
        },
        "endpoint": {
            "scope": {
                "type": "BearerToken",
                "token": "access-token-from-Amazon"
            },
            "endpointId": "appliance-001"
        },
        "payload": {
        }
    },
    "context": {
      "properties": [
            {
              "namespace": "Alexa.LockController",
              "name": "lockState",
              "value": "UNLOCKED",
              "timeOfSample": "2017-02-03T16:20:50Z",
              "uncertaintyInMilliseconds": 0
            }
       ]
    },
}

Unlockディレクティブのエラー処理

Unlockディレクティブを正しく処理できなかった場合は、Alexa.ErrorResponseイベントを使用して応答します。

その他のサンプルコード

リクエストと応答のサンプルについては、AlexaスマートホームのGitHubリポジトリで以下を参照してください。

LockController