機能API
Alexaは常に進化しており、新しいインターフェースの追加や既存のインターフェースの更新が行われているため、機能APIでは製品ごとにインターフェースとサポート対象のインターフェースのバージョンを指定できるようになっています。これにより、無線(OTA)アップデートを使用して、柔軟に具体的な製品をターゲットとすることができます。
使用例
以下は、機能APIの主な使用例です。
- 初回設定から起動時に、製品がどのインターフェースとインターフェースのバージョンをサポートしているかをAlexaに知らせます。このAPIの呼び出しは、アクセストークンの取得後、Alexa Voice Service(AVS)との接続が確立される前に行う必要があります。
- 無線(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
ディレクティブの
サポートされるインターフェースのバージョン
以下の表は、各インターフェースでサポートされるバージョンの一覧です。バージョン間の変更点は、導入時に各インターフェースのページに記載され、変更ログの記録に記録されます。詳細については、以下の表内のリンクからご覧ください。
製品がサポートするインターフェースとインターフェースのバージョンはすべて、各機能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 | 製品がサポートするインターフェースのバージョンです。重要:各インターフェースは個別にバージョン管理され、メッセージペイロードのコンテンツはバージョンによって異なります。 | 文字列 | 必須 |
リクエスト本文のサンプル
capabilities
リストに含める必要があります。{ "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}}" } }