Systemインターフェース

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

    サンプルメッセージ

      {
         "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"は有効なファームウェアバージョンではありません。
    有効 無効
    • "123"
    • "8701"
    • "20170207"
    • "50.3"
    • "avs-123.4x"
    • "ask.201-(1.23.4-test)"
    文字列

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

      サンプルメッセージ

      { "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 デバイスがディレクティブを処理中にエラーが発生し、そのエラーが指定されたカテゴリーに当てはまりません。