Alexa.LockControllerインターフェース



Alexa.LockControllerインターフェース

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

ディレクティブ

このインターフェースの制御とクエリーのディレクティブは、以下の言語のスキルで使用できます。

  • 英語(オーストラリア)
  • 英語(カナダ)
  • 英語(英国)
  • 英語(米国)
  • ドイツ語
  • イタリア語
  • 日本語
  • スペイン語(スペイン)

詳細については、スマートホームスキルを複数の言語で開発するを参照してください。

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": {}
  }
}

ペイロードの詳細

フィールド 説明 必須
なし ペイロードに必須または任意のフィールドはありません。 なし なし

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": {}
  }
}

ペイロードの詳細

フィールド 説明 必須
なし ペイロードに必須または任意のフィールドはありません。 なし なし

プロパティとイベント

この機能では、次のいずれかの方法で応答する必要があります。

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

Responseを送信する場合、メッセージのcontextにインターフェースのプロパティの状態を含める必要があります。

LockまたはUnlockディレクティブに応答する方法を決める際には、ハードウェアデバイスがどのくらいの速度でリクエストを完了できるかについても検討する必要があります。ハードウェアが高速の場合、ロックの状態がロック解除またはロック済みに変わったことを表すResponseイベントで応答することができます。現時点では、リクエストを5秒以内に完了できれば高速ロックと見なされます。

低速ハードウェアの場合、estimatedDeferralInSecondsを指定してAlexa.DeferredResponseを送信します。その後、アクション完了時にResponseをAlexaのイベントゲートウェイに送信する必要があります。リクエストと一緒に送信される相関トークンをこれら2つのメッセージの両方に含めます。このメッセージフローを使用することで、Alexaはユーザーに適切に応答できます。

プロパティ

プロパティ名 説明
lockState LockState デバイスの現在のロック状態を表します。次の文字列値がサポートされます。 「LOCKED」、「UNLOCKED」、「JAMMED」のいずれかです。

DeferredResponse

低速ロックの場合:

  • DeferredResponseイベントを送信し、指定したestimatedDeferralInSecondsでリクエストが進行中であることを表します。
  • 続いて、AlexaイベントゲートウェイにResponseイベントを送信します。このイベントには、リクエスト完了後のlockStateプロパティの新しい値(LOCKEDJAMMEDなど)を表すcontextオブジェクトを含める必要があります。

どちらのイベントにも、リクエストからの相関トークンが含まれている必要があります。

低速ハードウェアのAlexa.DeferredResponseの例:

以下は、低速ロックの遅延応答イベントの例です。

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

低速ハードウェアの応答の例:

以下は、低速ロックへのロックリクエストに対する応答イベントの例です。このイベントには、元のリクエストからの相関トークンが含まれている必要があり、lockStateプロパティの値を提供します。

{
  "context": {
    "properties": [
          {
            "namespace": "Alexa.LockController",
            "name": "lockState",
            "value": "LOCKED",
            "timeOfSample": "2017-02-03T16:20:50.52Z",
            "uncertaintyInMilliseconds": 0
          }
     ]
  },
  "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": {
    }
  }
}

応答

ロックまたはロック解除アクションを通常5秒以内に完了するロックの場合は、Responseを同期的に返します。

応答の例:

以下は、5秒未満で完了したロックリクエストに対する応答の例です。

{
  "context": {
    "properties": [ {
      "namespace": "Alexa.LockController",
      "name": "lockState",
      "value": "LOCKED",
      "timeOfSample": "2017-02-03T16:20:50.52Z",
      "uncertaintyInMilliseconds": 1000
    } ]
  },
  "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": {}
  }
}

ErrorResponse

何らかの理由によりユーザーのリクエストを完了できない場合、エラー応答を返す必要があります。詳細については、Alexa.ErrorResponseを参照してください。

その他のサンプルコード

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

LockController