カスタムスキルのJSONインターフェースのリファレンス
Alexa Skills Kitを利用すると、クラウドベースのサービスを構築してAlexaに新しい機能を追加できます。構築できるサービスは、ウェブサービスまたはAWS Lambda関数のいずれかになります。この文書では、作成したウェブサービスまたはLambda関数とAlexaサービスとの間のプロトコルインターフェースについて詳しく説明します。AWS Lambdaは、Amazon Web Servicesによって提供されるサービスです。
Alexaと作成したサービスとの通信は、SSL/TLSを利用してHTTPを使用するリクエスト-応答の仕組みを介して行います。ユーザーがAlexaスキルと対話するとき、作成したサービスは、JSON本文を含むPOSTリクエストを受け取ります。このリクエスト本文には、サービスがロジックを実行してJSON形式の応答を生成するために必要なプロパティが含まれています。
リクエストの形式
ここでは、サービスに送信されるリクエストのフォーマットについて説明します。
HTTPヘッダー
POST / HTTP/1.1
Content-Type : application/json;charset=UTF-8
Host : your.application.endpoint
Content-Length :
Accept : application/json
Accept-Charset : utf-8
Signature:
SignatureCertChainUrl: https://s3.amazonaws.com/echo.api/echo-api-cert.pem
リクエスト本文の構文
サービスに送信されるリクエスト本文は、JSON形式で記述されます。この例では、AudioPlayerディレクティブをリクエストしましたが、Display.RenderTemplateディレクティブとVideoApp.Launchディレクティブをまだリクエストしていません。また、この例にはAdvertisingプロパティが含まれています。
{
"version": "1.0",
"session": {
"new": true,
"sessionId": "amzn1.echo-api.session.[unique-value-here]",
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"attributes": {
"key": "string value"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA..."
}
},
"context": {
"System": {
"device": {
"deviceId": "string",
"supportedInterfaces": {
"AudioPlayer": {}
},
"persistentEndpointId": "amzn1.alexa.endpoint.[unique-value-here]"
},
"application": {
"applicationId": "amzn1.ask.skill.[unique-value-here]"
},
"user": {
"userId": "amzn1.ask.account.[unique-value-here]",
"accessToken": "Atza|AAAAAAAA..."
},
"person": {
"personId": "amzn1.ask.person.[unique-value-here]",
"accessToken": "Atza|BBBBBBB..."
},
"unit": {
"unitId": "amzn1.ask.unit.[unique-value-here]",
"persistentUnitId": "amzn1.alexa.unit.did.[unique-value-here]"
},
"apiEndpoint": "https://api.fe.amazonalexa.com",
"apiAccessToken": "AxThk..."
},
"Advertising": {
"advertisingId": "296D263C-87BC-86A3-18A7-D307393B83A9",
"limitAdTracking": false
},
"AudioPlayer": {
"playerActivity": "PLAYING",
"token": "audioplayer-token",
"offsetInMilliseconds": 0
}
},
"request": {}
}
リクエスト本文のプロパティ
すべてのリクエストには、version、context、requestオブジェクトがトップレベルで含まれています。sessionオブジェクトは、すべての標準のリクエストタイプに含まれていますが、AudioPlayer、VideoApp、PlaybackControllerリクエストには含まれていません。
| プロパティ | 説明 | 型 |
|---|---|---|
|
|
リクエストのバージョン指定子です。値は |
|
|
|
リクエストに関連付けられた追加のコンテキストを提供します。
|
|
|
|
リクエストがサービスに送信された時点でのAlexaサービスとデバイスの現在の状態をスキルに提供します。このオブジェクトは、すべてのリクエストに含まれています。セッションのコンテキストで送信されたリクエスト（ contextオブジェクトの定義については、Contextオブジェクトを参照してください。 |
|
|
|
ユーザーのリクエストの詳細を提供します。以下に示す、いくつかの異なるリクエストタイプを利用できます。 標準のリクエストタイプ 特定のインターフェースと関連付けられているリクエスト： |
|
リクエストロケール
あらゆるrequestオブジェクトには、localeプロパティが含まれています。これはユーザーのロケールを示す 、日本語（JP）のja-JPなどのstring型ロケールコードです。スキルが応答する言語を決定するのに使用します。
サポートされているロケール：
| ロケールコード | 言語 |
|---|---|
|
|
アラビア語（SA） |
|
|
ドイツ語（DE） |
|
|
英語（AU） |
|
|
英語（CA） |
|
|
英語（UK） |
|
|
英語（IN） |
|
|
英語（US） |
|
|
スペイン語（ES） |
|
|
スペイン語（MX） |
|
|
スペイン語（US） |
|
|
フランス語（CA） |
|
|
フランス語（FR） |
|
|
ヒンディー語（IN） |
|
|
イタリア語（IT） |
|
|
日本語（JP） |
|
|
ポルトガル語（BR） |
複数言語のサポートの詳細については、多言語に対応するスキルを開発するを参照してください。
Sessionオブジェクト
標準のリクエストタイプ（CanFulfillIntentReqeuest、LaunchRequest、IntentRequest、SessionEndedRequest）には、sessionオブジェクトが含まれます。[GameEngineインターフェース][game-engine-interface-reference]にも、sessionオブジェクトが含まれます。
AudioPlayerやPlaybackControllerなどのインターフェースからのリクエストはセッションのコンテキストで送信されるものではないため、それらのリクエストにsessionオブジェクトは含まれません。context.System.userオブジェクトとcontext.System.applicationオブジェクトが提供するユーザーとアプリケーションに関する情報は、sessionに含まれる同じオブジェクトが提供する情報と同じです。Context objectを参照してください。
| プロパティ | 説明 | 型 |
|---|---|---|
|
|
新しいセッションかどうかを示します。新しいセッションの場合は |
|
|
|
ユーザーのアクティブセッションでの一意の識別子を表します。 注：
sessionIdは、同じユーザーの同じセッションでは、その後の複数のリクエストでも変わることはありません。あるユーザーのセッションが終了した場合、同じユーザーのその後のリクエストには、新しい一意のsessionId値が提供されます。 |
|
|
|
キーと値のペアのマップです。プロパティ
応答を返すときに、同一セッション内で保持する必要があるデータを |
|
|
|
アプリケーションIDを含みます。このオブジェクトはリクエストがそのサービスに対するものかどうかを検証するために使われます。
この情報は、 スキルのアプリケーションIDは、スキルのリストに移動してそのスキルのスキルIDの表示をクリックすると確認できます。 |
|
|
|
スキルを有効にしているAmazonアカウントを表します。
nullの場合、 この情報は、 |
|
Contextオブジェクト
contextオブジェクトは、リクエストがサービスに送信された時点でのAlexaサービスとデバイスの現在の状態をスキルに提供します。このオブジェクトは、すべてのリクエストに含まれています。セッションのコンテキストで送信されたリクエスト（CanFulfillIntentRequest、LaunchRequest、およびIntentRequest）では、sessionオブジェクトからも取得できるuser情報およびapplication情報がcontextオブジェクトに重複して含まれています。
| プロパティ | 説明 | 型 |
|---|---|---|
|
|
（任意）ユーザーの広告IDと、興味・関心に基づく広告の受け取りに関する詳細設定を提供します。スキルが広告を配信することを宣言しているスキルへのリクエストに含められます。 |
|
|
|
現在画面に表示されているAlexa Presentation Languageのドキュメントに関する情報を提供します。これは、ユーザーのデバイスに画面があり、ユーザーの操作がスキルにリクエストをトリガーしたときに、APLドキュメントが画面にレンダリングされている場合に含まれます。 APLの詳細については、スキルに視覚要素とオーディオを追加するを参照してください。 |
|
|
|
|
|
|
|
Alexaサービスと、スキルと対話しているデバイスの現在の状態に関する情報を提供します。 |
|
|
|
ユーザーのデバイスに画面がある場合に含まれます。 |
|
|
|
ユーザーのデバイスに画面またはキャラクターディスプレイがある場合に含まれます。使用可能な画面またはディスプレイに関する情報を提供するオブジェクトが含まれています。詳細については、Alexa.Presentation.APLTインターフェースリファレンスのスキルリクエストのViewportオブジェクトを参照してください。 |
|
Systemオブジェクト
| プロパティ | 説明 | 型 |
|---|---|---|
|
|
Alexa固有のAPIにアクセスするためのトークンを含みます。このトークンは以下をカプセル化します。
このトークンは、スキルに送信するすべてのリクエストに含まれます。このトークンを使用してアクセス権限を必要とするAPIにアクセスする場合、スキルはAPIを呼び出して返すコードを確認する必要があります。 |
|
|
|
デバイスの位置情報APIやプログレッシブ応答APIなどのAPIで使用するための、地域に応じた正しいベースURIを参照します。 |
|
|
|
アプリケーションIDを含みます。このIDを使用してリクエストがそのサービスに対するものかどうかを検証します。
この情報は、 アプリケーションIDは、開発者コンソールに表示されます。カスタム > エンドポイントページのAWS Lambda ARNを選択すると確認できます。スキル一覧のスキル名の下にも表示されます。 |
|
|
|
リクエストの送信に使用されたデバイスについての情報を提供します。
|
|
|
|
Alexaシステムとやり取りするアクター（人や組織など）とリソース（デバイスやスキルなど）を整理する論理構造を表します。
|
|
|
|
Alexaにリクエストしているユーザーを表します。
nullの場合、 |
|
|
|
スキルを有効にしているAmazonアカウントを表します。
nullの場合、 この情報は、 |
|
advertisingオブジェクト
advertisingオブジェクトは、ユーザーの広告IDと、興味・関心に基づく広告の受け取りに関するカスタマイズ設定を提供します。Alexaは、スキルが広告を配信することを宣言しているカスタムスキルへのリクエストにadvertisingオブジェクトを含めます。詳細については、Alexa広告IDについてを参照してください。
Alexa広告IDを受け取るには、スキルが広告を配信することを示し、プライバシーポリシーを公開して、スキルの再認定を申請する必要があります。詳細については、スキルにAlexa広告IDを追加する手順を参照してください。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
OpenRTB API仕様の 形式は、ハイフンで区切られた、バージョン4のUUID文字列（8-4-4-4-12）です。 |
文字列 |
◯ |
|
|
ユーザーが興味・関心に基づく広告の受け取りを希望しているかどうかを示します。ユーザーが興味・関心に基づく広告と追跡を利用しないことを選択している場合は、 |
ブール値 |
◯ |
例
以下の例では、ユーザーが興味・関心に基づく広告と追跡を利用しないことを選択した場合の設定を示します。
"Advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": true
}
"Advertising": {
"advertisingId": "00000000-0000-0000-0000-00000000",
"limitAdTracking": true
}
以下の例では、ユーザーが興味・関心に基づく広告と追跡を利用することを選択した場合の設定を示します。
"Advertising": {
"advertisingId": "8D5E212-165B-4CA0-909B-C86B9CEE0111",
"limitAdTracking": false
}
AudioPlayerオブジェクト
AudioPlayerインターフェースの現在の状態を提供するオブジェクトです。
AudioPlayerは、ユーザーが音声やリモコンを通して開始したすべてのリクエストに含まれていますが、再生についての詳細情報（tokenおよびoffsetInMilliseconds）は、直近のオーディオを再生したスキルに送信するリクエストにのみ含まれています。
AudioPlayerリクエストなど、ユーザーが開始していないリクエストでは、contextにAudioPlayerオブジェクトは含まれていません。このようなリクエストでは、リクエストタイプが現在の状態（たとえば、リクエストAudioPlayer.PlaybackStartedは再生が開始されたことを示します）を示し、状態についての詳細はrequestオブジェクトに含まれています。
| プロパティ | 説明 | 型 |
|---|---|---|
|
|
この |
|
|
|
リクエストが送信された時点のトラックのオフセットをミリ秒単位で示します。トラックが先頭にある場合、このパラメーターは0です。これは、このリクエストを受け取るスキルがデバイスで直近のオーディオを再生したスキルであった場合にのみ、 |
|
|
|
|
|
応答の形式
このセクションでは、サービスが返す応答の形式について説明します。Alexaスキルのサービスでは、JSON形式で応答を送信する必要があります。
応答には、次のサイズ制限があります。
outputSpeech応答は、8,000文字以内でなければなりません。- 1つの
cardに含まれるすべてのテキストは、8,000文字以内でなければなりません。この文字数には、title、content、textと、画像のURLが含まれます。 - 画像のURL（
smallImageUrlまたはlargeImageUrl）は、2000文字以内でなければなりません。 - SSMLタグ
<audio>を使用する場合： AudioPlayer.PlayディレクティブのaudioItem.streamに含まれているtokenは、1024文字以内でなければなりません。AudioPlayer.PlayディレクティブのaudioItem.streamに含まれているurlは、8,000文字以内でなければなりません。CustomInterfaceController.SendDirectiveディレクティブのpayloadの上限は1000バイトです。このディレクティブの詳細については、ガジェットをターゲットとしたディレクティブを使用してAlexaに応答するを参照してください。- 応答の合計サイズは120KB以内でなければなりません。
応答がこれらの制限を超える場合、Alexaサービスはエラーを返します。
HTTPヘッダー
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length:
応答本文の構文
{
"version": "string",
"sessionAttributes": {
"key": "value"
},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "話すプレーンテキストの文字列",
"playBehavior": "REPLACE_ENQUEUED"
},
"card": {
"type": "Standard",
"title": "カードのタイトル",
"text": "Standardカードのテキストの内容",
"image": {
"smallImageUrl": "https://url-to-small-card-image...",
"largeImageUrl": "https://url-to-large-card-image..."
}
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": "話すプレーンテキストの文字列",
"playBehavior": "REPLACE_ENQUEUED"
}
},
"directives": [
{
"type": "InterfaceName.Directive"
(...ディレクティブの タイプに 応じた プロパティ )
}
],
"shouldEndSession": true
}
}
応答のプロパティ
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
応答のバージョン指定子です。値は |
|
◯ |
|
|
セッションで持続するキーと値のペアのマップです。
セッション属性は、 |
|
✕ |
|
|
ユーザーに対して何を出力するかと現在のセッションを終了するかどうかを定義します。 |
◯ |
Responseオブジェクト
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
ユーザーに対して出力する音声です。OutputSpeechオブジェクトを参照してください。 |
|
✕ |
|
|
Amazon Alexaアプリに出力するためのカードです。Cardオブジェクトを参照してください。 |
|
✕ |
|
|
再プロンプトが必要な場合に使用する このオブジェクトは、サービスが応答を送信後にセッションを開いたままにしている状態（
|
|
✕ |
|
|
Alexaが応答を発話した後に何が起こるかを表します。
|
|
✕ |
|
|
特定のインターフェース（音声ストリーミング用の |
|
✕ |
OutputSpeechオブジェクト
このオブジェクトは、outputSpeechおよびrepromptプロパティの両方を設定するために使用します。
このオブジェクトは、応答をCanFulfillIntentRequest、LaunchRequest、IntentRequest、Display.ElementSelectedリクエスト、または InputHandlerEventに送信するときにのみ含まれます。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
出力する音声のタイプです。
|
|
◯ |
|
|
ユーザーに対して出力する音声です。このプロパティは、 |
|
〇（ |
|
|
ユーザーに対して出力する、SSMLでマークアップされたテキストです。これは、 |
|
〇（ |
|
|
この出力する音声のキューと再生について判断します。
|
|
✕ |
Cardオブジェクト
このオブジェクトは、応答をCanFulfillIntentRequest、LaunchRequest、IntentRequest、またはInputHandlerEventに送信するときにのみ含まれます。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
出力するカードのタイプを示します。有効なタイプは以下の通りです。
|
|
◯ |
|
|
カードのタイトル（タイプが |
|
✕ |
|
|
ヒント： 改行を含めるには、カードの
content内に\r\nまたは\nのいずれかを使用します。 |
|
✕ |
|
|
ヒント： 改行を含めるには、カードの
text内に\r\nまたは\nのいずれかを使用します。 |
|
✕ |
|
|
異なるサイズの画面上で使用するために、2つのURLを指定できます。
スキルの応答にカードを追加するを参照してください。 |
|
✕ |
Repromptオブジェクト
repromptオブジェクトは、CanFulfillIntentRequest、LaunchRequest、IntentRequestに応答を送信するときに有効です。
shouldEndSessionがfalseで、ユーザーが数秒以内に応答しない場合、Alexaは再プロンプトを発話します。
| プロパティ | 説明 | 型 | 必須 |
|---|---|---|---|
|
|
再プロンプトとして出力するテキストまたはSSMLを含む |
|
✕ |
|
|
特定のインターフェースを使用してデバイスレベルで実行するアクションを指定する、ディレクティブのリストです。
|
|
✕ |
outputSpeechとdirectivesの両方が含まれている場合、AlexaはまずoutputSpeechを読み上げ、次にAlexa.Presentation.APLA.RenderDocumentディレクティブによって生成されたオーディオを再生します。directives配列に複数のAlexa.Presentation.APLA.RenderDocumentディレクティブが含まれている場合、配列順に再生されます。
エラー
InternalServerError
- サービス内でリクエストを処理中に発生したエラーです。
HTTPステータスコード： 500
応答の例
CanFulfillIntentRequest、LaunchRequestまたはIntentRequestに対する標準的な応答の例
この応答の例では、インターフェース（AudioPlayerなど）を使用しないため、標準の応答プロパティ（outputSpeech、card、reprompt、shouldEndSession）を返します。CanFulfillIntentには、その応答に特有の追加プロパティが含まれます。
{
"version": "1.0",
"sessionAttributes": {
"supportedHoroscopePeriods": {
"daily": true,
"weekly": false,
"monthly": false
}
},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "今日は新しいことを学ぶチャンスが訪れるでしょう。 それをやり通せば可能性は無限です。他にも質問はありますか？"
},
"card": {
"type": "Simple",
"title": "ホロスコープ",
"content": "今日は新しいことを学ぶチャンスが訪れるでしょう。 それをやり通せば可能性は無限です。"
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": "他にも質問はありますか？"
}
},
"shouldEndSession": false
}
}
関連トピック： CanFulfillIntentRequestに対する応答
Alexa Presentation Language（APL）ディレクティブの応答
Alexa.Presentation.APLインターフェースリファレンスのRenderDocumentディレクティブの例を参照してください。
IntentRequestまたはLaunch Requestに対してディレクティブを使用して応答をした例
この応答には、AudioPlayerインターフェースディレクティブが含まれています。この例では、Alexaは、用意されたoutputSpeechテキストを読み上げてから、オーディオ再生を開始します。
この例は、LaunchRequestまたはIntentRequestから送信された応答を示しています。AudioPlayerまたはPlaybackControllerから返される応答には、outputSpeech、card、reprompt、shouldEndSessionプロパティを含めることができません。
{
"version": "1.0",
"sessionAttributes": {},
"response": {
"outputSpeech": {
"type": "PlainText",
"text": "リクエスト曲を再生しています。"
},
"card": {
"type": "Simple",
"title": "オーディオ再生",
"content": "リクエスト曲を再生しています。"
},
"reprompt": {
"outputSpeech": {
"type": "PlainText",
"text": null
}
},
"directives": [
{
"type": "AudioPlayer.Play",
"playBehavior": "ENQUEUE",
"audioItem": {
"stream": {
"token": "this-is-the-audio-token",
"url": "https://my-audio-hosting-site.com/audio/sample-song.mp3",
"offsetInMilliseconds": 0
}
}
}
],
"shouldEndSession": true
}
}
AudioPlayerまたはPlaybackControllerへの応答の例（ディレクティブのみ）
以下は、AudioPlayerリクエストまたはPlaybackControllerリクエスト（ユーザーがリモコンで次へボタンを押したときに送信されるPlaybackController.NextCommandIssuedリクエストなど）から送信される応答の例です。これらの応答には、outputSpeech、card、reprompt、shouldEndSessionプロパティを含めることができません。
{
"version": "1.0",
"response": {
"directives": [
{
"type": "AudioPlayer.Play",
"playBehavior": "REPLACE_ALL",
"audioItem": {
"stream": {
"token": "track2-long-audio",
"url": "https://my-audio-hosting-site.com/audio/sample-song-2.mp3",
"offsetInMilliseconds": 0
}
}
}
]
}
}
サービスインターフェースのリファレンス（JSON）
リクエストの形式と標準のリクエストタイプ：
- カスタムスキルのJSONインターフェースのリファレンス（本ドキュメント）
- 標準のリクエストタイプのリファレンス
- Alexa.Presentation.APLインターフェース
- Alexa.Presentation.APLTインターフェース
- Alexa.Presentation.HTMLインターフェースのリファレンス
- AudioPlayerインターフェース
- Connectionsインターフェース
- Dialogインターフェース
- Messagingインターフェース
- PlaybackControllerインターフェース
- VideoAppインターフェース
最終更新日: 2024 年 07 月 01 日