機能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が呼び出されるまで、各インターフェースの宣言されたバージョンを使用します。

リクエスト

ヘッダーのパラメーター

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

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

本文のパラメーター

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

{
    "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ステータスコードで応答します。

ステータスコード

エラーメッセージ

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

400エラーの構造

{
    "error": {
        "message": "{{STRING}}"
    }
}