スマートホームスキルにシーンを追加する



スマートホームスキルにシーンを追加する

シーン機能を使用することで、ユーザーは音声を使って、定義済みの設定を複数のデバイスに適用できます。たとえば、「アレクサ、就寝をオンにして」と言うと、部屋の照明を暗くして温度を下げるといったことができます。シーンは通常、Alexaと互換性のあるハブやデバイスメーカーのアプリを使用してユーザーが変更または作成すると、Alexa搭載デバイスで検出できるようになります。

シーンをサポートするスキルを提供する方法は、他のコネクテッドデバイス向けのスマートホームスキルと似ていますが、スキルアダプターにいくつかの特殊な要件があります。スマートホームスキルのシーン機能を有効にするには、スキルアダプターコードが以下の要件を満たしている必要があります。

  • 使用できるデバイスの設定に影響するシーンのみ検出を有効にすること
  • 検出の応答に含まれる特定のプロパティが、シーン向けの適切な形式になっていること
  • 検出プロセスで提示するシーンが12種類以下であること

前提条件

スマートホームスキルを作成したことがない場合は、このドキュメントを読み進める前に、関連する既存のドキュメントを確認してください。

シーンの検出と使用できるデバイス

シーンの検出を有効にする方法は、デバイスの検出と同じです。ただし、検出を有効にするのは、ユーザーにセキュリティ上または安全上のリスクを与えることのないデバイスを使ったシーンのみに限定する必要があります。つまり、使用できないデバイスがシーンに使われている場合は、そのシーンが検出の応答に含まれないようにします。

使用できるデバイスとできないデバイスは以下のとおりです。

使用できるデバイス

以下の種類のデバイスは、シーンの一部として組み込むことが可能です。

  • 送風機
  • 電球
  • スピーカー
  • スイッチ付き電源コンセント
  • サーモスタット
  • ブラインド

使用できないデバイス

セキュリティ上または安全上の懸念があるデバイスは使用できません。使用できないデバイスの例は以下のとおりです。スマートホームスキルで、使用できないデバイスに影響を与えるシーンの検出が可能と判断された場合、そのスキルは認定されません。

  • カメラ
  • 調理器具
  • ドアロック
  • ガレージのドア
  • セキュリティセンサー
  • セキュリティシステム

さらに、ユーザーが検出されたシーンに使用できないデバイスを追加して、シーンの操作を試みた場合は、スキルによってエラーが返されるようにする必要があります。たとえば、ユーザーが就寝シーンにドアロックを追加し、「アレクサ、就寝をオンにして」と言った場合、スキルアダプターはエラーを返す必要があります。

シーンを記述するためのDiscoveryResponseの要件

Alexaから送信される検出リクエストに対して、デバイスを記述する場合と同様に、Discover.Responseイベントにシーンをエンドポイントとして記述します。ただし、シーンの場合、一部の応答プロパティに特殊な要件が適用されます。

  • displayCategoriesの配列にSCENE_TRIGGERまたはACTIVITY_TRIGGERを含めることで、エンドポイントがシーンであることを示す必要があります

  • descriptionに「scene」という単語とシーンの接続手段を含める必要があります。たとえば、「ベンダー名で接続されたscene」のように指定します。この説明は128文字以内で記述します。

  • friendlyNameは、ユーザーがシーンを操作するときに使用する名前で、必ず指定する必要があります。この名前の目的は、ユーザーが自然に、かつ簡単にシーンを操作できるようにすることです。friendlyNameは、以下のガイドラインに従って指定する必要があります。

    • シーン名のみを使用することが推奨されます。ユーザーは最も自然に、かつ簡単にシーンを操作できるからです
    • 別の部屋で類似したシーンが提供されている場合は、部屋の名前を含めることができます
    • 「シーン」を含めることができます
    • 部屋の名前とシーンの名前との間に「の」を含めることができます
    • 特殊文字や句読点は使用しません
    • 128文字以内で指定します

次の表に、フレンドリー名の例と、ユーザーがシーンを有効にするときに使用する発話の例を示します。

フレンドリー名の形式 フレンドリー名の例 ユーザーの発話
シーン名就寝「アレクサ、就寝をオンにして」
シーン名 + シーン就寝シーン「アレクサ、就寝シーンをオンにして」
部屋の名前 + の + シーンの名前子ども部屋就寝「アレクサ、子ども部屋の就寝をオンにして」
  • capabilitiesの配列に、SceneController機能が含まれている必要があります。
  • 有効化は必ず設定する必要があり、このインターフェースを指定している場合は、自動的に有効になっていることになります。
  • 無効化の設定は、supportsDeactivationフィールドで指定します。無効化ディレクティブを処理する場合は、trueにします。

シーンが含まれるDiscover.Response

Discover.Responseは、ユーザーのデバイス制御クラウドアカウントに関連付けられたすべてのデバイス、またはシーンを返すイベントで、Discoverディレクティブに対して使用されることが想定されます。応答のプロパティの詳細については、Discover.Responseを参照してください。

以下のコードは、シーンが含まれるスキルからのDiscovery.Responseの例です。

{
  "event": {
    "header": {
      "namespace":"Alexa.Discovery",
      "name":"Discover.Response",
      "payloadVersion":"3",
      "messageId":"ff746d98-ab02-4c9e-9d0d-b44711658414"
    },
    "payload":{
      "endpoints":[
        {
          "endpointId": "uniqueIdOfScene",
          "manufacturerName": "エンドポイントのメーカー名",
          "friendlyName": "TV視聴",
          "description": "MyVendorから接続されたTV scene",
          "displayCategories": [ "ACTIVITY_TRIGGER" ],
          "cookie": {
          },
          "capabilities":
          [
            {
              "type": "AlexaInterface",
              "interface": "Alexa.SceneController",
             "version" : "3",
              "supportsDeactivation" : false,
              "proactivelyReported" : true
            }
          ]
        }
      ]
    }
  }
}

シーン検出の制限

検出が完了すると、スキルが検出プロセスで提供するすべてのデバイスやシーンがAlexaアプリに表示されます。ユーザーの操作性が損なわれないよう、Discover.Responseで記述するデフォルトのシーンの上限は12個となっています。ユーザーはカスタムシーンをいくつでも設定できます。

シーンの有効化リクエスト

シーンは有効化に対応している必要があります。つまり、スキルがActivateディレクティブを処理し、ActivationStartedイベントで応答するか、リクエストを完了できなかった場合はエラーメッセージで応答できるようになっていなければなりません。

サンプル発話：

「アレクサ、テレビ視聴を有効にして」

シーンのActivateの例：

{
  "directive": {
    "header": {
      "namespace": "Alexa.SceneController",
      "name": "Activate",
      "messageId": "1bd5d003-31b9-476f-ad03-71d471922820",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-skill"
      },
      "endpointId": "uniqueIdOfScene"
    },
    "payload": {
    }
  }
}

ActivationStartedの例

{
  "context" : { },
  "event": {
    "header": {
      "messageId": "8d9c4fa2-9de0-4e75-ac38-9dde79abb1bd",
      "correlationToken": "dFMb0z+PgpgdDmluhJ1LddFvSqZ/jCc8ptlAKulUj90jSqg==",
      "namespace": "Alexa.SceneController",
      "name": "ActivationStarted",
      "payloadVersion": "3"
    },
     "endpoint": {
      "scope": {
        "type": "BearerToken",
        "token": "access-token-from-Amazon"
      },
      "endpointId": "appliance-001"
    },
    "payload": {
      "cause" : {
        "type" : "VOICE_INTERACTION"
      },
      "timestamp" : "2017-02-03T23:23:23.23Z"
    }
  }
}

その他のドキュメント

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment