機能API

Alexaは常に進化しており、新しいインターフェースの追加や既存のインターフェースの更新が行われているため、機能APIでは製品ごとにインターフェースとサポート対象のインターフェースのバージョンを指定できるようになっています。これにより、無線（OTA）アップデートを使用して、柔軟に具体的な製品をターゲットとすることができます。

使用例

以下は、機能APIの主な使用例です。

  1. 初回設定から起動時に、製品がどのインターフェースとインターフェースのバージョンをサポートしているかをAlexaに知らせます。このAPIの呼び出しは、アクセストークンの取得後、Alexa Voice Service（AVS）との接続が確立される前に行う必要があります。
  2. 無線（OTA）アップデート後に、製品がどのインターフェースとインターフェースのバージョンをサポートしているかをAlexaに知らせます。これにより、製品はAlexaに対して通知したインターフェースのバージョンに関連付けられたディレクティブとメッセージペイロードのみを受け取るようになります。

頻度

製品がサポートするインターフェースとインターフェースのバージョンをAlexaが認識しているという前提のもと、機能APIの呼び出し頻度はできるだけ少なくすることをお勧めします。

これらのガイドラインを参照し、製品がサポートする全インターフェースのリストを宣言する最適なタイミングを判断してください。

  • 製品に永続的なストレージがあり、ソフトウェアアップデートについて認識でき、以前宣言したインターフェースとインターフェースのバージョンを追跡できる場合、機能APIの呼び出しはインターフェースのバージョンが変更されたとき、またはサポートされるインターフェースが追加または削除された場合にのみ行うようにしてください。
  • 製品のストレージが限られており、インターフェースとインターフェースバージョンの前回の宣言について認識していない場合、機能APIはOTA後の起動時に呼び出すようにしてください。
  • 製品に永続的ストレージがない場合、機能APIはデバイスの起動時に呼び出すようにします。

呼び出しが正常に完了すると、製品はHTTP 204応答を受け取ります。HTTP 500応答が返された場合、製品は1秒後に再試行され、その後256秒が経過するまで指数関数的に間隔を増やして再試行し、HTTP 204応答を受け取るまで256秒ごとに再試行します。

バージョン管理

新しいディレクティブとイベントがインターフェースに追加されたり、インターフェースから削除されたとき、またはメッセージペイロードが調整されたときに、影響を受けるインターフェースは、メジャーマイナーのスキームを使用して個別にバージョン管理されます。

マイナーバージョンの変更

下位互換性があり、互換性に影響しない変更の場合、インターフェースバージョンのマイナー番号が増加します。マイナーバージョンの変更は通常、以下の場合に行われます。

  • 新しいディレクティブやイベントがインターフェースに追加された場合。
  • ディレクティブやイベントのメッセージペイロードにパラメーターが追加された場合。

たとえば、名前付きのタイマーとリマインダーをサポートするよう変更された場合、Alertsインターフェースのバージョン番号は、1.0から1.1に増加します。この変更により、拡張機能のための新しいペイロードパラメーターがSetAlertに導入されます。ただ、下位互換性は維持され、既存のクライアントが使えなくなることはありません。

メジャーバージョンの変更

互換性に影響する変更が導入される場合、インターフェースバージョンのメジャー番号が増加します。以下は、メジャーバージョンが変更される場合の例です。

  • 既存のディレクティブやイベントがインターフェースから削除された場合。
  • 既存のパラメーターの型が変更された場合。
  • ディレクティブやイベントのメッセージペイロードからパラメーターが削除された場合。

たとえば、ExpectSpeechディレクティブのinitiatorディレクティブのパラメーターの型が文字列からオブジェクトに変更された場合、SpeechRecognizerインターフェースのバージョンは1.0から2.0に上げられます。

サポートされるインターフェースのバージョン

以下の表は、各インターフェースでサポートされるバージョンの一覧です。バージョン間の変更点は、導入時に各インターフェースのページに記載され、変更ログの記録に記録されます。詳細については、以下の表内のリンクからご覧ください。

製品がサポートするインターフェースとインターフェースのバージョンはすべて、各機能API呼び出しに含める必要があります。機能APIへの呼び出しが正常に完了したら、Alexaは次に機能APIが呼び出されるまで、各インターフェースの宣言されたバージョンを使用します。

インターフェース 現行バージョン サポートされるバージョン 必須
Alerts☩ 1.1 1.0、1.1 必須
AudioActivityTracker 1.0 1.0 フォーカス管理では必須
AudioPlayer 1.0 1.0 必須
Bluetooth☩ 1.0 1.0 任意
Notifications 1.0 1.0 必須
PlaybackController 1.0 1.0 必須
Settings 1.0 1.0 必須
Speaker 1.0 1.0 必須
SpeechRecognizer 2.0 1.0、2.0 必須
SpeechSynthesizer 1.0 1.0 必須
System 1.0 1.0 必須
TemplateRuntime☩ 1.0 1.0 任意
VisualActivityTracker 1.0 1.0 フォーカス管理では必須

リクエスト

メソッド PUT
URI https://api.amazonalexa.com/v1/devices/@self/capabilities
データ形式 JSON

ヘッダーのパラメーター

パラメーター 説明 型 必須
Content-Type Alexaから返されるメッセージの形式を指定します。有効な値は、application/jsonです。 文字列 必須
Content-Length Alexaに送られるエンティティの本文のサイズをバイトで指定します。 整数 必須
Authorization 認可中にLogin with Amazon（LWA）から取得したアクセストークンです。AVSの認可オプションの全リストについては、認可を参照してください。 文字列 必須

リクエストヘッダーのサンプル

Content-Type: application/json
Content-Length: {{INTEGER}}
Authorization: {{LWA_ACCESS_TOKEN}}

本文のパラメーター

パラメーター 説明 型 必須
envelopeVersion この値により、APIの特定のバージョンを使用していることをAlexaに知らせます。その結果、Alexaによって返されるメッセージは宣言されたバージョンのメッセージ仕様に従います。有効な値は、20160207です。 文字列 必須
capabilities それぞれがインターフェースを表すオブジェクトのリストです。製品がサポートするすべてのインターフェースをこのリストに含める必要があります。インターフェースが宣言されていない場合、Alexaはインターフェースを使用できるかどうかを判断してから、どのバージョンのメッセージが送信されたかを判断します。詳細を見る > リスト 必須
capabilities[i].type 有効な値：AlexaInterface。 文字列 必須
capabilities[i].interface Alexaのインターフェースを指定します。有効な値：Alexa Voice Serviceの概要に記載されているすべてのインターフェースです。 文字列 必須
capabilities[i].version 製品がサポートするインターフェースのバージョンです。重要：各インターフェースは個別にバージョン管理され、メッセージペイロードのコンテンツはバージョンによって異なります。 文字列 必須

リクエスト本文のサンプル

{
    "envelopeVersion": "20160207",
    "capabilities": [
        {
            "type": "AlexaInterface",
            "interface": "Alerts",
            "version": "1.1"
        },
        {
            "type": "AlexaInterface",
            "interface": "AudioActivityTracker",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "AudioPlayer",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Bluetooth",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Notifications",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "PlaybackController",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Settings",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "Speaker",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "SpeechRecognizer",
            "version": "2.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "SpeechSynthesizer",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "System",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "TemplateRuntime",
            "version": "1.0"
        },
        {
            "type": "AlexaInterface",
            "interface": "VisualActivityTracker",
            "version": "1.0"
        }
        ...
        // This should be a complete list of
        // interfaces that your product supports.
        // All required interfaces must be declared.
    ]
}

応答

Alexaはすべてのリクエストに対してHTTPステータスコードで応答します。

ステータスコード

HTTPステータスコード メッセージ 説明
204 コンテンツなし リクエストは正常に処理されました。
400 Bad request ペイロードに問題がありました。400エラーは、エラーオブジェクトとエラーの詳細を含むJSONドキュメントを返します。
403 Forbidden 認証に失敗しました。
500 Internal Service Error 機能の処理または格納中に未知の問題が発生しました。1秒後に再試行され、その後256秒が経過するまで指数関数的に間隔を増やして再試行し、HTTP 204応答を受け取るまで256秒ごとに再試行します。

エラーメッセージ

400エラーは、1つのエラーオブジェクトとエラーの詳細を含むJSONドキュメントを返します。

エラーメッセージ 説明
"Invalid envelope version" envelopeVersionに対して無効なパラメーターが渡されました。
"Missing capabilities" 機能リストがありません。
"{field} cannot be null or empty" 宣言されたtype、interface、versionのいずれか、またはすべてが無効です。
"Unknown interface {name}, type {x}, version {number} combination" 渡されたtype、interface、versionの組み合わせが無効です。

400エラーの構造

{
    "error": {
        "message": "{{STRING}}"
    }
}
Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment