HTTP2 リクエストの構成



概要

AVS APIのバージョン:
v20160207

Alexa Voice Service(AVS)との接続が確立されると、クライアントはAlexaと、HTTP/2エンコードされたマルチパートメッセージを使用して通信します。Alexaから送信されたディレクティブ同様、クライアントから送信されたイベントも、サーバーまたはクライアントが実行する必要のあるアクションを示します。以下の図は、AVSに送信されるRecognizeイベントを示しています。マルチパートメッセージは、2つのパートで構成されます。1つ目はJSON形式のイベント、2つ目は製品のマイクからキャプチャされたオーディオです。

Message Structure
クリックして拡大

接続の作成と維持の詳細については、HTTP/2接続の管理を参照してください。

HTTP/2メッセージヘッダー

すべてのAVSの呼び出しには、以下のヘッダーが必要です。

:method = {{verb}}
:scheme = https
:path = /{{API version}}/{{events or directives}}
authorization = Bearer {{access_token}}
content-type = multipart/form-data; boundary={{boundary_term}}

メソッド

AVSでは、以下のメソッドがサポートされます。

  • POST は、イベントのパスを使用して、AVSに送信されるすべてのイベントに使用します。
  • GET は、ディレクティブのパスを使用してダウンチャネルを確立するために使用します。

スキーム

AVS APIへのアクセスに使用するスキームは、httpsです。

パス

すべてのイベントは以下のパスを使用します。

:path = /v20160207/events

すべてのディレクティブは以下のパスを使用します。

:path = /v20160207/directives

認可

ユーザーが、自身に代わって製品がAlexaにアクセスすることを認可すると、Login with Amazonは、その後AVSの呼び出しに使用するaccess_tokenを返します。access_tokenは、各リクエストのヘッダーに含まれる必要があります。

authorization = Bearer {{access_token}}

コンテンツタイプ

Content-Type は、本文に含まれるデータを示します。これにより、AVSがリクエストを適切に処理できます。マルチパートメッセージを複数のパートに区切る際には、バウンダリ文字列が使用されます。この場合、Alexa、JSON、バイナリオーディオのパートがあります。

Content-Type は、常にmultipart/form-dataである必要があります。バウンダリ文字列は、自由に決めてかまいません。唯一の要件は、使用するバウンダリ文字列に一貫性があること、およびデータにはバウンダリ文字列を使用しないことです。

content-type = multipart/form-data; boundary={{boundary_term}}

HTTP/2マルチパートメッセージ

AVSでは、HTTP/2エンコードされたマルチパートメッセージが想定されています。マルチパートメッセージは、1つ以上のJSON形式のディレクティブ/イベントと、(必要な場合)関連するバイナリオーディオ添付ファイルで構成されます。このセクションでは、AVSに送信されるマルチパートメッセージの構成を確認します。

JSONヘッダー

以下のヘッダーは、各マルチパートリクエストのJSONのパートに必要です。

Content-Disposition: form-data; name="metadata"
Content-Type: application/json; charset=UTF-8

JSONコンテンツ

AVSに送信されるすべてのJSON形式のイベントは、以下の形式で記述されます。

{
    "event":{
        "header": {
            "namespace": "{{STRING}}",
            "name": "{{STRING}}",
            "messageId": "{{STRING}}",
        },
        "payload": {
        }
    }
}

各イベントには、固有のヘッダーとペイロードがあります。ヘッダーでは、namespaceとnameがインターフェースとイベントを示し、messageIdにクライアントが各リクエストとともに送信する必要のある一意の識別子が入ります。その他の情報やサンプルについては、APIの概要を参照してください。

バイナリオーディオヘッダー

以下のヘッダーは、各マルチパートリクエストのバイナリオーディオ添付ファイルのパートに必要です。

Content-Disposition: form-data; name="audio"
Content-Type: application/octet-stream

バイナリオーディオコンテンツ

マルチパートメッセージのこのパートは、バイナリオーディオです。オーディオ添付ファイルを必要とするイベントは、Recognizeイベントのみです。詳細情報については、SpeechRecognizerインターフェースを参照してください。

HTTP/2の応答

AVSは、クライアントに2種類の応答を送信します。1つ目は、リクエストと同様にマルチパートメッセージです。1つ以上のJSON形式のディレクティブと、(必要な場合)関連するバイナリオーディオ添付ファイルで構成されます。2つ目は、例外です。例外は、マルチパートメッセージではなく、エラーが発生したときにクライアントに返されます。例外には、それぞれエラーコード説明が含まれます。

その他の情報については、例外を参照してください。

例1:
この例では、応答としてSpeakディレクティブを受信するRecognizeイベントを示します。

クリックして拡大 +

例2:
この例では、応答としてSpeakディレクティブとListenディレクティブを1つずつ受信するRecognizeイベントを示します。

クリックして拡大 +

リソース