Alexa.LockControllerインターフェース

Alexa.LockControllerインターフェース

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

ディレクティブ

このインターフェースの制御とクエリのディレクティブは、次の言語を対象とするスキルでサポートされています。

  • 英語(米国)
  • 英語(英国)
  • ドイツ語
  • 日本語

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

Lock

エンドポイントのロックを要求します。

「Alexa、endpoint nameをロックして」

リクエストの例:


{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Lock",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

ペイロードの詳細

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

Unlock

エンドポイントのロック解除を要求します。

「Alexa、endpoint nameのロックを解除して」

リクエストの例:

{
  "directive": {
    "header": {
      "namespace": "Alexa.LockController",
      "name": "Unlock",
      "payloadVersion": "3",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "some-access-token"
      },
      "endpointId": "appliance-001",
      "cookie": {}
    },
    "payload": {}
  }
}

ペイロードの詳細

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

プロパティとイベント

このインターフェースでは、次のいずれかの応答を使用する必要があります。

  • 同期的。つまり、Lambda関数からAlexaにResponseイベントを送信します。
  • 非同期的。つまり、AlexaイベントゲートウェイにResponseイベントを送信します。非同期応答の際には、ユーザーを識別する認可を受けたトークンを含むscope要素と、応答するディレクティブを識別する correlation トークンが必要になります。

Responseを送信するときには、メッセージのcontextにレポート可能なプロパティの状態を含める必要があります。

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

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

レポート可能なプロパティ

プロパティ名 説明
lockState LockState デバイスの現在のロック状態を示します。「LOCKED」、「UNLOCKED」、または「JAMMED」などのサポートされている値が入った文字列。

DeferredResponse

低速ロックの場合:

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

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

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

以下の例は、低速ロックの遅延応答イベントを示しています。

{
  "event": {
    "header": {
      "namespace": "Alexa",
      "name": "DeferredResponse",
      "messageId": "30d2cd1a-ce4f-4542-aa5e-04bd0a6492d5",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
    "payload": {
      "estimatedDeferralInSeconds": 20
    }
  }
}

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

以下の例は、低速ロックのロックリクエストの応答イベントを示しています。このイベントには、オリジナルのリクエストからのcorrelationトークンが含まれている必要があり、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": "Alexa-access-token"
      },
      "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": "5f8a426e-01e4-4cc9-8b79-65f8bd0fd8a4",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg=="
    },
    "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "Alexa-access-token"
      },
      "endpointId": "appliance-001"
    },
    "payload": {}
  }
}

ErrorResponse

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

追加のサンプルコード

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

LockController