あなたのAlexaダッシュボード 設定

カスタムスキルの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ディレクティブをまだリクエストしていません。

{
  "version": "string",
  "session": {
    "new": true,
    "sessionId": "string",
    "application": {
      "applicationId": "string"
    },
    "attributes": {
      "string": {}
    },
    "user": {
      "userId": "string",
        "permissions": {
          "consentToken": "string"
      },	  
      "accessToken": "string"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "string"
      },
      "user": {
        "userId": "string",
        "permissions": {
          "consentToken": "string"
      },		
        "accessToken": "string"
      },
      "device": {
        "deviceId": "string",	  
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      },
      "apiEndpoint": "string"
    },
    "AudioPlayer": {
      "token": "string",
      "offsetInMilliseconds": 0,
      "playerActivity": "string"
    }
  },
  "request": {}
}

リクエストボディのパラメーター

すべてのリクエストには、versioncontextrequestオブジェクトがトップレベルで含まれています。sessionオブジェクトは、すべての標準のリクエストタイプに含まれていますが、AudioPlayerVideoAppPlaybackControllerリクエストには含まれていません。

パラメーター 説明

version

リクエストのバージョン指定子です。値は"1.0"と定義されています。

string

session

sessionオブジェクトは、リクエストに関連付けられた追加のコンテキストを提供します。

sessionオブジェクトの定義については、Sessionオブジェクトを参照してください。

object

context

contextオブジェクトは、リクエストがサービスに送信された時点でのAlexaサービスと端末の現在の状態をスキルに提供します。このオブジェクトは、すべてのリクエストに含まれています。セッションのコンテキストで送信されたリクエスト(LaunchRequestおよびIntentRequest)では、sessionオブジェクトからも取得できるuser情報およびapplication情報がcontextオブジェクトに重複して含まれています。

contextオブジェクトの定義については、Contextオブジェクトを参照してください。

object

request

ユーザーのリクエストの詳細を提供するrequestオブジェクトです。以下に示す、いくつかの異なるリクエストタイプを利用できます。

object

Sessionオブジェクト

標準のリクエストタイプLaunchRequestIntentRequestSessionEndedRequest)には、sessionオブジェクトが含まれます。

AudioPlayerPlaybackControllerなどのインターフェースからのリクエストはセッションのコンテキストで送信されるものではないため、それらのリクエストにsessionオブジェクトは含まれません。context.System.userオブジェクトとcontext.System.applicationオブジェクトが提供するユーザーとアプリケーションに関する情報は、sessionに含まれる同じオブジェクトが提供する情報と同じです。Contextオブジェクトを参照してください。

パラメーター 説明

new

新しいセッションかどうかを示すブール値です。新しいセッションの場合はtrueを、既存のセッションの場合はfalseを返します。

boolean

sessionId

ユーザーのアクティブセッションでの一意の識別子を表す文字列です。

string

attributes

キーと値のペアのマップです。プロパティnewtrueに設定されてセッションが新しく開始したリクエストの場合、この属性マップは空になります。

  • keyは、属性の名前を表す文字列です。型: string
  • valueは、属性の値を表すオブジェクトです。型: object

応答を返すときに、同一セッション内で保持する必要があるデータをsessionAttributesプロパティに組み込むことができます。ここで提供した属性が、次のリクエストでスキルに与えられます。

map

application

アプリケーションIDを含むオブジェクトです。このオブジェクトはリクエストがそのサービスに対するものかどうかを検証するために使われます。

  • applicationId: スキルのアプリケーションIDを表すstringです。

この情報は、context.System.applicationプロパティからも取得できます。

スキルのアプリケーションIDは、開発者ポータルスキル情報ページで確認できます。

object

user

リクエストを行ったユーザーを示すオブジェクトです。userは、以下で構成されています。

  • userId: リクエストを行ったユーザーの一意の識別子を表す文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。userIdは、ユーザーがAlexaアプリでスキルを有効にすると自動的に生成されます。

  • accessToken: 別のシステム内の該当のユーザーを識別するトークンです。このトークンは、ユーザーがアカウントを正常にリンクできたときにのみ付与されます。詳細については、Alexaユーザーとあなたのシステムでのユーザーを関連付けるを参照してください。

  • permissions: ユーザーが提供に同意した情報(住所など)へのアクセスをスキルに許可するconsentTokenが含まれています。詳細については、権限を参照してください。

この情報は、context.System.applicationプロパティからも取得できます。

object

Contextオブジェクト

contextオブジェクトは、リクエストがサービスに送信された時点でのAlexaサービスと端末の現在の状態をスキルに提供します。このオブジェクトは、すべてのリクエストに含まれています。セッションのコンテキストで送信されたリクエスト(LaunchRequestおよびIntentRequest)では、sessionオブジェクトからも取得できるuser情報およびapplication情報がcontextオブジェクトに重複して含まれています。

パラメーター 説明

System

Alexaサービスと、スキルと対話している端末の現在の状態に関する情報を提供するsystemオブジェクトです。

systemオブジェクトの定義については、Systemオブジェクトを参照してください。

object

AudioPlayer

AudioPlayerインターフェースの現在の状態を提供するオブジェクトです。AudioPlayerオブジェクトの定義については、AudioPlayerオブジェクトを参照してください。

AudioPlayerは、ユーザーが音声やリモコンを通して開始したすべてのリクエストに含まれていますが、再生についての詳細情報(tokenおよびoffsetInMilliseconds)は、直近のオーディオを再生したスキルに送信するリクエストにのみ含まれています。

object

Systemオブジェクト

パラメーター 説明

application

アプリケーションIDを含むオブジェクトです。このオブジェクトはリクエストがそのサービスに対するものかどうかを検証するために使われます。

  • applicationId: スキルのアプリケーションIDを表すstringです。

この情報は、LaunchRequestIntentRequestSessionEndedRequestタイプのsession.applicationプロパティからも取得できます。

スキルのアプリケーションIDは、開発者ポータルスキル情報ページで確認できます。

object

user

リクエストを行ったユーザーを示すオブジェクトです。userは、以下で構成されています。

  • userId: リクエストを行ったユーザーの一意の識別子を表す文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。userIdは、ユーザーがAlexaアプリでスキルを有効にすると自動的に生成されます。

  • accessToken: 別のシステム内の該当のユーザーを識別するトークンです。このトークンは、ユーザーがアカウントを正常にリンクできたときにのみ付与されます。詳細については、Alexaユーザーとあなたのシステムでのユーザーを関連付けるを参照してください。

この情報は、LaunchRequestIntentRequestSessionEndedRequestタイプのsession.userプロパティからも取得できます。

object

device

リクエストを送信するために使用された端末についての情報を提供するオブジェクトです。deviceオブジェクトには、deviceIdプロパティとsupportedInterfacesプロパティの両方が含まれています。deviceIdプロパティは、端末を一意に識別します。supportedInterfacesプロパティには、端末がサポートする各インターフェースが列挙されます。たとえば、supportedInterfacesAudioPlayer {}が含まれている場合、AudioPlayerインターフェースを使用するオーディオのストリーミングを端末がサポートしていることが分かります。

object

apiEndpoint

リージョンによって参照される正しいベースURIを参照しているオブジェクトです。端末の所在地データを呼び出すUS用のベースURI: https://api.amazonalexa.com/。端末の所在地データを呼び出すUKおよびDE用のベースURI: https://api.eu.amazonalexa.com

object

AudioPlayerオブジェクト

このオブジェクトは、AudioPlayerインターフェースの現在の状態を提供します。

AudioPlayer は、ユーザーが音声やリモコンを通して開始したすべてのリクエストに含まれていますが、再生についての詳細情報(tokenおよびoffsetInMilliseconds)は、直近のオーディオを再生したスキルへのリクエストにのみ含まれています。

AudioPlayerリクエストなど、ユーザーが開始していないリクエストでは、contextAudioPlayerオブジェクトは含まれていません。このようなリクエストでは、リクエストタイプが現在の状態(たとえば、リクエストAudioPlayer.PlaybackStartedは再生が開始されたことを示します)を示し、状態についての詳細はrequestオブジェクトに含まれています。

パラメーター 説明

token

このAudioPlayerオブジェクトで記述されたオーディオストリーミングを表す不透明なトークンです。Playディレクティブを送信するときには、このトークンを提供します。これは、このリクエストを受け取るスキルが端末上で直近のオーディオを再生したスキルであった場合にのみ、AudioPlayerオブジェクトに含まれます。

string

offsetInMilliseconds

リクエストが送信された時点のトラックのオフセットをミリ秒単位で示します。トラックが先頭にある場合、このパラメーターは0です。これは、このリクエストを受け取るスキルが端末上で直近のオーディオを再生したスキルであった場合にのみ、AudioPlayerオブジェクトに含まれます。

long

playerActivity

playerActivity: オーディオ再生の最新の既知の状態を示します。

  • IDLE: 何も再生されておらず、待機中のアイテムもありませんでした。
  • PAUSED: ストリーミングが一時停止されていました。
  • PLAYING: ストリーミングの再生中でした。
  • BUFFER_UNDERRUN: バッファアンダーランが発生していました。
  • FINISHED: ストリーミングの再生が終了していました。
  • STOPPED: ストリーミングが中断されていました。

string

応答のフォーマット

このセクションでは、サービスが返す応答のフォーマットについて説明します。Alexaスキルのサービスでは、JSON形式で応答を送信する必要があります。

応答には、次のサイズ制限があります。

  • outputSpeech応答は、8000文字以内でなければなりません。
  • 1つのcardに含まれるすべてのテキストは、8000文字以内でなければなりません。この文字数には、titlecontenttextと、画像のURLが含まれます。
  • 画像のURL(smallImageUrlまたはlargeImageUrl)は、2000文字以内でなければなりません。
  • AudioPlayer.PlayディレクティブのaudioItem.streamに含まれているtokenは、1024文字以内でなければなりません。
  • AudioPlayer.PlayディレクティブのaudioItem.streamに含まれているurlは、8000文字以内でなければなりません。
  • 応答の合計サイズは24キロバイト以内でなければなりません。

応答がこれらの制限を超える場合、Alexaサービスはエラーを返します。

HTTPヘッダー

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length:

応答ボディの構文

この例の中で、Display.RenderTemplateディレクティブのコンテンツは、使用されている表示テンプレートに応じて異なります。

{
  "version": "string",
  "sessionAttributes": {
    "string": "<object>"
  },
  "response": {
    "outputSpeech": {
      "type": "string",
      "text": "string",
      "ssml": "string"
    },
    "card": {
      "type": "string",
      "title": "string",
      "content": "string",
      "text": "string",
      "image": {
        "smallImageUrl": "string",
        "largeImageUrl": "string"
      }
    },
    "reprompt": {
      "outputSpeech": {
        "type": "string",
        "text": "string",
        "ssml": "string"
      }
    },
    "directives": [
      {
        "type": "Display.RenderTemplate",
        "template": {
          "type": "string",
          ...
        }
      },
      {
        "type": "string",
        "playBehavior": "string",
        "audioItem": {
          "stream": {
            "token": "string",
            "url": "string",
            "offsetInMilliseconds": 0
          }
        }
      },
      {
        "general": {
          "type": "VideoApp.Launch",
          "videoItem": {
              "source": "string",
              "metadata": {
                "title": "string",
				"subtitle": "string"
              }
			}  
        }
      },
    ],
    "shouldEndSession": boolean
  }
}

応答パラメーター

パラメーター 説明 必須

version

応答のバージョン指定子です。値は"1.0"と定義されています。

string

sessionAttributes

セッションで持続するキーと値のペアのマップ。

  • キーは、属性の名前を表す文字列です。型: string
  • 値は、属性の値を表すオブジェクトです。型: object

セッション属性は、AudioPlayerリクエストまたはPlaybackControllerリクエストに対する応答に含まれている場合、無視されます。

map

×

response

ユーザーに対して何を出力するかと現在のセッションを終了するかどうかを定義するresponseオブジェクトです。

object

Responseオブジェクト

パラメーター 説明 必須
outputSpeech ユーザーに対して出力する音声を含むオブジェクトです。詳細については、OutputSpeechオブジェクトを参照してください。 object ×
card Amazon Alexaアプリに出力するためのカードを含むオブジェクトです。詳細については、Cardオブジェクトを参照してください。 object ×
reprompt 再プロンプトが必要な場合に使用するoutputSpeechを含むオブジェクトです。

このオブジェクトは、サービスが応答を送信後、セッションが開かれたままの状態にあり、この状態でユーザーが音声インターフェースで定義されたインテントに対応する反応を返さなかった場合に使用されます。

このオブジェクトが設定されていない場合、ユーザーへの再プロンプトは行われません。
object ×
shouldEndSession Alexaが応答を話した後にセッションを終了する必要がある場合はtrueに、セッションをアクティブのままにする必要がある場合はfalseにするブール値です。これを指定しない場合、デフォルト値はtrueです。 Boolean ×
directives 特定のインターフェース(音声ストリーミング用のAudioPlayerインターフェースなど)を使用して端末レベルで実行するアクションを指定するディレクティブの配列です。応答に含めることのできるディレクティブの詳細については、AudioPlayerインターフェースのリファレンスVideoAppインターフェースのリファレンスDisplayインターフェースのリファレンスDialogインターフェースのリファレンスを参照してください。 array ×

OutputSpeechオブジェクト

このオブジェクトは、outputSpeechおよびrepromptプロパティの両方を設定するために使用します。

このオブジェクトは、LaunchRequestまたはIntentRequestに対して応答を送信するときにのみ含めることができます。

パラメーター 説明 必須

type

出力する音声のタイプを含む文字列です。有効なタイプは以下の通りです。

string

text

ユーザーに対して出力する音声を含む文字列です。これは、typeが次の値の場合に使用します: "PlainText"

string

○(PlainTextの場合)

ssml

ユーザーに対して出力する、SSMLでマークアップされたテキストを含む文字列です。これは、typeが次の値の場合に使用します: "SSML"

string

○(SSMLの場合)

Cardオブジェクト

このオブジェクトは、LaunchRequestまたはIntentRequestに対して応答を送信するときにのみ含めることができます。

パラメーター 説明 必須

type

出力するカードのタイプを示す文字列です。有効なタイプは以下の通りです。

  • "Simple": タイトルとプレーンテキストコンテンツを含むカード。
  • "Standard": タイトル、テキストコンテンツ、画像を含むカード。
  • "LinkAccount": ユーザーが別のシステムのユーザーと自分のAlexaのアカウントをリンクするために使用することができる認証URLへのリンクを表示するカード。詳細については、Alexaユーザーとあなたのシステムでのユーザーを関連付けるを参照してください。

string

title

カードのタイトルを含む文字列です(タイプLinkAccountのカードには適用されません)。

string

×

content

Simpleカードのコンテンツを含む文字列(タイプがStandardまたはLinkAccountのカードには適用されません)。

string

×

text

Standardカードのテキストコンテンツを含む文字列です(タイプがSimpleまたはLinkAccountのカードには適用されません)

string

×

image

Standardカードに表示する画像のURLを指定するimageオブジェクトです。Standardカードのみに適用されます。

異なるサイズの画面上で使用するために、2つのURLを指定できます。

  • smallImageUrl
  • largeImageUrl

詳細については、スキルの応答にカードを追加するを参照してください。

object

×

Repromptオブジェクト

このオブジェクトは、LaunchRequestまたはIntentRequestに対して応答を送信するときにのみ含めることができます。

パラメーター 説明 必須
outputSpeech OutputSpeechは再プロンプトとして出力するテキストまたはSSMLを含むオブジェクトです。 object ×

エラー

InternalServerError

  • サービス内でリクエストを処理中に発生したエラーです。
  • HTTP ステータスコード: 500

応答の例

LaunchRequestまたはIntentRequestに対する標準的な応答の例

この応答の例では、インターフェース(AudioPlayerなど)を使用しないため、標準の応答プロパティ(outputSpeechcardrepromptshouldEndSession)を返します。

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoriscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "Today will provide you a new learning opportunity.  Stick with it and the possibilities will be endless. Can I help you with anything else?"
    },
    "card": {
      "type": "Simple",
      "title": "Horoscope",
      "content": "Today will provide you a new learning opportunity.  Stick with it and the possibilities will be endless."
    },
    "reprompt": {
      "outputSpeech": {
        "type": "PlainText",
        "text": "Can I help you with anything else?"
      }
    },
    "shouldEndSession": false
  }
}

IntentRequestまたはLaunchRequestに対してディレクティブを使用して応答をした例

この応答には、AudioPlayerインターフェースディレクティブが含まれています。この例では、Alexaは、用意されたoutputSpeechテキストを読み上げてから、オーディオ再生を開始します。

この例は、LaunchRequestまたはIntentRequestから送信された応答を示しています。AudioPlayerまたはPlaybackControllerから返される応答には、outputSpeechcardrepromptshouldEndSessionプロパティを含めることができません。

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "Playing the requested song."
    },
    "card": {
      "type": "Simple",
      "title": "Play Audio",
      "content": "Playing the requested song."
    },
    "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リクエストなど)から送信される応答の例です。これらの応答には、outputSpeechcardrepromptshouldEndSessionプロパティを含めることができません。

{
  "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)

インターフェース: