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


カスタムスキルの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": {}
}

リクエスト本文のプロパティ

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

プロパティ 説明

version

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

string

session

リクエストに関連付けられた追加のコンテキストを提供します。

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

object

context

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

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

object

request

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

標準のリクエストタイプ

特定のインターフェースと関連付けられているリクエスト:

object

リクエストロケール

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

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

ロケールコード 言語

ar-SA

アラビア語(SA)

de-DE

ドイツ語(DE)

en-AU

英語(AU)

en-CA

英語(CA)

en-GB

英語(UK)

en-IN

英語(IN)

en-US

英語(US)

es-ES

スペイン語(ES)

es-MX

スペイン語(MX)

es-US

スペイン語(US)

fr-CA

フランス語(CA)

fr-FR

フランス語(FR)

hi-IN

ヒンディー語(IN)

it-IT

イタリア語(IT)

ja-JP

日本語(JP)

pt-BR

ポルトガル語(BR)

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

Sessionオブジェクト

標準のリクエストタイプCanFulfillIntentReqeuestLaunchRequestIntentRequestSessionEndedRequest)には、sessionオブジェクトが含まれます。[GameEngineインターフェース][game-engine-interface-reference]にも、sessionオブジェクトが含まれます。

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

プロパティ 説明

new

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

boolean

sessionId

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

string

attributes

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

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

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

map

application

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

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

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

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

object

user

スキルを有効にしているAmazonアカウントを表します。userオブジェクトはpersonオブジェクトと異なります。userはスキルを有効にしているAmazonアカウントを表し、personは、Alexaが声を識別しているユーザーを表します。

userは、以下で構成されています。

  • userId: スキルを有効にしているAmazonアカウントを一意に識別する文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。ユーザーがAlexaアプリでスキルを有効にすると、userIdが自動的に生成されます。通常、スキルを無効にしてから再度有効にすると、新しい識別子が生成されます。ただし、スキルで消費型課金が使用できる場合、userIdはリセットされません。ユーザーがスキルを無効化してから再有効化した場合にユーザーインベントリーを管理するを参照してください。

  • accessToken: 対象ユーザーを別のシステム内で識別するトークンです。このトークンは、ユーザーが自分のアカウントを正常にリンクしている場合のみ付与されます。詳細については、スキルにアカウントリンクを追加するをご覧ください。

  • permissions: 廃止になりました。このオブジェクトには、ユーザーが提供に同意している情報(住所など)にアクセスするためのconsentTokenが含まれます。consentTokenは廃止されているため、代わりにcontextオブジェクトに含まれるapiAccessTokenを使用してユーザーの権限を確認してください。詳細については、アクセス権限を参照してください。

nullの場合、accessTokenフィールドはリクエストに含まれません。consentTokenがnullの場合はpermissionsオブジェクトも含まれません。

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

object

Contextオブジェクト

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

プロパティ 説明

Advertising

(任意)ユーザーの広告IDと、興味・関心に基づく広告の受け取りに関する詳細設定を提供します。スキルが広告を配信することを宣言しているスキルへのリクエストに含められます。

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

object

Alexa.Presentation.APL

現在画面に表示されているAlexa Presentation Languageのドキュメントに関する情報を提供します。これは、ユーザーのデバイスに画面があり、ユーザーの操作がスキルにリクエストをトリガーしたときに、APLドキュメントが画面にレンダリングされている場合に含まれます。

APLの詳細については、スキルに視覚要素とオーディオを追加するを参照してください。

object

AudioPlayer

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

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

object

System

Alexaサービスと、スキルと対話しているデバイスの現在の状態に関する情報を提供します。

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

object

Viewport

ユーザーのデバイスに画面がある場合に含まれます。Viewportオブジェクトは、サイズや形状など、viewportに関する情報を提供します。詳細については、Alexa.Presentation.APLインターフェースリファレンススキルリクエストのViewportオブジェクトを参照してください。

object

Viewports

ユーザーのデバイスに画面またはキャラクターディスプレイがある場合に含まれます。使用可能な画面またはディスプレイに関する情報を提供するオブジェクトが含まれています。詳細については、Alexa.Presentation.APLTインターフェースリファレンススキルリクエストのViewportオブジェクトを参照してください。

array

Systemオブジェクト

プロパティ 説明

apiAccessToken

Alexa固有のAPIにアクセスするためのトークンを含みます。このトークンは以下をカプセル化します。

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

string

apiEndpoint

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

string

application

アプリケーションIDを含みます。このIDを使用してリクエストがそのサービスに対するものかどうかを検証します。

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

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

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

object

device

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

  • deviceIdプロパティは、デバイスを一意に識別します。
  • supportedInterfacesプロパティには、デバイスがサポートする各インターフェースが列挙されます。たとえば、supportedInterfacesAudioPlayer {}が含まれている場合、デバイスがAudioPlayerインターフェースを使用するオーディオのストリーミングをサポートしていることが分かります。
  • persistentEndpointIdプロパティは、スキルリクエストが発行されるエンドポイントの永続的な識別子です。エンドポイントは、Alexaコネクテッドデバイス(Echoデバイスやスマート電球など)やデバイスとして扱われるエンティティ(デバイスで実行されているシーンや特定のアプリケーションなど)を表します。エンドポイントの詳細については、Endpoint APIを参照してください。登録済みのAlexa Smart Properties for residentialおよびAlexa Smart Properties for hospitalityベンダーだけが、Alexa開発者コンソールでRead PersistentEndpointIdトグルを表示できます。この識別子はベンダーベースであり、特定のベンダーに属するすべてのスキルがこの識別子を共有します。

object

unit

Alexaシステムとやり取りするアクター(人や組織など)とリソース(デバイスやスキルなど)を整理する論理構造を表します。

unitは、以下で構成されています。

  • unitId: リクエストを行ったユーザーの一意の識別子を表す文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。スキルに対するリクエストに有効なユニットコンテキストがある場合にのみ、Alexaがこの文字列を生成します。通常、スキルを無効にしてから再度有効にすると、新しい識別子が生成されます。

  • persistentUnitId: リクエストを行ったユーザーの一意の識別子を表す文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。スキルに対するリクエストに有効なユニットコンテキストがある場合にのみ、Alexaがこの文字列を生成します。これは、組織の開発者アカウントに関連付けられた別の一意の識別子です。登録済みのAlexa Smart Properties for residentialおよびAlexa Smart Properties for hospitalityの開発者だけが、Alexa開発者コンソールでRead PersistentUnitIdトグルを表示できます。この識別子はベンダーベースであり、特定のベンダーに属するすべてのスキルがこの識別子を共有します。

object

person

Alexaにリクエストしているユーザーを表します。personオブジェクトはuserオブジェクトと異なります。personはAlexaが声を識別しているユーザーを表し、userは、スキルを有効にしているAmazonアカウントを表します。

personは、以下で構成されています。

  • personId: リクエストしているユーザーを一意に識別する文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。識別済みのユーザーがスキルにリクエストを伝えると、Alexaがこの文字列を生成します。通常、スキルを無効にしてから再度有効にすると、新しい識別子が生成されます。

  • accessToken: 対象ユーザーを別のシステム内で識別するトークンです。そのユーザーが、Alexaプロフィールで自分のアカウントを正常にリンクしている場合のみ、このフィールドがリクエストに追加されます。

nullの場合、accessTokenフィールドはリクエストに含まれません。

object

user

スキルを有効にしているAmazonアカウントを表します。userオブジェクトはpersonオブジェクトと異なります。userはスキルを有効にしているAmazonアカウントを表し、personは、Alexaが声を識別しているユーザーを表します。

userは、以下で構成されています。

  • userId: スキルを有効にしているAmazonアカウントを一意に識別する文字列です。この識別子の長さはさまざまですが、255文字を超えることはありません。ユーザーがAlexaアプリでスキルを有効にすると、userIdが自動的に生成されます。通常、スキルを無効にしてから再度有効にすると、新しい識別子が生成されます。ただし、スキルで消費型課金が使用できる場合、userIdはリセットされません。ユーザーがスキルを無効化してから再有効化した場合にユーザーインベントリーを管理するを参照してください。

  • accessToken: 対象ユーザーを別のシステム内で識別するトークンです。このトークンは、ユーザーが自分のアカウントを正常にリンクしている場合のみ付与されます。詳細については、スキルにアカウントリンクを追加するをご覧ください。

  • permissions: 廃止になりました。このオブジェクトには、ユーザーが提供に同意している情報(住所など)にアクセスするためのconsentTokenが含まれます。consentTokenは廃止されているため、代わりにcontextオブジェクトに含まれるapiAccessTokenを使用してユーザーの権限を確認してください。詳細については、アクセス権限を参照してください。

nullの場合、accessTokenフィールドはリクエストに含まれません。consentTokenがnullの場合はpermissionsオブジェクトも含まれません。

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

object

advertisingオブジェクト

advertisingオブジェクトは、ユーザーの広告IDと、興味・関心に基づく広告の受け取りに関するカスタマイズ設定を提供します。Alexaは、スキルが広告を配信することを宣言しているカスタムスキルへのリクエストにadvertisingオブジェクトを含めます。詳細については、Alexa広告IDについてを参照してください。

プロパティ 説明 必須

advertisingId

OpenRTB API仕様ifaアトリビュートにマッピングされる、ユーザーによるリセットが可能な一意の識別子です。

形式は、ハイフンで区切られた、バージョン4のUUID文字列(8-4-4-4-12)です。
例: E0DE19C7-43A8-4738-AfA7-3A7f1B3C0367

文字列

limitAdTracking

ユーザーが興味・関心に基づく広告の受け取りを希望しているかどうかを示します。ユーザーが興味・関心に基づく広告と追跡を利用しないことを選択している場合は、trueに設定します。
limitAdTrackingプロパティは、OpenRTB API仕様のlmtアトリビュートにマッピングされます。

ブール値

以下の例では、ユーザーが興味・関心に基づく広告と追跡を利用しないことを選択した場合の設定を示します。

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

プロパティ 説明

token

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

string

offsetInMilliseconds

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

long

playerActivity

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

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

string

応答の形式

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

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

  • outputSpeech応答は、8,000文字以内でなければなりません。
  • 1つのcardに含まれるすべてのテキストは、8,000文字以内でなければなりません。この文字数には、titlecontenttextと、画像のURLが含まれます。
  • 画像のURL(smallImageUrlまたはlargeImageUrl)は、2000文字以内でなければなりません。
  • SSMLタグ<audio>を使用する場合:
    • 応答outputSpeechプロパティに含めることのできるすべての音声ファイルの合計再生時間は240秒までです。
    • 応答repromptプロパティに含めることのできるすべての音声ファイルの合計再生時間は90秒までです。
  • 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
  }
}

応答のプロパティ

プロパティ 説明 必須

version

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

string

sessionAttributes

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

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

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

map

response

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

Responseオブジェクト

Responseオブジェクト

プロパティ 説明 必須

outputSpeech

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

object

card

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

object

reprompt

再プロンプトが必要な場合に使用するOutputSpeechです。

このオブジェクトは、サービスが応答を送信後にセッションを開いたままにしている状態(shouldEndSessionfalse)のときに、ユーザーが、マイクが有効になっている間に音声インターフェースで定義されたインテントに対応する言葉を発しなかった場合に使用されます。Alexaがセッションを閉じる前に、再プロンプトに応答する時間が数秒あります。

repromptに値がない場合、Alexaはユーザーに再プロンプトしません。

object

shouldEndSession

Alexaが応答を発話した後に何が起こるかを表します。

  • true: セッションが終了します。
  • falseまたはnull: Alexaは、ユーザーの応答を聴き取るために数秒間マイクを有効にします。ユーザーがもう一度リクエストできるようにrepromptを含めます。
  • undefined: セッションの動作は、Echoデバイスの種類によって異なります。デバイスに画面があり、スキルに画面コンテンツが表示されている場合、セッションは最大30秒間開いたままになります。ただし、マイクをオンにしてユーザーに入力を求めることはありません。詳細については、画面付きデバイスがスキルセッションに与える影響を参照してください。ユーザーがリクエストの前にウェイクワードを付けて話しかけると(「アレクサ」など)Alexaはリクエストをスキルに送信します。それ以外の場合、Alexaはユーザーの音声を無視します。Alexa Gadgetsイベントハンドラーが有効な場合、スキルがCustomInterfaceController.StopEventHandlerを呼び出すまで、あるいはイベントハンドラーの有効期限が切れない限り、セッションは開いたままになります。

AMAZON.StopIntentへの応答はtrueを使用する必要があります。

boolean

directives

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

array

OutputSpeechオブジェクト

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

このオブジェクトは、応答をCanFulfillIntentRequestLaunchRequestIntentRequestDisplay.ElementSelectedリクエスト、または InputHandlerEventに送信するときにのみ含まれます。

プロパティ 説明 必須

type

出力する音声のタイプです。
有効な値は次のとおりです。

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

string

text

ユーザーに対して出力する音声です。このプロパティは、type"PlainText"の場合に使用します。

string

〇(PlainTextの場合)

ssml

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

string

〇(SSMLの場合)

playBehavior

この出力する音声のキューと再生について判断します。
有効な値は次のとおりです。

  • "ENQUEUE": この音声をキューの最後に追加します。Alexaの現在の音声には割り込ませないでください。GameEngineインターフェースを使用しないすべてのスキルで、これがデフォルト値になります。
  • "REPLACE_ALL": 現在の音声およびキューに追加された音声を置き換え、この音声の再生をすぐに開始します。GameEngineインターフェースを使用しているすべてのスキルで、これがデフォルト値になります。
  • "REPLACE_ENQUEUED": キューのすべての音声をこの音声に置き換えます。Alexaの現在の音声には割り込ませないでください。

playBehaviorとAlexa Skills Kit SDKを使用してplayBehaviorを設定するサンプルコードについて詳しくは、Alexaの音声の割り込みを制御するを参照してください。

string

Cardオブジェクト

このオブジェクトは、応答をCanFulfillIntentRequestLaunchRequestIntentRequest、またはInputHandlerEventに送信するときにのみ含まれます。

プロパティ 説明 必須

type

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

  • "Simple": タイトルとプレーンテキストコンテンツを含むカード。
  • "Standard": タイトル、テキストコンテンツ、表示する画像を含むカードです。
  • "LinkAccount": ユーザーが別のシステムのユーザーと自分のAlexaのアカウントをリンクするために使用できる認証画面のURIへのリンクを表示するカードです。詳細については、カスタムスキルのアカウントリンクを参照してください。
  • "AskForPermissionsConsent": ユーザーに住所などの特定のユーザー情報の取得に同意を求めるカードです。詳細については、permissionsを参照してください。

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オブジェクト

repromptオブジェクトは、CanFulfillIntentRequestLaunchRequestIntentRequestに応答を送信するときに有効です。

shouldEndSessionfalseで、ユーザーが数秒以内に応答しない場合、Alexaは再プロンプトを発話します。

プロパティ 説明 必須

outputSpeech

再プロンプトとして出力するテキストまたはSSMLを含むOutputSpeechオブジェクトです。

object

directives

特定のインターフェースを使用してデバイスレベルで実行するアクションを指定する、ディレクティブのリストです。repromptオブジェクト内に、次のディレクティブを含めることができます。

repromptオブジェクトでは、他のディレクティブはサポートされていません。再プロンプトのディレクティブ配列に他のdirectivesを含めると、エラーが発生し、スキルセッションが終了します。

array

outputSpeechdirectivesの両方が含まれている場合、AlexaはまずoutputSpeechを読み上げ、次にAlexa.Presentation.APLA.RenderDocumentディレクティブによって生成されたオーディオを再生します。directives配列に複数のAlexa.Presentation.APLA.RenderDocumentディレクティブが含まれている場合、配列順に再生されます。

エラー

InternalServerError

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

応答の例

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

この応答の例では、インターフェース(AudioPlayerなど)を使用しないため、標準の応答プロパティ(outputSpeechcardrepromptshouldEndSession)を返します。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から返される応答には、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
          }
        }
      }
    ]
  }
}

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

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

インターフェース


このページは役に立ちましたか?

最終更新日: 2024 年 07 月 01 日