Alexa検出オブジェクトのリファレンス
このリファレンスでは、Alexa.DiscoveryインターフェースでAlexaに送信するオブジェクトの定義を説明します。
Endpointオブジェクト
Endpointオブジェクトは、ユーザーのデバイス制御クラウドアカウントと関連付けられた、接続済みデバイス／コンポーネントを表します。エンドポイントには以下のいずれかの詳細が含まれます。
- 物理デバイス
- 仮想デバイス（シーン内など）
- ソフトウェアコンポーネント（モバイルアプリなど）
endpointオブジェクトの例
{
"endpointId": "エンドポイントの一意のID",
"manufacturerName": "サンプルメーカー",
"description": "サンプルメーカーのスマート照明",
"friendlyName": "リビングの照明",
"displayCategories": ["LIGHT"],
"additionalAttributes": {
"manufacturer": "サンプルメーカー",
"model": "サンプルモデル",
"serialNumber": "デバイスのシリアル番号",
"firmwareVersion": "デバイスのファームウェアバージョン",
"softwareVersion": "デバイスのソフトウェアバージョン",
"customIdentifier": "デバイスの任意のカスタム識別子"
},
"capabilities": [],
"connections": [],
"relationships": {},
"registration": {},
"cookie": {
"extraDetail1": "スキルが使用する情報",
"extraDetail2": "複数のエントリを作成できます",
"extraDetail3": "ここにデバイスの状態を保存しないでください"
}
}
Endpointオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
エンドポイントの識別子です。識別子は、スキルを使用するすべてのデバイスおよびユーザーでグローバルに一意である必要があります。同じデバイスのすべての検出リクエストに対して、識別子は常に同じである必要があります。 |
文字列 |
◯ |
|
|
デバイスのメーカーの名前です。 |
文字列 |
◯ |
|
|
デバイスの説明です。メーカー名やデバイスの接続方法を含めてください。 |
文字列 |
◯ |
|
|
デバイスを識別するためにユーザーが使用する名前です。フレンドリー名の初期値を設定したら、その後はユーザーがAlexaアプリを使って変更できます。このプロパティはすべてのインターフェースで必須です（一部例外があります）。このフィールドが任意かどうかを確認するには、Alexa機能インターフェースのドキュメントを参照してください。 |
文字列 |
◯ |
|
|
Alexaアプリでデバイスが表示されるカテゴリーです。 |
文字列の配列 |
◯ |
|
|
エンドポイントについての追加情報です。Alexaアプリのユーザーエクスペリエンスが向上するため、このプロパティを含めることをお勧めします。Works with Alexa認定の申請を希望する場合は、このプロパティを含める必要があります。 |
|
推奨 |
|
|
スキルがエンドポイントをサポートする機能インターフェースです。 |
|
◯ |
|
|
デバイスがインターネットとスマートホームハブへの接続に使用する方法についての情報です。 |
|
✕ |
|
|
エンドポイントが接続するエンドポイントです。たとえば、コンピューターのエンドポイントはホームネットワークのエンドポイントに接続します。 |
|
✕ |
|
|
スキルが使用するデバイスについての情報です。このプロパティのコンテンツは5,000バイト以内でなければなりません。Alexaはこのデータの読み取りや使用は行いません。 |
名前と値のペアのリスト |
✕ |
AdditionalAttributesオブジェクト
さまざまなスキルが同じデバイスを異なる方法で表していると、Alexaアプリに同じデバイスが複数回表示され、ユーザーが混乱する原因となります。Alexaは、AdditionalAttributesオブジェクトを使用して重複するデバイスを識別し、Alexaアプリのユーザーエクスペリエンスを向上させます。
AdditionalAttributesオブジェクトの例
{
"additionalAttributes": {
"manufacturer" : "サンプルメーカー",
"model" : "サンプルモデル",
"serialNumber": "シリアル番号",
"firmwareVersion" : "ファームウェアバージョン",
"softwareVersion": "ソフトウェアバージョン",
"customIdentifier": "カスタム識別子（MatterのUniqueIDなど）"
}
}
AdditionalAttributesオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
デバイスのメーカーの名前です。 |
文字列 |
推奨 |
|
|
ユーザーに表示されるデバイスのモデル名です。モデルは製品の特定のバリエーションを一意に識別する必要があります。たとえば、Audi A6 2020という車の場合、メーカーは |
文字列 |
推奨 |
|
|
デバイスのシリアル番号です。 |
文字列 |
推奨 |
|
|
デバイスのファームウェアバージョンです。 |
文字列 |
推奨 |
|
|
デバイスのソフトウェアバージョンです。 |
文字列 |
推奨 |
|
|
デバイスのカスタム識別子です。この識別子は、さまざまなユーザーアカウントにわたってグローバルに一意である必要があります。 |
文字列 |
推奨 |
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オブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
機能の種類です。現時点で使用できる種類は |
文字列 |
◯ |
|
|
機能インターフェースの名前です。 |
文字列 |
◯ |
|
|
一部のインターフェースにはインスタンスを複数実装できます。この場合、インターフェースの各インターフェースに一意の名前を付けます。詳細については、汎用コントローラーインターフェースを参照してください。 |
文字列 |
✕ |
|
|
インターフェースのバージョンです。インターフェースごとにバージョンが異なります。 |
文字列 |
◯ |
|
|
スキルがサポートするインターフェースのプロパティです。 |
|
✕ |
|
|
ユーザーが一部のインターフェースとの対話に使用できるフレンドリー名を指定します。詳細については、フレンドリー名のリソースとアセットおよび各インターフェースのドキュメントを参照してください。 |
オブジェクト |
✕ |
|
|
任意の設定です。一部のインターフェースでは、インターフェースの使用方法に関する情報を含むconfigurationオブジェクトが必要です。詳細については、各インターフェースのドキュメントを参照してください。 |
オブジェクト |
✕ |
|
|
一部のインターフェースでは、セマンティクスを使用して機能を追加できます。 |
|
✕ |
|
|
一部のインターフェースとロケールでは、Alexaがアクションを実行する前に任意でユーザーに確認を求めることができます。 |
|
✕ |
|
|
コネクテッドカーの場合、任意で認証の信頼度とポリシー名を指定できます。 |
|
✕ |
Propertiesオブジェクト
Propertiesオブジェクトは、エンドポイントの出力可能なプロパティを定義します。各Alexaインターフェースで出力可能なプロパティ名と値を定義します。詳細については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。
propertiesオブジェクトの例
{
"supported": [
{
"name": "percentage"
}
],
"proactivelyReported": true,
"retrievable": true
}
Propertiesオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
スキルがサポートするインターフェースのプロパティです。 |
配列 |
✕ |
|
|
プロパティが変更されたときにスキルが変更レポートを送信する場合は |
ブール値 |
✕ |
|
|
状態レポートリクエストに応答してプロパティの値をレポートする場合は |
ブール値 |
✕ |
Semanticsオブジェクト
プリビルドの音声対話モデルで定義した標準発話以外にユーザー発話を追加する場合は、セマンティクスを使用できます。発話にセマンティクスを使用する場合は、「開いて」、「閉じて」、「上げて」、「下げて」といったフレーズを手動でコントローラーのディレクティブにマッピングします。詳細については、ユーザー発話のセマンティクスを参照してください。
デバイスでAlexa Hunchesを有効にしてユーザーの代わりにエネルギーを節約する場合にも、セマンティクスを使用できます。詳細については、Alexa Hunchesのセマンティクスを参照してください。
Alexaアプリのユーザーエクスペリエンスを向上させるには、セマンティクスを使用して、デバイスに注意を向けてもらう必要がある場合にユーザーへのお知らせを有効にすることができます。お知らせを有効にするには、デバイスのステータスコードをAlexaで事前定義された状態にマッピングします。詳細については、通知のセマンティクスを参照してください。
Semanticsオブジェクトの例
以下は、RangeControllerインターフェースを実装するデバイスの検出応答での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オブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
アクションフレーズとインターフェースディレクティブ間のマッピングの配列です。 |
|
|
|
|
Alexaの状態とコントローラーの状態の間のマッピングの配列です。ユーザーが |
|
|
ActionMappingsオブジェクト
ActionMappingsオブジェクトは、アクションフレーズとインターフェースディレクティブ間のマッピングを定義します。
ActionMappingsオブジェクトの例
{
"@type": "ActionsToDirective",
"actions": ["Alexa.Actions.Close", "Alexa.Actions.Lower"],
"directive": {
"name": "SetRangeValue",
"payload": {
"rangeValue": 0
}
}
}
ActionMappingsオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
アクションマッピングのタイプです。 |
文字列 |
◯ |
|
|
1つのディレクティブにマッピングされているアクションの配列です。 |
配列 |
◯ |
|
|
アクションで呼び出すディレクティブを指定します。 |
オブジェクト |
◯ |
|
|
ディレクティブの名前です。ディレクティブは、 |
文字列 |
◯ |
|
|
ディレクティブに適したペイロードです。一部のディレクティブにはペイロードは必要ありません。またペイロードのタイプはディレクティブによって異なります。詳細については、各インターフェースのドキュメントを参照してください。 |
オブジェクト |
✕ |
StateMappingsオブジェクト
StateMappingsオブジェクトは、Alexaの状態とコントローラーの状態の間のマッピングを定義します。
StateMappingsオブジェクトの例
{
"@type": "StatesToRange",
"states": ["Alexa.States.Open"],
"range": {
"minimumValue": 1,
"maximumValue": 100
}
}
StateMappingsオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
状態マッピングのタイプです。 |
文字列 |
◯ |
|
|
コントローラーの値にマッピングされるAlexaの状態の配列です。 |
配列 |
◯ |
|
|
指定したAlexaの状態に対応するコントローラーの値です。 |
値 |
|
|
|
指定したAlexaの状態に対応するコントローラーの値の範囲です。 |
オブジェクト |
|
VerificationsRequiredオブジェクト
ユーザーがスキルに照明をオンにするなどのアクションの実行をリクエストする際、アクションを実行して結果に関するフィードバックを提供する前に、まずユーザーからのアクションの確認を要求することができます。ユーザー確認を求めるには、エンドポイントごとに、検出応答で確認を要求するディレクティブを指定します。
アクションの確認をサポートするインターフェースは、 Alexa.PowerControllerとAlexa.ThermostatControllerです。
VerificationsRequiredオブジェクトの例
以下は、ThermostatControllerインターフェースを実装するAlexaスキルのVerificationsRequiredオブジェクトの例です。この例では、Alexaがサーモスタットの目標温度を設定する前にアクションの確認を要求します。検出応答全体の例については、アクションの確認を求めるサーモスタットの例を参照してください。
{
"directive": "SetTargetTemperature",
"methods": [
{
"@type": "Confirmation"
}
]
}
VerificationsRequiredオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
確認を求めるディレクティブの名前です。ディレクティブは、 |
文字列 |
◯ |
|
|
アクションの確認を取得するのに使用するメソッドを指定します。 |
オブジェクトの配列 |
◯ |
|
|
アクションの確認を取得するメソッドです。 |
文字列 |
◯ |
DirectiveConfigurationsオブジェクト
以下のインターフェースは、directiveConfigurationsをサポートします。 Alexa.PowerController、Alexa.LockController、Alexa.ToggleController、Alexa.RangeController、Alexa.ModeController。
DirectiveConfigurationsオブジェクトの例
以下は、Alexaスキルの検出応答でのdirectiveConfigurationsオブジェクトの例です。スキルはLockControllerインターフェースを実装し、Alexaがコネクテッドカーのロック解除をする前にユーザーを識別する必要があります。ユーザーの識別が必要なロックの例全体については、discovery response example with voice recognition and personal profile PINを参照してください。
"directiveConfigurations": [{
"directives": ["Unlock"],
"requestedAuthenticationConfidenceLevel": {
"level": 400,
"customPolicy": {
"policyName": "VOICE_PIN"
}
}
}
]
DirectiveConfigurationsオブジェクトの詳細
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
ユーザーの識別を必要とするディレクティブの名前です。名前は、capabilityオブジェクトに指定したインターフェースと一致する必要があります。 |
文字列の配列 |
◯ |
|
|
認証の信頼度（ACL）を指定して、Alexaが発話した人の識別をどの程度信頼しているかを表します。 |
オブジェクト |
✕ |
|
|
発話した人の識別時にリクエストされたAlexaの信頼度です。
|
整数 |
◯ |
|
|
認証ポリシーを指定します。 |
オブジェクト |
✕ |
|
|
認証ポリシーの名前を指定します。 |
文字列 |
✕ |
Connectionsプロパティ
Connectionsプロパティは、デバイスがインターネットとスマートホームハブへの接続に使用する方法を表します。connectionsプロパティにはconnectionオブジェクトの配列が含まれます。
connectionsプロパティの例
{
"connections": [
{
"type": "BLUETOOTH_MESH",
"deviceUuid": "90b6eeb8cb58c9a7887d4797543bbe8a"
},
{
"type": "MATTER",
"macAddress": "00:11:22:AA:BB:33:44:55",
"macNetworkInterface": "WIFI",
"matterVendorId": "MatterのVendorID",
"matterProductId": "MatterのProductID",
"matterDiscriminator": "longDiscriminator"
},
{
"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"
}
]
}
Connectionsオブジェクトの詳細
次の表は、Connectionsオブジェクトの詳細と、各プロパティに適用される接続のtypeをまとめたものです。
| プロパティ | 説明 | 接続の種類 | 型 | 必須 |
|---|---|---|---|---|
|
|
接続の種類。 |
すべて |
文字列 |
◯ |
|
|
ネットワークインターフェースコントローラー（NIC）の一意の識別子。接続の種類が |
|
文字列 |
推奨 |
|
|
エンドポイントが接続するZ-WaveネットワークのホームIDです。 |
|
文字列 |
✕ |
|
|
エンドポイントが接続するZ-Waveネットワーク内のエンドポイントのノードIDです。 |
|
文字列 |
✕ |
|
|
製造時にエンドポイントに割り当てられた12ビットの値です。複数のコミッション可能なMatterデバイス通知を識別するのに使用します。 |
|
整数 |
◯ |
|
|
Connectivity Standards Allianceによってエンドポイントメーカーに割り当てられる16ビットの値です。 |
|
整数 |
◯ |
|
|
製品を一意に識別するためにベンダーが割り当てた16ビットの値です。 |
|
整数 |
◯ |
|
|
|
|
文字列 |
推奨 |
|
|
Bluetoothメッシュネットワークに接続するデバイスエンドポイントのUUIDです。 |
|
文字列 |
◯ |
|
|
接続の種類をより具体的に識別できない場合、接続の情報を含めます。このプロパティで提供する情報は、安定した具体的なものである必要があります。 |
|
文字列 |
◯ |
Relationshipsオブジェクト
1つのエンドポイントを接続するエンドポイントを列挙するrelationshipsオブジェクトです。たとえば、ヘッドライトを車に接続したり、1つ以上のスピーカーをサウンドバーに接続してホームシアターを構成したりする場合です。Alexaは、Alexaアプリでデバイスの関係を使用して、関連するデバイスやシーンを分類します。詳細については、Identify relationships between endpointsを参照してください。
コネクテッドビークルエンドポイントのRelationshipsオブジェクトの例
{
"relationships": {
"Alexa.Automotive.IsPartOf": {
"endpointId": "vehicle-1"
}
}
}
Alexa搭載ビデオデバイスのRelationshipsオブジェクトの例
{
"endpoints": [{
"endpointId": "ABI-hub-endpointID",
"registration": {
"productId": "productID-001",
"deviceSerialNumber": "serial-001"
},
"friendlyName": "マイAlexa搭載ハブ",
"displayCategories": ["ALEXA_VOICE_ENABLED"],
"capabilities": [],
"connections": []
},
{
"endpointId": "soundbar-endpointID",
"friendlyName": "サウンドバー",
"displayCategories": ["OTHER"],
"relationships": {
"video_isSameAs": {
"endpointId": "serial-001",
"endpointTypeId": "productID-001",
"source": "AVS"
}
}
},
{
"endpointId": "tv-endpointID",
"friendlyName": "TV",
"displayCategories": ["TV"],
"relationships": {
"isControlledBy": [{
"endpointId": "ABI-hub-endpointID"
}],
"video_isSameAs": {
"endpointId": "serial-001",
"endpointTypeId": "productID-001",
"source": "AVS"
}
}
}
]
}
Relationshipsオブジェクトの詳細
以下の表は、Relationshipsオブジェクトの詳細を示しています。1つ以上のプロパティを含める必要があります。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
検出応答のエンドポイントが接続する車を識別します。このプロパティを使用して、ライト、ロックなどの車のパーツを車に接続します。詳細については、Alexaのコネクテッドカースキルを参照してください。 |
オブジェクト |
✕ |
|
|
このエンドポイントが接続する車のエンドポイントIDです。 |
文字列 |
◯ |
|
|
別のエンドポイントがこのエンドポイントを制御することを示すのに使用します。たとえば、Alexa搭載サウンドバーがテレビを制御したり、シーンが複数のライトを制御したりする場合です。出力される 注： 1つのエンドポイントに指定できるのは、1つのcontrolled-by関係のみです。
|
文字列の配列 |
✕ |
|
|
スマートホームエンドポイントが1つ以上のAlexa搭載（ABI）エンドポイントを制御することを示すのに使用します。クラスターを構成するすべてのエンドポイントを含めます。たとえば、1つ以上のスピーカーがサウンドバーに接続してホームシアターを構成する場合などです。クラスターエンドポイントはAlexaアプリに表示され、すべての子エンドポイントは非表示になります。 |
文字列の配列 |
✕ |
|
|
ビデオ機能付きのスマートホームエンドポイントをAlexa搭載デバイスに関連付ける場合に使用します。 |
オブジェクト |
✕ |
|
|
Alexa搭載デバイスなど、エンドポイントソースの種類です。 |
文字列 |
✕ |
|
|
Alexa搭載ソースの |
文字列 |
◯ |
|
|
Alexa搭載製品IDです。 |
文字列 |
✕ |
Registrationプロパティ
Registrationプロパティを使用して、Alexa搭載デバイスを表します。
Registrationプロパティの例
{
"registration": {
"productId": "productID-001",
"deviceSerialNumber": "serial-001"
}
}
Registrationオブジェクトの詳細
以下の表は、Registrationオブジェクトの詳細を示しています。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
開発者が提供した製品IDです。Alexa搭載デバイスの認可フローでアクセストークンを取得するのに使用した |
文字列 |
◯ |
|
|
同じ |
文字列 |
◯ |
関連トピック
最終更新日: 2024 年 12 月 06 日