Alexa.Discoveryインターフェース



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

ガジェットの識別子です。

  • ガジェットのファームウェアに入力する一意のIDです。
  • デバイスのシリアル番号(DSN)とも呼ばれます。
  • 変更不可です。
  • デバイスタイプ内で一意である必要があります(デバイスタイプは、開発者ポータルに表示されるガジェットのAmazon IDです)。 つまり、すべてのガジェットには、同じタイプであっても、一意のエンドポイントが必要です。
    例: "G090RD108032071X"
  • 英数字、スペース、および次の特殊文字を使用できます。使用可能な特殊文字:_ - = # ; : ? @ &
  • 256文字以内でなければなりません。
文字列
manufacturerName デバイスメーカーの名前です。この値は128文字以内でなければなりません。例: "AMAZON" 文字列
description 人が読める形式でのガジェットの説明です。この値は128文字以内でなければなりません。例: "EchoButtons" 文字列
friendlyName ユーザーがガジェットの識別に使用する名前です。この値は128文字以内でなければなりません。また、特殊文字や句読点は使用できません。例: "EchoButton1" 文字列

Capabilities

ガジェットには、サポートするすべてのインターフェースのCapabilitiesオブジェクトを含める必要があります。ここに入力する項目の詳細については、インターフェースのAPIリファレンスの「このインターフェースのサポート」セクションを参照してください。例として、NotificationsのAPIリファレンスを参照してください。

Capabilitiesフィールドは次のとおりです。

フィールド 説明 必須
type 機能の型を表します。この型により、機能に含まれるフィールドが決まります。現在、有効な値はAlexaInterfaceのみです。 文字列
interface インターフェースの修飾名です。インターフェースはガジェットが対応するアクションを表します。 文字列
version このガジェットがサポートするインターフェースバージョンを表します。 文字列
configuration ガジェットに関する追加の説明を含みます。 Configuration

Configuration

このフィールドは次のとおりです。

フィールド 説明 必須
supportedTypes ガジェットがサポートする機能内の型です。 SupportedTypes

SupportedTypes

このフィールドは次のとおりです。

フィールド 説明 必須
name ガジェットがサポートする機能内の型です。複数の型をサポートする場合にのみ、この情報が必要です。たとえば、ガジェットがAlexa.Gadget.StateListenerインターフェースをサポートしている場合、このインターフェースのサポートを参照すると、namealarmstimersremindersなどであることがわかります。 文字列

AdditionalIdentification

このフィールドは次のとおりです。

フィールド 説明 必須
modelName ガジェットのタイプの一般名です。例: "EchoButton" 文字列
deviceTokenEncryptionType デバイスシークレットのアルゴリズムです。現在、有効な値は1のみです。これは、アルゴリズムがSHA256であることを意味します。 文字列
firmwareVersion このガジェットで実行されているファームウェアのバージョンです。OTA(ワイヤレス)アップデート中、ガジェットはこの値でCMD_VERSIONコマンドに応答します。ガジェットのファームウェアバージョンの初期値は、ゼロでなければなりません。 整数を含む文字列
amazonDeviceType ガジェットの種類です。これは、開発者ポータルのガジェットの製品ページに表示されるAmazon IDです。 文字列
radioAddress 16進数形式のガジェットのMACアドレスです。例: "0123456789AB" 文字列
deviceToken ガジェット登録後に開発者ポータルに表示されるAlexa Gadgetシークレットと連結されたendpointIdSHA256)を含む、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')
文字列