Alexa.LockControllerインターフェース

Alexa.LockControllerインターフェース

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

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

発話

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

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

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

プロパティ

lockStateプロパティ

Alexa.LockControllerインターフェースは、lockStateプロパティを使用してロックの状態を表します。lockStateの有効な値は次のとおりです。

値 説明
LOCKED デバイスは現在ロックされています。
UNLOCKED 現在、デバイスのロックは解除されています。
JAMMED ロック機構で不具合が発生したため、ロックがロック状態またはロック解除状態に遷移できません。

LockStateプロパティの例

{
"name": "lockState",
"value": "LOCKED"
}

検出

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

Alexaからスキルに状態レポートリクエストが送信されるときにレポートするすべてのインターフェースとプロパティのretrievableをtrueに設定します。変更レポートでAlexaにプロアクティブにレポートするインターフェースとプロパティのproactivelyReportedをtrueに設定します。

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

応答例

以下は、Alexa.PercentageControllerインターフェースをサポートする1つのエンドポイントへのAlexa.LockControllerメッセージの例です。

{
  "event": {
    "header": {
      "namespace": "Alexa.Discovery",
      "name": "Discover.Response",
      "payloadVersion": "3",
      "messageId": "<メッセージID>"
    },
    "payload": {
      "endpoints":[
        {
          "endpointId": "<エンドポイントの一意のID>",
          "manufacturerName": "<エンドポイントのメーカー名>",
          "description": "<Alexaアプリに表示される説明>",
          "friendlyName": "<Alexaアプリに表示されているデバイス名（例：玄関）>",
          "displayCategories": ["SMARTLOCK"],
          "cookie": {},
          "capabilities": [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.LockController",
              "version": "3",
              "properties": {
                "supported": [
                  {
                    "name": "lockState"
                  }
                ],
                "proactivelyReported": true,
                "retrievable": true
              }
            },
            {
              "type": "AlexaInterface",
              "interface": "Alexa",
              "version": "3"
            }
          ]
        }
      ]
    }
  }
}

ディレクティブ

Lockディレクティブ

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

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

アレクサ、玄関に鍵をかけて。

Lockディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {}
  }
}

Lock応答イベント

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

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

いずれの場合も、Responseイベントを同期的または非同期的に送信できます。Responseを非同期で送信する場合、相関トークンと、認可トークンを含めたスコープを含めます。

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

低速ロックの例：遅延応答と応答

次の例では、完了に5秒以上かかるLockディレクティブに対する2つの応答を示します。最初に同期のDeferredResponse</code>を送信します。オプションで、2番目の応答を送信する前のおおよその時間であるestimatedDeferralInSeconds（単位：秒）を含めます。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 15
    }
  }
}

次に、Responseイベントを送信します。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "LOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

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

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

Unlockディレクティブ

エンドポイントのロック解除をユーザーがリクエストできるように、Unlockディレクティブをサポートします。デフォルトでは、デバイスのロックを解除できません。ロック可能なエンドポイントスキルをテストする場合は、Alexaアプリでデバイスを編集することで、まずロック解除機能を有効にします。

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

アレクサ、玄関の鍵を開けて。

Unlockディレクティブの例

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>",
      "cookie": {}
    },
    "payload": {}
  }
}

Unlock応答イベント

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

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

いずれの場合も、Responseイベントを同期的または非同期的に送信できます。

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

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

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

低速アンロックの例：遅延応答と応答

次の例では、完了に5秒以上かかるunlockディレクティブに対する2つの応答を示します。最初に同期のDeferredResponse</code>を送信します。オプションで、2番目の応答を送信する前のおおよその時間であるestimatedDeferralInSeconds（単位：秒）を含めます。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

次に、Responseイベントを送信します。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "Response",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

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

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

状態レポート

Alexaはエンドポイントの状態についての情報をリクエストするためにReportStateディレクティブを送信します。AlexaがReportStateディレクティブを送信したら、それに対する応答としてStateReportイベントを送信します。この応答には、contextオブジェクトのすべてのretrievableプロパティの現在の状態を含めます。retrievableプロパティは検出応答で特定します。状態レポートの詳細については、状態レポートについてを参照してください。

StateReport応答イベントの例

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "StateReport",
      "messageId": "<メッセージID>",
      "correlationToken": "<opaque相関トークン>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {}
  },
  "context": {
    "properties": [
      {
        "namespace": "Alexa.LockController",
        "name": "lockState",
        "value": "UNLOCKED",
        "timeOfSample": "2017-02-03T16:20:50Z",
        "uncertaintyInMilliseconds": 1000
      }
    ]
  }
}

変更レポート

エンドポイントの状態の変化をプロアクティブにレポートするために、ChangeReportイベントを送信します。プロアクティブにレポートするプロパティは検出応答で特定します。変更レポートの詳細については、スマートホームスキルの状態レポートについてを参照してください。

ChangeReportイベントの例

{  
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "ChangeReport",
      "messageId": "<メッセージID>",
      "payloadVersion": "3"
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "<OAuth2ベアラートークン>"
      },
      "endpointId": "<エンドポイントID>"
    },
    "payload": {
      "change": {
        "cause": {
          "type": "PHYSICAL_INTERACTION"
        },
        "properties": [
          {
            "namespace": "Alexa.LockController",
            "name": "lockState",
            "value": "LOCKED",
            "timeOfSample": "2017-02-03T16:20:50Z",
            "uncertaintyInMilliseconds": 1000
          }
        ]
      }
    }
  },
  "context": {}
}
このページは役に立ちましたか？

最終更新日: 2021 年 08 月 10 日