Alexa検出オブジェクト

Note: Sign in to the developer console to build or publish your skill.

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.BrightnessController`や`Alexa.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`	一部のインターフェースにはインスタンスを複数実装できます。この場合、インターフェースの各インスタンスに一意の名前を付けます。詳細については、ModeController、RangeController、ToggleControllerを参照してください。	文字列	✕
`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インターフェースを使用する場合、音声対話モデルは既にビルドされています。ユーザーは、デバイスとの対話に標準の発話を使用できます。オプションで、セマンティクスを使用して発話を追加できます。セマンティクスを使用する場合は、「開いて」、「閉じて」、「上げて」、「下げて」といったフレーズを手動でディレクティブにマッピングします。

セマンティクスがサポートされるのは以下のインターフェースのみです： ModeController、RangeController、ToggleController。

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`	アクションフレーズとインターフェースディレクティブ間のマッピングの配列です。	アクションマッピングオブジェクトの配列	`actionMappings`と`stateMappings`のいずれかが必須
`stateMappings`	Alexaの状態とコントローラーの状態の間のマッピングの配列です。ユーザーが`Open`や`Closed`のフレーズを使ってデバイスの状態を照会できるよう状態マッピングを含みます。	状態マッピングオブジェクトの配列	`actionMappings`と`stateMappings`のいずれかが必須

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

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

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

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

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

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

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

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

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

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

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

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

verificationsRequiredオブジェクト

注：現在、ユーザー確認はja-JPロケールでのみサポートされています。

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

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

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_IP`、`ZIGBEE`、`ZWAVE`、または`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を実装する必要があります。	オブジェクト	◯

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2020 年 12 月 22 日