カスタムスキルのJSONインターフェースのリファレンス



カスタムスキルのJSONインターフェースのリファレンス

Alexa Skills Kitを利用すると、クラウドベースのサービスを構築してAlexaに新しい機能を追加できます。構築できるサービスは、ウェブサービスまたはAWS Lambda関数のいずれかになります。この文書では、作成したウェブサービスまたはLambda関数とAlexaサービスとの間のプロトコルインターフェースについて詳しく説明します。AWS Lambdaは、アマゾンウェブサービスが提供するサービスです。

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": "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...",
      "permissions": {
        "consentToken": "ZZZZZZZ..."
      }
    }
  },
  "context": {
    "System": {
      "device": {
        "deviceId": "string",
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      },
      "application": {
        "applicationId": "amzn1.ask.skill.[unique-value-here]"
      },
      "user": {
        "userId": "amzn1.ask.account.[unique-value-here]",
        "accessToken": "Atza|AAAAAAAA...",
        "permissions": {
          "consentToken": "ZZZZZZZ..."
        }
      },
      "apiEndpoint": "https://api.amazonalexa.com",
      "apiAccessToken": "AxThk..."
    },
    "AudioPlayer": {
      "playerActivity": "PLAYING",
      "token": "audioplayer-token",
      "offsetInMilliseconds": 0
    }
  },
  "request": {}
}

リクエスト本文のパラメーター

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

パラメーター 説明

version

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

文字列

session

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

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

オブジェクト

context

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

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

オブジェクト

request

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

オブジェクト

リクエストロケール

あらゆるrequestオブジェクトには、ロケールプロパティが含まれています。これはユーザーのロケールを示す 、日本語のja-JPなどの文字列コードです。スキルが応答する言語を決定するのに使用します。

サポートされているロケール:

ロケールコード 言語

de-DE

ドイツ語

en-AU

英語(オーストラリア)

en-CA

英語(カナダ)

en-GB

英語(英国)

en-IN

英語(インド)

en-US

英語(米国)

fr-FR

フランス語

ja-JP

日本語

複数言語のサポートの詳細については、多言語に対応するスキルを開発するを参照してください。

スキルが受け取る可能性のあるリクエストオブジェクトのそれぞれのタイプについては以下のとおりです。

Sessionオブジェクト

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

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

パラメーター 説明

new

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

ブール値

sessionId

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

文字列

attributes

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

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

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

マップ

application

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

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

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

スキルのアプリケーションIDは、スキルのリストに移動してそのスキルのスキルIDの表示をクリックすると確認できます。

オブジェクト

user

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

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

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

  • permissions:ユーザーが提供に同意した情報(住所など)へのアクセスをスキルに許可するconsentTokenが含まれています。consentTokenは廃止になりましたのでご注意ください。ユーザーの許可を決定するにはcontextオブジェクトで取得できるapiAccessTokenを使用します。詳細については、権限を参照してください。

accessTokenフィールドはnullの場合は表示されず、consentTokenがnullの場合はpermissionsオブジェクトも表示されません。

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

オブジェクト

Contextオブジェクト

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

パラメーター 説明

System

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

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

オブジェクト

AudioPlayer

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

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

オブジェクト

Systemオブジェクト

パラメーター 説明

apiAccessToken

Alexa固有のAPIにアクセスする際に使用できるトークンを含む文字列です。このトークンは以下をカプセル化します。

このトークンは、スキルに送信するすべてのリクエストに含まれます。このトークンを使用してアクセス権限を必要とするAPIにアクセスする場合、スキルはAPIを呼び出して返すコードを確認する必要があります。403(アクセス拒否)コードが返されたら、スキルはユーザーに権限を要求する適切なアクションを実行することができます。

文字列

apiEndpoint

デバイスの位置情報APIプログレッシブ応答APIなどのAPIで使用するための、地域に応じた正しいベースURIを参照している文字列です。

文字列

application

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

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

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

アプリケーションIDは、開発者コンソールに表示されます。カスタム > エンドポイントページのAWS Lambda ARNを選択すると確認できます。スキル一覧のスキル名の下にも表示されます。

オブジェクト

device

リクエストの送信に使用されたデバイスについての情報を提供するオブジェクトです。deviceオブジェクトには、deviceIdプロパティとsupportedInterfacesプロパティの両方が含まれています。

  • deviceIdプロパティは、デバイスを一意に識別します。
  • supportedInterfacesプロパティには、デバイスがサポートする各インターフェースが列挙されます。たとえば、supportedInterfacesAudioPlayer {}が含まれている場合、デバイスがAudioPlayer interfaceを使用するオーディオのストリーミングをサポートしていることが分かります。

オブジェクト

user

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

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

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

  • permissions:ユーザーが提供に同意した情報(住所など)へのアクセスをスキルに許可するconsentTokenが含まれています。consentTokenは廃止になりましたのでご注意ください。ユーザーの許可を決定するにはcontextオブジェクトで取得できるapiAccessTokenを使用します。詳細については、権限を参照してください。

accessTokenフィールドはnullの場合は表示されず、consentTokenがnullの場合はpermissionsオブジェクトも表示されません。

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

オブジェクト

AudioPlayerオブジェクト

AudioPlayerインターフェースの現在の状態を提供するオブジェクトです。

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

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

パラメーター 説明

token

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

文字列

offsetInMilliseconds

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

long

playerActivity

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

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

文字列

応答の形式

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

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

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

応答がこれらの制限を超える場合、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": "話すプレーンテキストの文字列",
      "ssml": "<speak>SSML text string to speak</speak>"
    },
    "card": {
      "type": "Standard",
      "title": "カードのタイトル",
      "content": "Simpleカードの内容",
      "text": "Standardカードのテキストの内容",
      "image": {
        "smallImageUrl": "https://url-to-small-card-image...",
        "largeImageUrl": "https://url-to-large-card-image..."
      }
    },
    "reprompt": {
      "outputSpeech": {
        "type": "PlainText",
        "text": "話すプレーンテキストの文字列",
        "ssml": "<speak>SSML text string to speak</speak>"
      }
    },
    "directives": [
      {
        "type": "InterfaceName.Directive"
        (...ディレクティブの タイプに 応じた プロパティ  )
      }
    ],
    "shouldEndSession": true
  }
}

応答のパラメーター

パラメーター 説明 必須

version

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

文字列

sessionAttributes

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

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

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

マップ

response

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

オブジェクト

Responseオブジェクト

パラメーター 説明 必須

outputSpeech

ユーザーに対して出力する音声を含むオブジェクトです。OutputSpeech Objectオブジェクトを参照してください。

オブジェクト

×

card

Amazon Alexaアプリに出力するためのカードを含むオブジェクトです。Cardオブジェクトを参照してください。

オブジェクト

×

reprompt

再プロンプトが必要な場合に使用するoutputSpeechを含むオブジェクトです。

このオブジェクトは、サービスが応答を送信後にセッションを開いたままにしている状態のときに、ユーザーが、音声ストリーミングが有効になっている間に音声インターフェースで定義されたインテントに対応する言葉を発しなかった場合に使用されます。

このオブジェクトが設定されていない場合、ユーザーへの再プロンプトは行われません。

オブジェクト

×

shouldEndSession

Alexaが応答を話した後にセッションを終了する必要がある場合はtrueに、セッションをアクティブのままにする必要がある場合はfalseにするブール値です。これを指定しない場合、デフォルト値はtrueです。

ブール値

ディレクティブ

特定のインターフェース(音声ストリーミング用のAudioPlayerインターフェースなど)を使用してデバイスレベルで実行するアクションを指定する、ディレクティブの配列です。応答に含めることができるディレクティブの詳細については、以下を参照してください。

配列

OutputSpeechオブジェクト

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

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

パラメーター 説明 必須

type

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

  • "PlainText": 出力する音声がプレーンテキストとして定義されていることを示します。
  • "SSML": 出力する音声がSSMLでマークアップされたテキストであることを示します。

文字列

text

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

文字列

〇(PlainTextの場合)

ssml

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

文字列

〇(SSMLの場合)

Cardオブジェクト

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

パラメーター 説明 必須

type

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

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

文字列

title

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

文字列

×

content

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

文字列

×

text

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

文字列

×

image

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

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

  • smallImageUrl
  • largeImageUrl

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

オブジェクト

×

Repromptオブジェクト

このオブジェクトは、LaunchRequestIntentRequest、またはInputHandlerEventに対して応答を送信するときにのみ含めることができます。入力ハンドラーが再プロンプトに与える影響の詳細については、入力ハンドラーと再プロンプト(日本未対応)を参照してください。

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

エラー

InternalServerError

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

応答の例

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

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

{
  "version": "1.0",
  "sessionAttributes": {
    "supportedHoriscopePeriods": {
      "daily": true,
      "weekly": false,
      "monthly": false
    }
  },
  "response": {
    "outputSpeech": {
      "type": "PlainText",
      "text": "今日は新しいことを学ぶチャンスが訪れるでしょう。 それをやり通せば可能性は無限です。他にも質問はありますか?"
    },
    "card": {
      "type": "Simple",
      "title": "ホロスコープ",
      "content": "今日は新しいことを学ぶチャンスが訪れるでしょう。 それをやり通せば可能性は無限です。"
    },
    "reprompt": {
      "outputSpeech": {
        "type": "PlainText",
        "text": "他にも質問はありますか?"
      }
    },
    "shouldEndSession": false
  }
}

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

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

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

{
  "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リクエストなど)から送信される応答の例です。これらの応答には、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
          }
        }
      }
    ]
  }
}

Displayインターフェースのリファレンスを参照してください。

GameEngineインターフェースのリファレンスおよびGadgetControllerインターフェースのリファレンスを参照してください。

サービスインターフェースのリファレンス(JSON)

リクエストの形式と標準のリクエストタイプ:

インターフェース: