Systemインターフェース
Systemインターフェースは、複数のクライアントコンポーネントに及ぶイベントを提供します。
バージョンの変更点
SoftwareInfoイベントを送信してReportSoftwareInfoディレクティブを受信するには、機能APIを使用してバージョン1.1の宣言をする必要があります。
機能API
バージョン1.1のSystemインターフェースを使用するには、機能APIの呼び出し内で宣言する必要があります。その他の詳細については、機能APIを参照してください。
オブジェクトのサンプル
{
"type": "AlexaInterface",
"interface": "System",
"version": "1.1"
}
SynchronizeStateイベント
SynchronizeStateイベントは、新しい接続が確立されたときに、すべての製品コンポーネントの状態を更新するためにAVSに送信される必要があります。
サンプルメッセージ
{
"context": [
// This is an array of context objects that are used to communicate the
// state of all client components to Alexa. See Context for details.
],
"event": {
"header": {
"namespace": "System",
"name": "SynchronizeState",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
コンテキスト
このイベントでは、製品がAlexaに対して、すべてのクライアントコンポーネントのステータスをコンテキストオブジェクトに格納して報告しなければならない。その他の情報については、コンテキストを参照してください。
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
空のペイロードを送信する必要があります。
UserInactivityReportイベント
このイベントは非アクティブな1時間が経過した後、ユーザーのアクションが行われるまでの間1時間ごとに送信される必要があります。このイベントにより、Alexaに最後に操作が検知されてからの経過時間が提供されます。ユーザー操作は製品内にユーザーが存在していると確認できるアクションとして定義されます。たとえば、製品上のボタンの操作、Alexaとの対話、GUIアフォーダンスの使用などです。ユーザー操作が検知されたら、非アクティブ状態のトラッキングに使用するタイマーを0にリセットする必要があります。
inactiveTimeInSecondsに提供される値は、常に3600（1時間）の倍数になる必要があります。たとえば、非アクティブな時間が4時間の場合、値は14400となります。サンプルメッセージ
{
"event": {
"header": {
"namespace": "System",
"name": "UserInactivityReport",
"messageId": "{{STRING}}"
},
"payload": {
"inactiveTimeInSeconds": {{LONG}}
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| inactiveTimeInSeconds | 前回のユーザーとの対話からの時間（秒）です。 | long |
ResetUserInactivityディレクティブ
ResetUserInactivityディレクティブは、UserInactivityReportによって使用される非アクティブタイマーをリセットするために、クライアントに送信されます。たとえば、Amazon Alexaアプリ上でのユーザーとの対話によってこのディレクティブがトリガーされます。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "ResetUserInactivity",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
SetEndpointディレクティブ
以下の状況に該当する場合、SetEndpointディレクティブはクライアントにエンドポイントを変更するよう指示します。
- ユーザーの国／地域の設定が、接続された先のエンドポイントでサポートされていない場合。たとえば、Amazonサイト上の「コンテンツと端末の管理」ページでユーザーの国／地域の設定が英国（UK）に設定されており、クライアントが米国（US）のエンドポイントに接続した場合、
SetEndpointディレクティブが送信されてクライアントにUKをサポートするエンドポイントに接続するよう指示します。 - ユーザーが国／地域の設定（または住所）を変更した場合。たとえば、USのエンドポイントに接続したユーザーが国／地域の設定をUSからUKに変更すると、
SetEndpointディレクティブが送信されてクライアントにUKをサポートするエンドポイントに接続するよう指示します。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "SetEndpoint",
"messageId": "{{STRING}}"
},
"payload": {
"endpoint": "{{STRING}}"
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| endpoint | ユーザーの国／地域設定をサポートするAVSエンドポイントのURLです。エンドポイントのURLには、プロトコルおよび／またはポートが含まれる場合があります。 例： https://avs-alexa-na.amazon.com |
文字列 |
SoftwareInfoイベント
このイベントは、ファームウェアのバージョンなど、製品のソフトウェア情報をAlexaに伝えます。以下のようなシナリオで送信される必要があります。
- 永続性メモリを持つ製品の場合、イベントは製品の初回起動時と、ファームウェアバージョンがアップデートされるたびに送信される必要があります。
- 永続性メモリを持たない製品の場合、イベントは製品の起動／再起動時に送信される必要があります。
ReportSoftwareInfoディレクティブの受信時。
イベントが正常に処理されたら、製品は204のHTTPステータスコード（本文は空）を受信します。イベントが処理されない場合、製品は500のHTTPステータスコードと例外メッセージを受信します。
サンプルメッセージ
{
"event": {
"header": {
"namespace": "System",
"name": "SoftwareInfo",
"messageId": "{{STRING}}"
},
"payload": {
"firmwareVersion": "{{STRING}}"
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | RFC 4122仕様で生成されるuniversally unique identifier（UUID）です。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 | ||||
|---|---|---|---|---|---|---|
| firmwareVersion | 文字列として表される正符号付き32ビット整数です。無効な値がAlexaに送信されると、クライアントにHTTP 400ステータスコードが返されます。重要："0"は有効なファームウェアバージョンではありません。
|
文字列 |
ReportSoftwareInfoディレクティブ
このディレクティブは、製品に対して現在のソフトウェア情報をSoftwareInfoイベントを使用してAlexaに報告するよう指示します。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "ReportSoftwareInfo",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | RFC 4122仕様で生成されるuniversally unique identifier（UUID）です。 | 文字列 |
ExceptionEncounteredイベント
AVSからのディレクティブを実行できないとき、クライアントはこのイベントを送信する必要があります。
サンプルメッセージ
{
"context": [
// This is an array of context objects that are used to communicate the
// state of all client components to Alexa. See Context for details.
],
"event": {
"header": {
"namespace": "System",
"name": "ExceptionEncountered",
"messageId": "{{STRING}}"
},
"payload": {
"unparsedDirective": "{{STRING}}",
"error": {
"type": "{{STRING}}"
"message": "{{STRING}}"
}
}
}
}
コンテキスト
このイベントでは、製品がAlexaに対して、すべてのクライアントコンポーネントのステータスをコンテキストオブジェクトに格納して報告しなければならない。その他の情報については、コンテキストを参照してください。
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| unparsedDirective | ディレクティブを実行できないとき、クライアントはAVSに対してディレクティブを文字列として返す必要があります。 | 文字列 |
| error | エラーのキー／値ペアです。 | object |
| error.type | ディレクティブを実行できないときに、クライアントがAVSに返す必要があるエラーです。 | 文字列 |
| error.message | ログやトラブルシューティング用のその他のエラー詳細です。 | 文字列 |
エラータイプ
| エラータイプ | 説明 |
|---|---|
| UNEXPECTED_INFORMATION_RECEIVED | クライアントに送信されたディレクティブの形式が正しくない、またはペイロードがディレクティブの仕様に準拠していません。 |
| INTERNAL_ERROR | デバイスがディレクティブを処理中にエラーが発生し、そのエラーが指定されたカテゴリーに当てはまりません。 |
Systemインターフェースは、複数のクライアントコンポーネントに及ぶイベントを提供します。
バージョンの変更点
- ドキュメントの誤りを修正しました。
SoftwareInfoイベントとReportSoftwareInfoディレクティブがSystemインターフェースのバージョン1.1に移動されました。バージョンを切り替えるには、このページの上部にあるバージョン選択をお試しください。
機能API
バージョン1.0のSystemインターフェースを使用するには、機能APIの呼び出し内で宣言する必要があります。その他の詳細については、機能APIを参照してください。
オブジェクトのサンプル
{ "type": "AlexaInterface", "interface": "System", "version": "1.0" }
SynchronizeStateイベント
SynchronizeStateイベントは、新しい接続が確立されたときに、すべての製品コンポーネントの状態を更新するためにAVSに送信される必要があります。
サンプルメッセージ
{ "context": [ // This is an array of context objects that are used to communicate the // state of all client components to Alexa.See Context for details.], "event": { "header": { "namespace": "System", "name": "SynchronizeState", "messageId": "" }, "payload": { } } }
コンテキスト
このイベントでは、製品がAlexaに対して、すべてのクライアントコンポーネントのステータスをコンテキストオブジェクトに格納して報告しなければならない。その他の情報については、コンテキストを参照してください。
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
空のペイロードを送信する必要があります。
UserInactivityReportイベント
このイベントは非アクティブな1時間が経過した後、ユーザーのアクションが行われるまでの間1時間ごとに送信される必要があります。このイベントにより、Alexaに最後に操作が検知されてからの経過時間が提供されます。ユーザー操作は製品内にユーザーが存在していると確認できるアクションとして定義されます。たとえば、製品上のボタンの操作、Alexaとの対話、GUIアフォーダンスの使用などです。ユーザー操作が検知されたら、非アクティブ状態のトラッキングに使用するタイマーを0にリセットする必要があります。
inactiveTimeInSecondsに提供される値は、常に3600（1時間）の倍数になる必要があります。たとえば、非アクティブな時間が4時間の場合、値は14400となります。サンプルメッセージ
{ "event": { "header": { "namespace": "System", "name": "UserInactivityReport", "messageId": "" }, "payload": { "inactiveTimeInSeconds": } } }
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| inactiveTimeInSeconds | 前回のユーザーとの対話からの時間（秒）です。 | long |
ResetUserInactivityディレクティブ
ResetUserInactivityディレクティブは、UserInactivityReportによって使用される非アクティブタイマーをリセットするために、クライアントに送信されます。たとえば、Amazon Alexaアプリ上でのユーザーとの対話によってこのディレクティブがトリガーされます。
サンプルメッセージ
{ "directive": { "header": { "namespace": "System", "name": "ResetUserInactivity", "messageId": "" }, "payload": { } } }
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
SetEndpointディレクティブ
以下の状況に該当する場合、SetEndpointディレクティブはクライアントにエンドポイントを変更するよう指示します。
- ユーザーの国／地域の設定が、接続された先のエンドポイントでサポートされていない場合。たとえば、Amazonサイト上の「コンテンツと端末の管理」ページでユーザーの国／地域の設定が英国（UK）に設定されており、クライアントが米国（US）のエンドポイントに接続した場合、
SetEndpointディレクティブが送信されてクライアントにUKをサポートするエンドポイントに接続するよう指示します。 - ユーザーが国／地域の設定（または住所）を変更した場合。たとえば、USのエンドポイントに接続したユーザーが国／地域の設定をUSからUKに変更すると、
SetEndpointディレクティブが送信されてクライアントにUKをサポートするエンドポイントに接続するよう指示します。
サンプルメッセージ
{ "directive": { "header": { "namespace": "System", "name": "SetEndpoint", "messageId": "" }, "payload": { "endpoint": "" } } }
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| endpoint | ユーザーの国／地域設定をサポートするAVSエンドポイントのURLです。エンドポイントのURLには、プロトコルおよび／またはポートが含まれる場合があります。 例： https://avs-alexa-na.amazon.com |
文字列 |
ExceptionEncounteredイベント
AVSからのディレクティブを実行できないとき、クライアントはこのイベントを送信する必要があります。
サンプルメッセージ
{ "context": [ // This is an array of context objects that are used to communicate the // state of all client components to Alexa.See Context for details.], "event": { "header": { "namespace": "System", "name": "ExceptionEncountered", "messageId": "" }, "payload": { "unparsedDirective": "", "error": { "type": "" "message": "" } } } }
コンテキスト
このイベントでは、製品がAlexaに対して、すべてのクライアントコンポーネントのステータスをコンテキストオブジェクトに格納して報告しなければならない。その他の情報については、コンテキストを参照してください。
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のIDです。 | 文字列 |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| unparsedDirective | ディレクティブを実行できないとき、クライアントはAVSに対してディレクティブを文字列として返す必要があります。 | 文字列 |
| error | エラーのキー／値ペアです。 | object |
| error.type | ディレクティブを実行できないときに、クライアントがAVSに返す必要があるエラーです。 | 文字列 |
| error.message | ログやトラブルシューティング用のその他のエラー詳細です。 | 文字列 |
エラータイプ
| エラータイプ | 説明 |
|---|---|
| UNEXPECTED_INFORMATION_RECEIVED | クライアントに送信されたディレクティブの形式が正しくない、またはペイロードがディレクティブの仕様に準拠していません。 |
| INTERNAL_ERROR | デバイスがディレクティブを処理中にエラーが発生し、そのエラーが指定されたカテゴリーに当てはまりません。 |