Alexa.Discoveryインターフェース
このインターフェースによって、Echoデバイスはガジェットに関する以下の情報を検出できます。
- 種類、メーカー、ファームウェアのバージョンなど、ガジェットの詳細情報
- ガジェットがサポートする機能またはインターフェース
Bluetooth経由で接続または再接続すると、Echoデバイスがガジェットからこの情報を取得します。この情報をリクエストするために、EchoデバイスはガジェットにDiscover
ディレクティブを送信します。ガジェットは、すべての情報を含むDiscover.Response
イベントで応答します。この種類のディレクティブをデコードし、応答をエンコードする方法については、データのシリアル化と逆シリアル化の例を参照してください。
ディレクティブ
このインターフェースには、以下に説明する1つのディレクティブ (Discover
)が含まれます。
Discoverディレクティブ
このディレクティブは、ガジェットの詳細情報と機能を照会します。.protoファイルの記述は次のとおりです。
syntax = "proto3";
message DiscoverDirectiveProto {
Directive directive = 1;
message Directive {
alexaDiscovery.DiscoverDirectivePayloadProto payload = 2;
header.DirectiveHeaderProto header = 1;
}
}
message DirectiveHeaderProto {
string namespace = 1;
string name = 2;
string messageId = 3;
string dialogRequestId = 4;
}
message DiscoverDirectivePayloadProto {
Scope scope = 1;
message Scope {
string type = 1;
string token = 2;
}
}
DiscoverDirectiveProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 |
---|---|---|
directive |
Discover ディレクティブの全文が含まれます。 |
Directive |
Directive
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 |
---|---|---|
header |
このディレクティブのヘッダーが含まれます。 | DirectiveHeaderProto |
payload |
このディレクティブのペイロードが含まれます。 | DiscoverDirectivePayloadProto |
DirectiveHeaderProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 |
---|---|---|
namespace |
このディレクティブの名前空間で、Alexa.Discovery が入ります。 |
文字列 |
name |
このディレクティブの名前で、Discover が入ります。 |
文字列 |
messageId |
このディレクティブのインスタンスを一意に定義するIDです。文字列は空の場合があります。 | 文字列 |
dialogRequestId |
このディレクティブをユーザーからの特定の音声対話に関連付ける一意のIDです。このフィールドは省略可能です。 | 文字列 |
DiscoverDirectivePayloadProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 |
---|---|---|
scope |
このメッセージは省略可能です。 | Scope |
Scope
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 |
---|---|---|
type |
空の文字列です。 | 文字列 |
token |
空の文字列です。 | 文字列 |
イベント
このインターフェースには、以下に説明する1つのイベント (Discover.Response
)が含まれます。
Discover.Responseイベント
このイベントを使用して、ガジェットは詳細情報と機能を報告します。.protoファイルの記述は次のとおりです。
syntax = "proto3";
message DiscoverResponseEventProto {
Event event = 1;
message Event {
alexaDiscovery.DiscoverResponseEventPayloadProto payload = 2;
header.EventHeaderProto header = 1;
}
}
message EventHeaderProto {
string namespace = 1;
string name = 2;
string messageId = 3;
}
message DiscoverResponseEventPayloadProto {
repeated Endpoints endpoints = 1;
message Endpoints {
repeated Capabilities capabilities = 11;
message Capabilities {
Configuration configuration = 4;
message Configuration {
repeated SupportedTypes supportedTypes = 1;
message SupportedTypes {
string name = 1;
}
}
string type = 1;
string interface = 2;
string version = 3;
}
AdditionalIdentification additionalIdentification = 12;
message AdditionalIdentification {
string modelName = 5;
string deviceTokenEncryptionType = 3;
string firmwareVersion = 1;
string amazonDeviceType = 4;
string radioAddress = 6;
string deviceToken = 2;
}
string endpointId = 1;
string manufacturerName = 4;
string description = 3;
string friendlyName = 2;
}
}
DiscoverResponseEventProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
event |
Discover.Response イベントの全文が含まれます。 |
Event |
◯ |
Event
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
header |
このイベントのヘッダーが含まれます。 | EventHeaderProto |
◯ |
payload |
このイベントのペイロードが含まれます。 | DiscoverResponseEventPayloadProto |
◯ |
EventHeaderProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
namespace |
このイベントの名前空間で、Alexa.Discovery が入ります。 |
文字列 |
◯ |
name |
このイベントの名前で、Discover.Response が入ります。 |
文字列 |
◯ |
messageId |
このディレクティブのインスタンスを一意に定義するIDです。文字列は空の場合があります。 | 文字列 |
◯ |
DiscoverResponseEventPayloadProto
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
endpoints |
エンドポイントの配列です。各エンドポイントは、Echoデバイスに接続されているガジェットを示します。 | Endpoints の配列 |
◯ |
Endpoints
このメッセージのフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
capabilities |
ガジェットの機能の配列です。機能は、ガジェットがサポートするインターフェースを示します。 | Capabilities の配列 |
◯ |
AdditionalIdentification |
モデル名、ファームウェアのバージョンなど、ガジェットに関する追加情報です。 | AdditionalIdentification |
◯ |
endpointId |
ガジェットの識別子です。
|
文字列 |
◯ |
manufacturerName |
デバイスメーカーの名前です。この値は128文字以内でなければなりません。例: "AMAZON" |
文字列 |
◯ |
description |
人が読める形式でのガジェットの説明です。この値は128文字以内でなければなりません。例: "EchoButtons" |
文字列 |
◯ |
friendlyName |
ユーザーがガジェットの識別に使用する名前です。この値は15文字以内でなければなりません。また、特殊文字や句読点は使用できません。例: "EchoButton1" |
文字列 |
◯ |
Capabilities
ガジェットには、サポートするすべてのインターフェースのCapabilities
オブジェクトを含める必要があります。ここに入力する項目の詳細については、インターフェースのAPIリファレンスの「このインターフェースのサポート」セクションを参照してください。例として、NotificationsのAPIリファレンスを参照してください。
Capabilities
フィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
type |
機能の型を表します。この型により、機能に含まれるフィールドが決まります。現在、有効な値はAlexaInterface のみです。 |
文字列 |
◯ |
interface |
インターフェースの修飾名です。インターフェースはガジェットが対応するアクションを表します。 | 文字列 |
◯ |
version |
このガジェットがサポートするインターフェースバージョンを表します。 | 文字列 |
◯ |
configuration |
ガジェットに関する追加の説明を含みます。 | Configuration |
✕ |
Configuration
このフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
supportedTypes |
ガジェットがサポートする機能内の型です。 | SupportedTypes |
◯ |
SupportedTypes
このフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
name |
ガジェットがサポートする機能内の型です。複数の型をサポートする場合にのみ、この情報が必要です。たとえば、ガジェットがAlexa.Gadget.StateListener インターフェースをサポートしている場合、このインターフェースのサポートを参照すると、name はalarms 、timers 、reminders などであることがわかります。 |
文字列 |
◯ |
AdditionalIdentification
このフィールドは次のとおりです。
フィールド | 説明 | 型 | 必須 |
---|---|---|---|
modelName |
ガジェットのタイプの一般名です。例: "EchoButton" |
文字列 |
◯ |
deviceTokenEncryptionType |
デバイスシークレットのアルゴリズムです。現在、有効な値は1 のみです。これは、アルゴリズムがSHA256であることを意味します。 |
文字列 |
◯ |
firmwareVersion |
ガジェットで実行されているファームウェアのバージョンです。ガジェットのOTAアップデートが必要かどうかを判断するために使用されます。 | 整数を含む文字列 |
◯ |
amazonDeviceType |
ガジェットの種類です。これは、開発者ポータルのガジェットの製品ページに表示されるAmazon IDです。 | 文字列 |
◯ |
radioAddress |
16進数形式のガジェットのMACアドレスです。例: "0123456789AB" |
文字列 |
◯ |
deviceToken |
ガジェット登録後に開発者ポータルに表示されるAlexa Gadgetシークレットと連結されたendpointId (SHA256 )を含む、UTF-8でエンコードされた文字列です。以下のコードは、Pythonでデバイスのトークンを計算する方法を示しています。 import hashlib def generate_token(device_id, device_token): hash_object = ( hashlib.sha256(bytes(device_id, 'utf-8') + bytes(device_token, 'utf-8')) ) hex_dig = hash_object.hexdigest() return bytes(hex_dig, 'utf-8') |
文字列 |
◯ |