Alexa Gadgetsのプロトコルバッファー形式
ガジェットは通常、リソースに制約のあるデバイスなので、Alexaクラウドと直接通信することはありません。その代わりに、ガジェットは、Alexaクラウドとの通信すべてを処理するEchoデバイスと通信を行います。
交換された情報を最小限に保つために、ガジェットとEchoデバイスはバイナリー形式でメッセージを交換します。このトピックでは、ガジェットに関連する情報をバイナリー形式にエンコードおよびデコードする方法について説明します。
概要
EchoデバイスとAlexaクラウドのディレクティブやイベントのやり取りには、JSON形式が使用されます。ただし、ガジェットはリソースに制限のあるデバイスなので、Echoデバイスとガジェットは、この情報を代わりにバイナリー形式で交換します。
バイナリー間の情報のエンコードとデコードを容易にするために、プロトコルバッファーと呼ばれるメカニズムを使用して、プラットフォームに依存しない方法でディレクティブとイベントのフィールドを表します。.protoファイルは構造化データを表すという点でJSONファイルに似ていますが、.protoファイルでコンパイラを実行して、お好みのプログラミング言語でデータを読み書きできるコードを生成することができます。
プロトコルバッファーの詳細については、GoogleのサイトのProtocol Buffer Developer Guideを参照してください。ガジェットは、プロトコルバッファー形式のバージョン3（proto3）を使用します。
ダウンロード
ガジェットのコードの記述を開始する前に、以下をダウンロードする必要があります。
- Alexa Gadgets .protoファイル - Alexa GadgetsサンプルコードGitHubリポジトリから.protoファイルをダウンロードして解凍します。
- .protoコンパイラ - Alexa Gadgetsには、nanopb.protoコンパイラをお勧めします。これはNanopbのウェブサイトからダウンロードできます。これはC言語の実装で、メモリが制限されたシステムで小規模のコードを生成できます。ほかのプログラミング言語の.protoコンパイラの詳細については、GoogleのサイトのGenerating Your Classesを参照してください。
.protoファイルのコンパイル方法
前述の.protoコンパイラと.protoファイルをダウンロードしてインストールした後、Alexa Gadgetsファイルをコンパイルして、Alexa Gadgetsディレクティブやイベントのアクセスクラスを生成できます。次に、ガジェットのコードで日付クラスを使用して、ディレクティブとイベントをエンコードおよびデコードします。
.protoコンパイラを実行する方法は、コンパイラを実行するオペレーティングシステムによって以下のように異なります。.protoコンパイラの使用方法の詳細については、GoogleのサイトのGenerating Your Classesを参照してください。
Windows
この例では、Windowsでnotifications.setIndicatorディレクティブのハンドラーをC++で作成する方法を示します。
- コマンドラインで、Notifications\SetIndicatorフォルダに移動します。
-
次のコマンドを入力して、protocコンパイラを実行します。
注： commonフォルダとディレクティブフォルダの両方をproto_pathに必ず含めるようにしてください。protoc --proto_path=..\..\common;.\ --cpp_out=. notificationsSetIndicatorDirective.protonotificationsSetIndicatorDirective.pb.hとnotificationsSetIndicatorDirective.pb.ccの2つのファイルが出力されます。
MacおよびLinux
MacおよびLinuxで、さまざまなAlexa Gadgets .protoファイルをコンパイルするには、Alexa GadgetsサンプルコードGitHubリポジトリでシェルスクリプトを次のように実行します。
- Alexa GadgetsサンプルコードGitHubリポジトリからダウンロードしたデータのAlexaGadgetsProtoBuf/utilsディレクトリにアクセスします。
- compile_nanos.shを開き、指定した
PROTO_COMPILE_PATHにnanopb .protoコンパイラがあることを確認します。 - compile_nanos.shを実行します。これにより、すべてのAlexa Gadgets .protoファイルの.cファイルと.hのファイルが生成され、現在のディレクトリに配置されます。
スクリプトを使用しない場合（たとえば、単一の.protoファイルをコンパイルする場合など）、その1つの方法として、次のように.protoおよび.optionsファイルを含むディレクトリで.protoコンパイラを実行できます。
protoc -I=. --nanopb_out=. <ファイル名.proto>
たとえば、notificationSetIndicatorPayload.protoで.protoコンパイラを実行するには、次のコマンドを実行します。
protoc -I=. --nanopb_out=. notificationsSetIndicatorDirectivePayload.proto
.protoファイル形式
モジュール性のために、各ディレクティブとイベントは3種類の.protoファイルを使用します。ヘッダー、ペイロード、およびヘッダーとペイロードの.protoファイルをインポートした統合ファイルです。protocのコンパイル処理では、これらをまとめた最終的なコードが作成されます。
ディレクティブヘッダーはすべてのディレクティブに共通であり、イベントヘッダーはすべてのイベントに共通です。
ディレクティブの.protoファイル
このセクションでは、ディレクティブを表す3つの各.protoファイルの例を示します。
ディレクティブのヘッダー
すべてのディレクティブに共通のディレクティブヘッダーdirectiveHeader.protoの.protoの定義は次のとおりです。
syntax = "proto3";
package header;
option java_package = "com.amazon.proto.avs.v20160207.header";
option java_outer_classname = "DirectiveHeader";
message DirectiveHeaderProto {
string namespace = 1;
string name = 2;
string messageId = 3;
}
ディレクティブのペイロード
各ディレクティブに、ペイロードの.protoファイルが1つあります。次に示すnotificationsSetindicatorDirectivePayload.protoは、notifications.setIndicatorディレクティブの.protoファイルの例です。
syntax = "proto3";
package notifications;
option java_package = "com.amazon.proto.avs.v20160207.notifications";
option java_outer_classname = "SetindicatorDirectivePayload";
message SetindicatorDirectivePayloadProto {
bool persistVisualIndicator = 1;
bool playAudioIndicator = 2;
Asset asset = 3;
message Asset {
string assetId = 1;
string url = 2;
}
}
ディレクティブのオプション
ペイロードに1つ以上のフィールドを含む各ディレクティブの.protoファイルには、対応するオプションファイルがあります（たとえば、notifications.clearIndicatorディレクティブのペイロードにはフィールドが含まれていないため、このディレクティブにはオプションファイルがありません）。 オプションファイルは必須ではありませんが、ディレクティブ内のフィールドの最大サイズを指定できます。次に示すnotificationsSetIndicatorDirectivePayload.optionsは、notifications.setIndicatorディレクティブのオプションファイルの例です。
notifications.SetIndicatorDirectivePayloadProto.Asset.assetId max_size:32
notifications.SetIndicatorDirectivePayloadProto.Asset.url max_size:64
ディレクティブの統合ファイル
各ディレクティブには、ガジェットがEchoデバイスから受信するメッセージ全体を表す.protoファイルがあります。次に示すnotificationsSetindicatorDirective.protoは、notifications.setIndicatorディレクティブの.protoファイルの例です。
syntax = "proto3";
package notifications;
option java_package = "com.amazon.proto.avs.v20160207.notifications";
option java_outer_classname = "SetindicatorDirective";
import "directiveHeader.proto";
import "notificationsSetindicatorDirectivePayload.proto";
message SetindicatorDirectiveProto {
Directive directive = 1;
message Directive {
notifications.SetindicatorDirectivePayloadProto payload = 2;
header.DirectiveHeaderProto header = 1;
}
}
イベントの.protoファイル
このセクションでは、イベントを表す3つの.protoファイルの例を示します。
イベントのヘッダー
すべてのイベントに共通するイベントヘッダーeventHeader.protoの.protoの定義は次のとおりです。
syntax = "proto3";
package header;
option java_package = "com.amazon.proto.avs.v20160207.header";
option java_outer_classname = "EventHeader";
message EventHeaderProto {
string namespace = 1;
string name = 2;
string messageId = 3;
}
イベントのペイロード
各イベントには、ペイロードの.protoファイルが1つあります。次に示すdiscoveryResponseAlexadiscoveryEventPayload.protoは、Alexa.Discovery.Discover.Responseイベントの.protoファイルの例です。
syntax = "proto3";
package discoveryResponse;
option java_package = "com.amazon.proto.avs.v20160207.discoveryResponse";
option java_outer_classname = "AlexadiscoveryEventPayload";
message AlexadiscoveryEventPayloadProto {
repeated Endpoints endpoints = 1;
message Endpoints {
string deviceType = 5;
repeated Capabilities capabilities = 11;
message Capabilities {
string configuration = 4;
string type = 1;
string interface = 2;
string version = 3;
}
string endpointId = 1;
string manufacturerName = 4;
string description = 3;
string envelopeVersion = 10;
string firmwareVersion = 8;
string encoding = 9;
string friendlyName = 2;
string deviceTokenType = 7;
bytes deviceToken = 6;
}
}
イベントのオプション
各イベントの.protoファイルには、対応するオプションファイルがあります。オプションファイルは必須ではありませんが、イベント内のフィールドの最大サイズを指定できます。次のalexaDiscoveryDiscoverResponseEventPayload.optionsからの抜粋は、Alexa.Discovery.Discover.Responseイベントのオプションファイルの例です。
alexaDiscovery.DiscoverResponseEventPayloadProto.endpoints max_count:1
alexaDiscovery.DiscoverResponseEventPayloadProto.Endpoints.capabilities max_count:10
（中略）
alexaDiscovery.DiscoverResponseEventPayloadProto.Endpoints.endpointId max_size:32
alexaDiscovery.DiscoverResponseEventPayloadProto.Endpoints.description max_size:32
alexaDiscovery.DiscoverResponseEventPayloadProto.Endpoints.friendlyName max_size:32
イベントの統合ファイル
各イベントには、ガジェットがEchoデバイスに送信するメッセージ全体を表す.protoファイルが1つあります。次に示すdiscoveryResponseAlexadiscoveryEvent.protoは、Alexa.Discovery.Discover.Responseイベントの.protoファイルの例です。
syntax = "proto3";
package discoveryResponse;
option java_package = "com.amazon.proto.avs.v20160207.discoveryResponse";
option java_outer_classname = "AlexadiscoveryEvent";
import "eventHeader.proto";
import "discoveryResponseAlexadiscoveryEventPayload.proto";
message AlexadiscoveryEventProto {
Event event = 1;
message Event {
discoveryResponse.AlexadiscoveryEventPayloadProto payload = 2;
header.EventHeaderProto header = 1;
}
}
