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 ユーザーがガジェットの識別に使用する名前です。この値は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')
文字列 ◯