Alexaインターフェースのメッセージとプロパティ

---

Alexaスキルを作成してスキルコードにAlexaインターフェースを実装すると、Alexaとの間でメッセージの送受信を行えます。Alexaは、スキルにディレクティブを送信し、ユーザーに代わって何らかのリクエストを行います。スキルがデバイスを制御する場合、Alexaはディレクティブを送信してデバイスを制御するか、デバイスに関する状態情報をリクエストします。スキルは、Alexaに応答を返すことでディレクティブに応答します。先回りしてAlexaにイベントを送信することもできます。

このリファレンスには、すべてのスキルが実装する基本的なメッセージとパラメーターの一覧が含まれています。

メッセージのリファレンス

Alexaからスキルへのメッセージ

以下は、Alexaがスキルに送信するメッセージの一覧です。

• AcceptGrantディレクティブ – Alexaはユーザーを識別して認証する認証情報をスキルに提供します。
• Discoverディレクティブ – ユーザーはデバイスをスマートホームスキルに接続するようAlexaにリクエストします。
• ReportState directive – Alexaは、スマートホームスキルまたはビデオスキルに接続されたデバイスの状態をアナウンスまたは表示します。
• インターフェース固有のディレクティブ – ユーザーはAlexaにデバイスを制御するようリクエストします。ディレクティブの例については、各インターフェースのドキュメントを参照してください。

スキルからAlexaへのメッセージ

以下は、スキルがAlexaに送信するイベントメッセージの一覧です。

• AcceptGrant.Response – ユーザーの認証情報を受け取って格納したら、AcceptGrant応答を送信します。
• Discover.Response – ユーザーがデバイスをスキルに接続できるよう、検出応答を送信します。
• AddOrUpdateReportイベント – ユーザーがスキルに接続されているデバイスを追加または更新したら、Alexaにイベントを送信して新しいデバイスや更新されたデバイスについて知らせます。
• DeleteReportイベント – ユーザーがスマートホームスキルに接続されたデバイスを削除したら、イベントを送信してAlexaに知らせます。
• StateReport – スキルは、状態レポートディレクティブに対する状態レポート応答を返して、Alexaにスキルが制御するデバイスの状態を知らせます。
• ChangeReportイベント – デバイスの状態が変更されたら、プロアクティブに変更レポートイベントを送信します。
• Responseイベント – インターフェース固有のディレクティブに応答を送信します。
• DeferredResponseイベント – 特定のディレクティブの後に遅延応答を送信して、実際の応答を後で送信することをAlexaに知らせます。
• ErrorResponse – インターフェース固有のディレクティブを処理できない場合、エラー応答を送信してエラーの理由を知らせます。たとえば、電源オンのディレクティブを受け取ったのに、デバイスが接続されていない場合などです。

Alexaに送信するすべてのイベントと応答の例については、各インターフェースのドキュメントを参照してください。

メッセージの形式

ディレクティブ、イベント、応答のメッセージコンテンツはすべて共通です。

• Header — メッセージとインターフェースを定義します。
• Endpoint — デバイスを識別し、認証情報を含みます。
• Payload — メッセージのパラメーターです。ペイロードの内容は、ヘッダーで定義されるインターフェースによって異なります。

ディレクティブの場合、これらのプロパティはDirectiveオブジェクトに含まれます。イベントと応答の場合、これらのプロパティはEventオブジェクトに含まれます。また、一部のイベントと応答には、Contextオブジェクトが含まれます。

以下は、ディレクティブリクエストの例です。メッセージには、header、endpoint、payloadのオブジェクトが含まれています。

以下は、ディレクティブ応答の例です。メッセージには、header、endpoint、payload、contextのオブジェクトが含まれています。

プロパティのリファレンス

以下のプロパティは、全メッセージタイプで共通です。

Headerオブジェクト

以下の表は、Headerオブジェクトに含まれるプロパティを示しています。

プロパティ	説明	型	必須
namespace	メッセージペイロードのインターフェースを指定します。例：Alexa、Alexa.Discovery、Alexa.PowerControllerなど。	文字列	◯
name	メッセージ内のディレクティブ、イベント、応答の名前です。例：Discover、ReportState、TurnOn、AdjustPercentage、Response、ErrorResponse、StateReport、ChangeReportなど。	文字列	◯
messageId	メッセージごとに一意のIDです。スキルが送信するすべての応答およびイベントの新しい値を含みます。Amazonでは、バージョン4のUUIDを使用することをお勧めします。 有効な値は、 英数字およびダッシュを含む最大128文字の文字列です。 追跡の目的で使用します。メッセージIDをログに記録することはできますが、ビジネスロジックのプログラミングには使用しないでください。	文字列	◯
correlationToken	メッセージの交換を識別するOpaqueトークンです。Alexaから相関トークンを含むディレクティブを受信したら、同じ相関トークンを応答メッセージに含めます。応答をAlexaイベントゲートウェイに非同期に送信する場合も、Alexaから受け取った相関トークンを含めます。Alexaからのリクエストへの応答ではないイベントを送信する場合は、相関トークンを含めないでください。たとえば、Alexa.ChangeReportイベントを送信する場合は、correlationTokenを含めません。	文字列	✕
payloadVersion	名前空間フィールドに指定されたインターフェースのAPIバージョンです。 有効な値は "3"です。	文字列	◯

Endpointオブジェクト

スキルがデバイスを制御する場合、AlexaからのメッセージにはEndpointオブジェクトが含まれます。スキルからAlexaへのメッセージにEndpointオブジェクトが含まれることで、Alexaはデバイスを識別し、スキルの認証を行うことができます。検出応答でのEndpointオブジェクトの定義については、endpointオブジェクトを参照してください。

以下の表は、Endpointオブジェクトに含まれるプロパティを示しています。

プロパティ	説明	型	必須
endpointId	ユーザーに関連付けられたデバイスを識別します。この識別子は、スキルのドメイン内でユーザーが所有するすべてのデバイスで一意である必要があります。検出時にendpointIDを指定し、同じIDを同じデバイスを対象とするすべてのメッセージで常に使用します。 有効な値は、 英数字を含む最大256文字の文字列です。英数字、スペース、および次の特殊文字を使用できます：_ - = # ; : ? @ &	文字列	◯
scope	スキルの認証を行うベアラートークンのスコープです。Alexaゲートウェイに送信するイベントや非同期応答で必要です。	Scopeオブジェクト	✕
cookie	エンドポイントに関連付けられたキー／値ペアのリストです。検出時にcookieを指定すると、Alexaはエンドポイントに関するスキルへのすべてのメッセージでcookieを返します。 有効な値は、 最大5000バイトです。	JSON形式の文字列のリスト	✕

Scopeオブジェクト

Scopeオブジェクトは、メッセージの認可および識別の情報を提供します。オブジェクトは検出ディレクティブなどのペイロード、または非同期の応答メッセージなどのエンドポイントオブジェクトに含めることができます。

Scopeオブジェクトは、Alexaイベントゲートウェイに送信するメッセージに必要です。

以下の表は、Scopeオブジェクトに含まれるプロパティを示しています。

プロパティ	説明	型	必須
type	OAuthトークンのスコープの種類を指定します。 有効な値は、 BearerToken、BearerTokenWithPartition	文字列	◯
token	リンクされたユーザーアカウントを識別し、アクセスするためのOAuthベアラートークンです。	文字列	◯
partition	部屋の名前や番号など、リクエストの対象となる場所です。 BearerTokenWithPartitionでのみ有効です。	文字列	✕
userId	リクエストを行ったユーザーの一意のIDです。ユーザーの識別にこの値を使わないでください。代わりにtokenを使用します。 BearerTokenWithPartitionでのみ有効です。	文字列	✕

BearerTokenスコープ

BearerTokenスコープでは、リンクされたユーザーアカウントにアクセスするため、またはAlexaユーザーを識別するための、OAuthベアラートークンを提供します。スキルは認証中にトークンを受け取ります。通常は、スマートホームスキルまたはビデオスキルで使用されます。

以下は、BearerTokenスコープの例です。

BearerTokenWithPartitionスコープ

BearerTokenWithPartitionスコープでは、リンクされたユーザーアカウントにアクセスするため、および物理的な場所を指定するために、OAuthベアラートークンを提供します。通常は、Alexa for Businessを対象とするスキルで使用されます（日本未対応）。

以下は、BearerTokenWithPartitionスコープの例です。

Directiveオブジェクト

すべてのディレクティブには、Directiveオブジェクトが含まれます。

プロパティ	説明	型	必須
header	メッセージとインターフェースを識別します。	Headerオブジェクト	〇
endpoint	ユーザーが制御するエンドポイントを識別し、Alexaを認証する認可を提供します。	Endpointオブジェクト	◯
payload	ディレクティブの一部であるプロパティを指定します。	Payloadオブジェクト	〇

Eventオブジェクト

ディレクティブに対するすべてのイベントと応答には、Eventオブジェクトが含まれます。

プロパティ	説明	型	必須
header	メッセージとインターフェースを識別します。	Headerオブジェクト	〇
endpoint	エンドポイントを指定し、スキルを認証する認可を提供します。	Endpointオブジェクト	◯
payload	応答に必要なプロパティを指定します。ペイロードは、ディレクティブ、応答、イベントによって異なります。ペイロードのプロパティについて詳しくは、デバイスのインターフェースを参照してください。 メッセージにペイロードがない場合は、空のオブジェクトを設定します。	オブジェクト	◯

Contextオブジェクト

エンドポイントのすべてのレポート可能なプロパティを列挙するContextオブジェクトです。プロパティを追加するには、検出応答でretrievable = trueとしてプロパティを定義します。Amazonでは、変化のなかったプロパティも含めてすべてのプロパティの状態を指定することをお勧めします。

プロパティ	説明	型	必須
properties	エンドポイントの取得可能なプロパティを指定します。レポートされる各プロパティのPropertyオブジェクトを含めます。	Propertyオブジェクトの配列	✕

Payloadオブジェクト

ペイロードは、ディレクティブ、応答、イベントによって異なります。ペイロードのプロパティについて詳しくは、デバイスがサポートする各インターフェースのドキュメントを参照してください。

Propertyオブジェクト

Propertyオブジェクトは、エンドポイントのレポート可能なプロパティを定義します。各Alexaインターフェースでプロパティ名と値を定義します。詳細については、Alexaスキルでサポートする各インターフェースのドキュメントを参照してください。

以下の表は、Propertyオブジェクトのパラメーターを示しています。

プロパティ	説明	型	必須
namespace	Alexa.PowerControllerなど、プロパティが属するAlexa機能インターフェースの名前です。	文字列	◯
instance	検出応答で定義したインターフェースのインスタンス名です。汎用コントローラーインターフェースでのみ使用します。たとえば、Dryer.Temperatureなどです。	文字列	✕
name	namespaceに属するレポート対象プロパティの名前です。	文字列	◯
value	レポートされるプロパティの値です。各Alexaインターフェースで、valueフィールドの型を定義します。	バリエーション	〇
timeOfSample	エンドポイントが状態変更を検出した時刻です。 ISO 8601形式で定義し、YYYY-MM-DDThh:mm:ssZとなります。	文字列	◯
uncertaintyInMilliseconds	timeOfSampleフィールドの不確実性をミリ秒で指定します。 このフィールドは、エンドポイントが最後にプロパティ値を確認してからの経過時間（ミリ秒）を表します。たとえば、エンドポイントがプロパティ値のサンプリングを60秒前に行った場合、uncertaintyInMillisecondsには60000を設定します。	数値	〇

関連トピック

• 機能のプロパティのスキーマ
• フレンドリー名のリソースとアセット

---

---

最終更新日: 2022 年 05 月 25 日