?
サポート

System インターフェース

Systemインターフェース

Systemインターフェースは、複数のクライアントコンポーネントに及ぶイベントを提供します。

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にリセットする必要があります。

サンプルメッセージ

{
   "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 Devicescurrent 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"は有効なファームウェアバージョンではありません。
有効 無効
  • "123"
  • "8701"
  • "20170207"
  • 123
  • 8701
  • "50.3"
  • "avs-123.4x"
  • "ask.201-(1.23.4-test)"
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 デバイスがディレクティブを処理中にエラーが発生し、そのエラーが指定されたカテゴリーに当てはまりません。

その他のインターフェース

このドキュメントの最初に戻り、サイドバーから、その他のインターフェースを参照してください。

リソース