Alexa検出オブジェクト



Alexa検出オブジェクト

Alexa.Discoveryインターフェースには、ユーザーのデバイスアカウントに関連付けられたエンドポイントの特定に使用するメッセージが含まれます。Discover.Responseイベントを送信すると、スマートホームスキルに関連付けられたデバイスやシーンをユーザーが検出できるようになります。詳細についてはAlexa.Discoveryを参照してください。

以下は、検出メッセージでAlexaに送信するオブジェクトです。

endpointオブジェクト

endpointオブジェクトは、ユーザーのデバイス制御クラウドアカウントと関連付けられた、コネクテッドデバイス/コンポーネントを表します。エンドポイントには以下のいずれかの詳細が含まれます。

  • 物理デバイス
  • 仮想デバイス
  • デバイスのグループまたは集合(シーン内のデバイスなど)
  • ソフトウェアコンポーネント(モバイルアプリなど)

endpointオブジェクトの例

クリップボードにコピーされました。

{
  "endpointId": "<エンドポイントの一意のID>",
  "manufacturerName": "サンプルメーカー",
  "description": "サンプルメーカーのスマート照明",
  "friendlyName": "リビングの照明",
  "displayCategories": ["LIGHT"],
  "additionalAttributes":  {},
  "capabilities": [],
  "connections": [],
  "relationships": {},
  "cookie": {
    "extraDetail1": "スキルが使用する情報",
    "extraDetail2": "複数のエントリを作成できます",
    "extraDetail3": "ここにデバイスの状態を保存しないでください"
  }
}

endpointオブジェクトのスキーマ

フィールド 説明 必須
endpointId エンドポイントの識別子です。識別子は、スキルを使用するすべてのデバイスで一意である必要があります。同じデバイスのすべての検出リクエストに対して、識別子は常に同じである必要があります。識別子には、英数字、スペース、次の特殊文字を使用できます。使用可能な特殊文字:_ - = # ; : ? @ &。識別子は、256文字以内でなければなりません。 文字列
manufacturerName デバイスのメーカーの名前です。この値には最大128文字を含めることができます。 文字列
description デバイスの説明です。説明には、メーカー名やデバイスの接続方法を含める必要があります。たとえば、「サンプルメーカーのスマートロック」や、「SmartHubを介して接続するWi-Fiサーモスタット」などです。この値には最大128文字を含めることができます。 文字列
friendlyName デバイスを識別するためにユーザーが使用する名前です。この値には最大128文字を含めることができます。特殊文字や句読点は使用できません。一部の例外を除き、すべてのインターフェースに必須のフィールドです。このフィールドが任意かどうかを確認するには、各インターフェースのドキュメントを参照してください。 文字列
displayCategories Alexaアプリで、デバイスが表示されるカテゴリーです。 表示カテゴリーの文字列の配列
additionalAttributes エンドポイントについての追加情報です。Alexaアプリのユーザーエクスペリエンスが向上するため、このフィールドを含めることをお勧めします。 additionalAttributesオブジェクト
capabilities スキルがエンドポイントをサポートする機能インターフェースです。Alexa.BrightnessControllerAlexa.PowerControllerなどです。capabilitiesフィールドにはサイズ制限が適用されます。 capabilityオブジェクトの配列
connections デバイスがインターネットとスマートホームハブへの接続に使用する方法についての情報です。 connectionオブジェクトの配列
relationships エンドポイントが接続されているエンドポイントです。たとえば、コンピューターのエンドポイントはホームネットワークのエンドポイントに接続されている場合があります。 relationshipsオブジェクト
cookie スキルが使用するデバイスについての情報です。このプロパティのコンテンツは5,000バイト以内でなければなりません。APIではこのデータの読み取りや使用はしません。 名前と値のペアのリスト

additionalAttributesオブジェクト

additionalAttributesオブジェクトには、エンドポイントについての追加情報が含まれます。Alexaは、さまざまなスキルが同じデバイスを異なる方法で表している場合に、この情報を使用してデバイスを識別できます。

たとえば、さまざまなスキルが同じデバイスを異なる方法で表していると、Alexaアプリに同じデバイスが複数回表示され、ユーザーが混乱する原因となります。Alexaは、additionalAttributesオブジェクトを使用して重複するデバイスを識別し、Alexaアプリのユーザーエクスペリエンスを向上させることができます。

additionalAttributesオブジェクトの例

クリップボードにコピーされました。

{
  "additionalAttributes":  {
    "manufacturer" : "サンプルメーカー",
    "model" : "サンプルモデル",
    "serialNumber": "<デバイスのシリアル番号>",
    "firmwareVersion" : "<デバイスのファームウェアバージョン>",
    "softwareVersion": "<デバイスのソフトウェアバージョン>",
    "customIdentifier": "<デバイスのカスタム識別子>"
  }
}

additionalAttributesオブジェクトのスキーマ

フィールド 説明 必須
manufacturer デバイスのメーカーの名前です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
model デバイスのモデルの名前です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
serialNumber デバイスのシリアル番号です。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
firmwareVersion デバイスのファームウェアバージョンです。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
softwareVersion デバイスのソフトウェアバージョンです。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列
customIdentifier デバイスのカスタム識別子です。この識別子は、システム内ですべてのユーザーアカウントにわたってグローバルに一意である必要があります。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列

capabilityオブジェクト

capabilityオブジェクトは、スキルがサポートするインターフェースを表します。たとえば、スキルがAlexa.PowerControllerインターフェースをサポートすると、照明の点灯をサポートできます。スマートホームデバイスで利用可能なインターフェースを確認するには、Alexaインターフェースの一覧を参照してください。

capabilityオブジェクトの例

クリップボードにコピーされました。

{
    "type": "AlexaInterface",
    "interface": "Alexa.PercentageController",
    "instance": "<コントローラーのインスタンス名>",
    "version": "3",
    "properties": {
        "supported": [
            {
                "name": "percentage"
            }
        ],
        "proactivelyReported": true,
        "retrievable": true
    },
    "capabilityResources": {},
    "configuration": {},
    "semantics": {},
    "verificationsRequired": []
}

capabilityオブジェクトのスキーマ

フィールド 説明 必須
type capabilityの種類です。現在使用できる種類はAlexaInterfaceのみです。 文字列
interface 機能インターフェースの名前です。 文字列
instance 一部のインターフェースにはインスタンスを複数実装できます。この場合、インターフェースの各インスタンスに一意の名前を付けます。詳細については、ModeControllerRangeControllerToggleControllerを参照してください。 文字列
version インターフェースのバージョンです。インターフェースごとにバージョンが異なります。常にインターフェースのドキュメントを参照して、最新のバージョンを確認してください。 文字列
properties スキルがサポートするインターフェースのプロパティです。 propertiesオブジェクト
capabilityResources ユーザーが一部のインターフェースの操作に使用できるフレンドリー名を指定できます。詳細については、フレンドリー名のリソースとアセットおよび各インターフェースのドキュメントを参照してください。 オブジェクト
configuration 一部のインターフェースでは、インターフェースの使用方法に関する情報を含むconfigurationオブジェクトが必要です。詳細については、各インターフェースのドキュメントを参照してください。 オブジェクト
semantics 一部のインターフェースでは、オプションとして、「開いて」、「閉じて」、「上げて」、「下げて」という単語を既存のディレクティブにマッピングできます。 semanticsオブジェクト
verificationsRequired 一部のインターフェースとロケールでは、オプションとして、Alexaがアクションを実行する前にユーザーに確認を求めることができます。 verificationsRequiredオブジェクトの配列

propertiesオブジェクト

propertiesオブジェクトの例

クリップボードにコピーされました。

{
  "supported": [
    {
      "name": "percentage"
    }
  ],
  "proactivelyReported": true,
  "retrievable": true
}

propertiesオブジェクトのスキーマ

フィールド 説明 必須
supported スキルがサポートするインターフェースのプロパティです。 配列
proactivelyReported プロパティが変更されたときにスキルが変更レポートを送信する場合はtrueです。デフォルトはfalseです。 ブール値
retrievable 状態レポートリクエストに応答してプロパティの値をレポートする場合はtrueです。デフォルトはfalseです。 ブール値

semanticsオブジェクト

Alexaインターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーは、デバイスとの対話に標準の発話を使用できます。オプションで、セマンティクスを使用して発話を追加できます。セマンティクスを使用する場合は、「開いて」「閉じて」「上げて」「下げて」といったフレーズを手動でディレクティブにマッピングします。

セマンティクスがサポートされるのは以下のインターフェースのみです: ModeControllerRangeControllerToggleController

semanticsオブジェクトの例

以下は、RangeControllerインターフェースを実装するデバイスの検出応答でのsemanticsオブジェクトの例です。各フィールドの詳細については、以下のsemanticsオブジェクトスキーマテーブルの例を参照してください。

クリップボードにコピーされました。

{
  "semantics": {
    "actionMappings": [
      {
        "@type": "ActionsToDirective",
        "actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
        "directive": {
          "name": "SetRangeValue",
          "payload": {
            "rangeValue": 0
          }
        }
      },
      {
        "@type": "ActionsToDirective",
        "actions": ["Alexa.Actions.Open", "Alexa.Actions.Raise"],
        "directive": {
          "name": "SetRangeValue",
          "payload": {
            "rangeValue": 100
          }
        }
      }
    ],
    "stateMappings": [
      {
        "@type": "StatesToValue",
        "states": ["Alexa.States.Closed"],
        "value": 0
      },
      {
        "@type": "StatesToRange",
        "states": ["Alexa.States.Open"],
        "range": {
          "minimumValue": 1,
          "maximumValue": 100
        }
      }  
    ]
  }
}

semanticsオブジェクトのスキーマ

フィールド 説明 必須
actionMappings アクションフレーズとインターフェースディレクティブ間のマッピングの配列です。 アクションマッピングオブジェクトの配列 actionMappingsstateMappingsのいずれかが必須
stateMappings Alexaの状態とコントローラーの状態の間のマッピングの配列です。ユーザーがOpenClosedのフレーズを使ってデバイスの状態を照会できるよう状態マッピングを含みます。 状態マッピングオブジェクトの配列 actionMappingsstateMappingsのいずれかが必須

アクションマッピングオブジェクト

アクションマッピングオブジェクトの例

クリップボードにコピーされました。

{
  "@type": "ActionsToDirective",
  "actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
  "directive": {
    "name": "SetRangeValue",
    "payload": {
      "rangeValue": 0
    }
  }
}

アクションマッピングのスキーマ

フィールド 説明 必須
@type アクションマッピングのタイプです。現在有効な値は、ActionsToDirectiveのみです。 文字列
actions 1つのディレクティブにマッピングされているアクションの配列です。有効な値は、Alexa.Actions.OpenAlexa.Actions.CloseAlexa.Actions.RaiseAlexa.Actions.Lowerです。 配列
directive アクションで呼び出すディレクティブです。 オブジェクト
directive.name ディレクティブの名前です。ディレクティブは、semanticsオブジェクトを含むcapabilityオブジェクトのインターフェースのディレクティブでなければなりません。 文字列
directive.payload ディレクティブに適したペイロードです。一部のディレクティブにはペイロードは必要ありません。またペイロードの種類はディレクティブによって異なります。詳細については、各インターフェースのドキュメントを参照してください。 オブジェクト

状態マッピングオブジェクト

状態マッピングオブジェクトの例

クリップボードにコピーされました。

{
  "@type": "StatesToRange",
  "states": ["Alexa.States.Open"],
  "range": {
    "minimumValue": 1,
    "maximumValue": 100
  }
}

状態マッピングのスキーマ

フィールド 説明 必須
@type 状態マッピングのタイプです。 有効な値はStatesToValueStatesToRangeのいずれかです。 文字列
states コントローラーの値にマッピングされるAlexaの状態の配列です。有効な値はAlexa.States.OpenAlexa.States.Closedです。 配列
value 指定したAlexaの状態に対応するコントローラーの値です。 @typeStatesToValueの場合は〇
range 指定したAlexaの状態に対応するコントローラーの値の範囲です。 オブジェクト @typeStatesToRangeの場合は〇

verificationsRequiredオブジェクト

照明をオンにするなどのアクションを実行するようにユーザーがスキルに指示した場合、Alexaがアクションを実行する前に、ユーザーに確認を求めることができます。ユーザー確認を求めるには、Discover.Responseで確認を要求するディレクティブを指定します。

ユーザー確認がサポートされるインターフェースは、 PowerControllerThermostatControllerだけです。

verificationsRequiredオブジェクトの例

以下は、ThermostatControllerインターフェースを実装するAlexaスキルの検出応答でのverificationsRequiredオブジェクトの例です。この例では、Alexaがサーモスタットの目標温度を設定する前にユーザーに確認を求めます。完全な例については、ユーザー確認を求めるサーモスタットの例を参照してください。

クリップボードにコピーされました。

{
  "directive": "SetTargetTemperature",
  "methods": [
    {
      "@type": "Confirmation"
    }
  ]
}

verificationsRequiredオブジェクトのスキーマ

フィールド 説明 必須
directive ユーザー確認を求めるディレクティブの名前です。ディレクティブは、verificationsRequiredオブジェクトを含むcapabilityオブジェクトのインターフェースのディレクティブでなければなりません。 文字列
methods ユーザー確認を取得する方法です。現時点でサポートされている確認方法はConfirmationのみです。 配列

connectionsプロパティ

connectionsプロパティは、デバイスがインターネットとスマートホームハブへの接続に使用する方法を表します。connectionsプロパティにはconnectionオブジェクトの配列が含まれます。

connectionsプロパティの例

クリップボードにコピーされました。

{
  "connections": [
    {
      "type": "TCP_IP",
      "macAddress": "00:11:22:AA:BB:33:44:55"
    },
    {
      "type": "ZIGBEE",
      "macAddress": "00:11:22:33:44:55"
    },
    {
      "type": "ZWAVE",
      "homeId": "<0x00000000>",
      "nodeId": "<0x00>"
    },
    {
      "type": "UNKNOWN",
      "value": "00:11:22:33:44:55"
    }
  ]
}

connectionオブジェクトのスキーマ

フィールド 説明 必須
type 接続の種類です。TCP_IPZIGBEEZWAVE、またはUNKNOWNのいずれかです。 文字列
macAddress ネットワークインターフェースコントローラー(NIC)の一意の識別子です。このフィールドは、接続の種類がTCP_IPまたはZIGBEEの場合に、オプションとして含めることができます。 文字列
homeId エンドポイントが接続するZ-WaveネットワークのホームIDです。形式は、UTF-8文字で0x00000000です。このフィールドは、接続の種類がZWAVEの場合に、オプションとして含めることができます。 文字列
nodeId エンドポイントが接続するZ-WaveネットワークのエンドポイントのノードIDです。形式は、UTF-8文字で0x00です。このフィールドは、接続の種類がZWAVEの場合に、オプションとして含めることができます。 文字列
value 接続の種類をより具体的に識別できない場合の接続の情報です。このフィールドで提供する情報は、安定した具体的なものである必要があります。この値には最大256文字の英数字を含めることができ、句読点も含めることができます。 文字列 typeがUNKNOWNである場合は◯

relationshipsオブジェクト

1つのエンドポイントが接続されているエンドポイントを列挙するrelationshipsオブジェクトです。たとえば、コンピューターのエンドポイントはホームネットワークのエンドポイントに接続されている場合があります。詳細については、ネットワークとWi-Fiのスキルについてを参照してください。

relationshipsオブジェクトの例

クリップボードにコピーされました。

{
  "relationships": {
    "isConnectedBy": {
      "endpointId": "<ホームネットワークエンドポイントの一意のID>"
    }
  }
}

relationshipsオブジェクトのスキーマ

フィールド 説明 必須
isConnectedBy このエンドポイントが接続されているネットワークのエンドポイントIDです。指定されたエンドポイントはAlexa.Networking.HomeNetworkControllerを実装する必要があります。 オブジェクト