System インターフェース
Systemインターフェースは、複数のクライアントコンポーネントに及ぶイベントを提供します。
- SynchronizeStateイベント
- UserInactivityReportイベント
- ResetUserInactivityディレクティブ
- SetEndpointディレクティブ
- SoftwareInfoイベント
- ReportSoftwareInfoディレクティブ
- ExceptionEncounteredイベント
- その他のインターフェース
- リソース
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。 | string |
ペイロードのパラメーター
なし
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。 | string |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| inactiveTimeInSeconds | 前回のユーザーとの対話からの時間（秒） | long |
ResetUserInactivityディレクティブ
ResetUserInactivityディレクティブは、UserInactivityReportによって使用される非アクティブタイマーをリセットするために、クライアントに送信されます。たとえば、Amazon Alexaアプリ上でのユーザーとの対話によってこのディレクティブがトリガーされます。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "ResetUserInactivity",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のID。 | string |
SetEndpointディレクティブ
SetEndpointディレクティブは、クライアントに、以下の条件を満たす場合にエンドポイントを変更するよう指示します。
- ユーザーのcountry settingsが、接続先のエンドポイントでサポートされていない場合。たとえば、Manage Your Content and Devicesのcurrent countryが、英国（UK）に設定されており、クライアントが米国（US）のエンドポイントに接続した場合、英国をサポートするエンドポイントに接続するよう指示する
SetEndpointディレクティブがクライアントに対して送信されます。 - ユーザーがcountry settings（または住所）を変更した場合。たとえば、米国のエンドポイントに接続しているユーザーがcurrent countryを米国から英国に変更した場合、英国をサポートするエンドポイントに接続するよう指示する
SetEndpointディレクティブがクライアントに対して送信されます。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "SetEndpoint",
"messageId": "{{STRING}}"
},
"payload": {
"endpoint": "{{STRING}}"
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | 特定のメッセージを表すのに使用される一意のID。 | string |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| endpoint | ユーザーの国設定をサポートするAVSエンドポイントのURL。エンドポイントのURLには、プロトコルおよび/またはポートが含まれる場合があります。 例: https://avs-alexa-na.amazon.com |
string |
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）。 | string |
ペイロードのパラメーター
| パラメーター | 説明 | 型 | ||||
|---|---|---|---|---|---|---|
| firmwareVersion | string型で表される32ビットの順序数。無効な値がAlexaに送信されると、クライアントにHTTP 400ステータスコードが返されます。重要: "0"は有効なファームウェアバージョンではありません。
|
string |
ReportSoftwareInfoディレクティブ
このディレクティブは、製品に対して現在のソフトウェア情報をSoftwareInfoイベントを使用してAlexaに報告するよう指示します。
サンプルメッセージ
{
"directive": {
"header": {
"namespace": "System",
"name": "ReportSoftwareInfo",
"messageId": "{{STRING}}"
},
"payload": {
}
}
}
ヘッダーのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| messageId | RFC 4122仕様で生成されるuniversally unique identifier（UUID）。 | string |
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。 | string |
ペイロードのパラメーター
| パラメーター | 説明 | 型 |
|---|---|---|
| unparsedDirective | ディレクティブを実行できないとき、クライアントはAVSに対してディレクティブを文字列として返す必要があります。 | string |
| error | エラーのキー/値ペア。 | object |
| error.type | ディレクティブを実行できないときに、クライアントがAVSに返す必要があるエラー。 | string |
| error.message | ログやトラブルシューティング用のその他のエラー詳細。 | string |
エラータイプ
| エラータイプ | 説明 |
|---|---|
| UNEXPECTED_INFORMATION_RECEIVED | クライアントに送信されたディレクティブの形式が正しくない、またはペイロードがディレクティブの仕様に準拠していません。 |
| INTERNAL_ERROR | デバイスがディレクティブを処理中にエラーが発生し、そのエラーが指定されたカテゴリーに当てはまりません。 |
その他のインターフェース
このドキュメントの最初に戻り、サイドバーから、その他のインターフェースを参照してください。