Alexa Gadgetsのプロトコルバッファー形式

ガジェットは通常、リソースに制約のあるデバイスなので、Alexaクラウドと直接通信することはありません。その代わりに、ガジェットは、Alexaクラウドとの通信すべてを処理するEchoデバイスと通信を行います。

交換された情報を最小限に保つために、ガジェットとEchoデバイスはバイナリー形式でメッセージを交換します。このトピックでは、ガジェットに関連する情報をバイナリー形式にエンコードおよびデコードする方法について説明します。

概要
ダウンロード
.protoファイルのコンパイル方法
- Windows
- MacおよびLinux
.protoファイル形式
- ディレクティブの.protoファイル
- イベントの.protoファイル

概要

EchoデバイスとAlexaクラウドのディレクティブやイベントのやり取りには、JSON形式が使用されます。ただし、ガジェットはリソースに制限のあるデバイスなので、Echoデバイスとガジェットは、この情報を代わりにバイナリー形式で交換します。

バイナリー間の情報のエンコードとデコードを容易にするために、プロトコルバッファーと呼ばれるメカニズムを使用して、プラットフォームに依存しない方法でディレクティブとイベントのフィールドを表します。.protoファイルは構造化データを表すという点でJSONファイルに似ていますが、.protoファイルでコンパイラを実行して、お好みのプログラミング言語でデータを読み書きできるコードを生成することができます。

プロトコルバッファーの詳細については、GoogleのサイトのProtocol Buffer Developer Guideを参照してください。ガジェットは、プロトコルバッファー形式のバージョン3（proto3）を使用します。

ダウンロード

ガジェットのコードの記述を開始する前に、以下をダウンロードする必要があります。

Alexa Gadgets .protoファイル - GitHubのAlexa Gadgetsサンプルコードリポジトリから.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.proto
```
notificationsSetIndicatorDirective.pb.hとnotificationsSetIndicatorDirective.pb.ccの2つのファイルが出力されます。

MacおよびLinux

MacおよびLinuxで、さまざまなAlexa Gadgets .protoファイルをコンパイルするには、GitHubのAlexa Gadgetsサンプルコードを使用してシェルスクリプトを次のように実行します。

GitHubのAlexa Gadgetsサンプルコードからダウンロードしたデータの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;
   }
}