標準のリクエストタイプのリファレンス

標準のリクエストタイプのリファレンス

Alexaサービスは、ユーザーが音声でスキルと対話するときに、標準のリクエストタイプのいずれかを使用してサービスにリクエストを送信します。リクエストタイプには、次の4つがあります。

  • LaunchRequest: 特定のインテントを提供することなく、ユーザーがスキルを呼び出すときに送信されます。
  • IntentRequest: インテントスキーマで定義されたインテントのいずれかに対応するリクエストをユーザーが行ったときに送信されます。
  • SessionEndedRequest: コードによるセッションの終了以外の理由で、現在のスキルセッションが終了した場合に送信されます。
  • CanFulfillIntentRequest: スキルが検出されたスロットを使用してインテントリクエストを理解できるかどうかを、スキルが実行される前に判別するために、Alexaサービスがスキルをクエリする場合に送信されます。

AudioPlayerPlaybackControllerなどの追加のインターフェースを実装している場合は、スキルは標準のリクエストタイプ以外の追加リクエストも受け取ります。インターフェースがスキルに送信できるリクエストの詳細については、インターフェースのドキュメントを参照してください。カスタムスキルインターフェースのリストについては、インターフェースを参照してください。

すべてのリクエスト形式については、カスタムスキルのJSONインターフェースリファレンス - リクエストフォーマットを参照してください。

LaunchRequest

LaunchRequestは、ユーザーがAlexaスキルへのリクエストを行ったが、特定のインテントを提供しなかったことを示すオブジェクトです。

{
  "type": "LaunchRequest",
  "requestId": "string",
  "timestamp": "string",
  "locale": "string"
}

LaunchRequestパラメーター

パラメーター 説明
type リクエストタイプを表す値: "LaunchRequest" string
timestamp ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。 string
requestId 特定のリクエストの固有IDを表します。 string
locale ユーザーのロケールを示すstringです。例:ja-JPサポートされているロケールコードを参照してください。 string

有効な応答タイプ

サービスは、LaunchRequestに対して、以下の任意の組み合わせで応答できます。

  • 標準の応答プロパティoutputSpeechcard、およびreprompt)。
  • 任意のAudioPlayerディレクティブ

    標準のプロパティとAudioPlayerディレクティブの両方を含める場合、Alexaは最初に標準のプロパティを処理します。たとえば、Playディレクティブと同じ応答にoutputSpeechを含めると、Alexaはあらかじめ用意されたテキストを読み上げてからオーディオのストリーミングを開始します。

  • 任意のDialogディレクティブ。ディレクティブのupdatedIntentパラメーターにインテントを指定する必要があります。これにより、ユーザーとのダイアログをすぐに開始できます。

    応答にDialogディレクティブと共にOutputSpeechを含めることができます。Dialog.Delegateの場合、Alexaはダイアログモデルで定義したプロンプトの前にoutputSpeechを読み上げます。その他のDialogディレクティブの場合、outputSpeechはスロット値の取得や確認を求めるプロンプトとして使われます。

CanFulfillIntentRequest

CanFulfillIntentRequestは、スキルが検出されたスロットを使用してインテントリクエストを理解し実行できるかどうかを、スキルが実行される前に判別するために、スキルをクエリするリクエストを表すオブジェクトです。リクエスト形式の詳細については、カスタムスキルの無指名対話を理解するを参照してください。

CanFulfillIntentRequestに対する応答

サービスは、CanFulfillIntentRequestに対して、canFulfillIntentを使用して応答できます。カスタムスキルの無指名対話を理解するを参照してください。

応答パラメーター全般については、応答本文の構文を参照してください。また、次のパラメーターはcanFulfillIntentに固有です。

canFulfillIntentパラメーター

パラメーター 説明 必須

canFulfill(インテント用)

スキルが検出されたスロットを使用してインテントを理解し実行できるかを判別するすべての応答を表します。有効な値は次のとおりです。

  • YES - スキルはすべてのスロットを理解し、すべてのスロットを満たして、リクエストを完全に実行できます。

  • NO - スキルはインテントを理解できないか、すべてのスロットを理解できないか、すべてのスロットを満たすことができません。

  • MAYBE - スキルはインテントを理解し、一部またはすべてのスロットを理解して、一部またはすべてのスロットを満たすことができます。MAYBEは、スキルがリクエストの一部を理解し、コールバックやユーザーとのマルチターン会話で追加のデータを取得できればリクエストを実行できるかもしれない場合にのみ、返されます。

ランク付けの判断では、AlexaはCanFulfillIntentRequestに対するスキルの応答を追跡し、ユーザーのフィードバックとあわせてそれを使用してスキルがユーザーのリクエストを満たしたかどうかを確認します。そのため、YESNO、またはMAYBEの応答は、スキルがユーザーのリクエストに応答するために使用する判断に影響を与える唯一の要素ではありません。

enum

slots

インテント内で検出された各スロットに対する詳細な応答およびスキルがスロットを理解し満たすことができたかどうかを表すマップです。マップはインテントのcanFulfill応答全体を補完するものであり、Alexaのランク付けおよびアービトレーションの判断が向上します。スロットの名前はキーであり、値はslotsタイプのオブジェクトです。各スロットで、canUnderstandがとることのできる値はYESNO、またはMAYBEであり、canFulfillがとることのできる値はYESまたはNOです。​

object

IntentRequest

IntentRequestは、ユーザーが何をしたいのかに基づいて、スキルに対して行われたリクエストを表すオブジェクトです。

{
  "type": "IntentRequest",
  "requestId": "string",
  "timestamp": "string",
  "dialogState": "string",
  "locale": "string",
  "intent": {
    "name": "string",
    "confirmationStatus": "string",
    "slots": {
      "SlotName": {
        "name": "string",
        "value": "string",
        "confirmationStatus": "string",
        "slotValue": {},
        "resolutions": {
          "resolutionsPerAuthority": [
            {
              "authority": "string",
              "status": {
                "code": "string"
              },
              "values": [
                {
                  "value": {
                    "name": "string",
                    "id": "string"
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

IntentRequestパラメーター

パラメーター 説明

type

リクエストのタイプを表す値: "IntentRequest"。

string

requestId

特定のリクエストの固有IDを表します。

string

timestamp

ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。

string

dialogState

マルチターンのダイアログのステータスを示す列挙値です。スキルにダイアログモデルがある場合、このプロパティも含まれます。取りうる値:

  • STARTED—ユーザーがダイアログのあるインテントを呼び出しました。
  • IN_PROGRESS—ダイアログが進行中です。
  • COMPLETED—ダイアログが完了しました。すべての必須スロットには値が含まれ、すべての値は、任意の定義されたスロット検証ルールを満たしています。ダイアログをAlexaにデリゲートする場合にのみ、この状態になることがあります。

ダイアログモデルがインテント確認ルールを定義する場合は、ユーザーがインテント全体を確認または拒否したかどうかにかかわらず(たとえば、確認プロンプトで「いいえ」と答える)、dialogStateCOMPLETEDになります。ユーザーのリクエストに応える前に、IntentオブジェクトでconfirmationStatusプロパティも確認します。

string

intent

ユーザーが何を望んでいるかを表すオブジェクトです。intentオブジェクトの定義については、Intentオブジェクトを参照してください。

object

locale

ユーザーのロケールを示すstringです。例:ja-JPサポートされているロケールコードを参照してください。

string

Intentオブジェクト

パラメーター 説明

name

インテントの名前を表す文字列です。

string

confirmationStatus

ユーザーがインテント全体を明示的に確認したか、拒否したかを示す列挙値です。取りうる値:

  • NONE
  • CONFIRMED
  • DENIED

slots

事前に定義されたインテントスキーマに基づいてユーザーの意図を詳しく示すキーと値のペアのマップです。マップは空である場合があります。

  • キーは、スロットの名前を示す文字列です。型:stringです。
  • 値は、型がslotのオブジェクトです。型:objectです。Slotオブジェクトを参照してください。

map

スキルが処理できるインテントの定義方法の詳細については、以下を参照してください。

Slotオブジェクト

名前 説明

confirmationStatus

ユーザーがこのスロットの値を明示的に確認したか、拒否したかを示す列挙値です。取りうる値: NONE, CONFIRMED, DENIED

Enum

name

スロットの名前を表す文字列です。

String

resolutions

ユーザーがスロットに1つの値を指定した場合に含まれます(slotValue.typeSimpleです)。ユーザー発話からキャプチャされた語句を解決した結果を表すResolutionsオブジェクトです。

カスタムスロットタイプまたは独自の値で拡張したビルトインスロットタイプを使用するスロットの場合に含まれます。slotValue.typeListの場合は省略されます。

このプロパティは下位互換を目的としており、1つのスロット値の解決を提供します。slotValueプロパティを使用して、1つまたは複数の値の解決を取得します。

Resolutionsオブジェクト

slotValue

スロットによってキャプチャされた値(1つまたは複数)を表すSlotValueオブジェクトです。

SlotValueオブジェクト

source

ユーザーから提供された値であることを示します。常にUSERです。

String

value

ユーザーがスロットに1つの値を指定した場合に含まれます(slotValue.typeSimpleです)。ユーザーがスロットについて話した値を表す文字列です。この発話は、ユーザーが話した実際の値です。エンティティに対して定義されている標準値やいずれかの同義語である必要はありません。slotValue.typeListの場合は省略されます。

このプロパティは下位互換を目的としており、1つのスロット値のみを含めることができます。slotValueプロパティを使用して、1つまたは複数の値を取得します。

String

Resolutionsオブジェクト

エンティティ解決のために同義語とID値によりカスタムスロットタイプを定義する方法については、スロットタイプ値の同義語とIDの定義(エンティティ解決)を参照してください。

名前 説明

resolutionsPerAuthority[]

エンティティ解決に使用可能なそれぞれの情報源を表すオブジェクトの配列です。情報源は、そのスロットに提供されるデータのソースを表しています。カスタムスロットタイプの場合、情報源は、開発者が定義したスロットタイプです。

Array

resolutionsPerAuthority[].authority

スロット値の情報源の名前です。カスタムスロットタイプの場合、この情報源ラベルには、スキルIDとスロットタイプ名が組み込まれます。

String

resolutionsPerAuthority[].status

スロットのエンティティ解決のステータスを表すオブジェクトです。

Object

resolutionsPerAuthority[].status.code

ユーザー発話を定義済みのスロットタイプに照らして解決しようと試みた結果を示すコードです。詳細については、エンティティ解決のステータスコードを参照してください。

Enum

resolutionsPerAuthority[].values

スロットの解決済みの値の配列です。配列の値は、最も一致する可能性の高いものから順に並べられます。このため、配列の最初の値が最も一致する値とみなされます。

Array

resolutionsPerAuthority[].values[].value

ユーザー発話とスロットタイプ定義に基づいた、スロットの解決済みの値を表すオブジェクトです。

Object

resolutionsPerAuthority[].values[].value.id

解決済みのスロット値に対して定義されている固有IDです。このIDは、スロットタイプ定義で定義されているIDに基づきます。スロット値とIDを定義する方法の詳細については、カスタムスロットタイプのエンティティ解決を参照してください。

String

resolutionsPerAuthority[].values[].value.name

解決済みのスロット値の文字列です。

String

SlotValueオブジェクト

SlotValueオブジェクトにはvalueまたはvaluesが含まれますが、両方は含まれません。ユーザーがスロットに1つの値を指定した場合、値はvalueプロパティになります。ユーザーがスロットに複数の値を指定した場合、値の配列はvaluesプロパティになります。

複数の値を収集するスロットの設定の詳細については、Collect Multiple Values in a Slotを参照してください。

名前 説明

resolutions

typeSimpleである場合に含まれます。ユーザー発話からキャプチャされた語句を解決した結果を表すResolutionsオブジェクトです。

カスタムスロットタイプまたは独自の値で拡張したビルトインスロットタイプを使用するスロットの場合に含まれます。

Resolutionsオブジェクト

type

スロットがユーザーから取得した値のタイプ。スロット値が1つの値である場合はSimple、スロット値が値の配列である場合はListです。

String

value

typeがSimpleである場合に含まれます。ユーザーがスロットについて話した値を表す文字列です。この発話は、ユーザーが話した実際の値です。エンティティに対して定義されている標準値やいずれかの同義語である必要はありません。

この値はSlotオブジェクトのvalueプロパティと同じです。

String

values

typeListである場合に含まれます。ユーザーが指定した値のセットを表すSlotValueオブジェクトの配列です。配列内の各オブジェクトには独自のtypevalue、およびresolutionsがあります。

SlotValueオブジェクトの配列

エンティティ解決のステータスコード

  • ER_SUCCESS_MATCH – 発話された値が正常に既知のエンティティに解決されました。
    • カスタムスロットタイプの場合、これは値がスロットタイプで明示的に定義された少なくとも1つの値または同義語と一致したことを示します。
    • 拡張されたビルトインスロットタイプの場合、追加した拡張値セット内の少なくとも1つの値または同義語に値が一致したことを示します。
    • エンティティ解決をサポートするビルトインスロットタイプの場合、値がAlexaナレッジグラフ内の少なくとも1つのエンティティに解決されたことを示します。
  • ER_SUCCESS_NO_MATCH – 発話された値が既知のエンティティに解決されませんでした。
  • ER_ERROR_TIMEOUT – タイムアウトのためエラーになりました。
  • ER_ERROR_EXCEPTION – 処理中に例外が発生したためエラーになりました。

有効な応答タイプ

サービスは、IntentRequestに対して、以下の任意の組み合わせで応答できます。

  • 標準の応答プロパティoutputSpeechcard、およびreprompt)。
  • 任意のAudioPlayerディレクティブ

    標準のプロパティとAudioPlayerディレクティブの両方を含める場合、Alexaは最初に標準のプロパティを処理します。たとえば、Playディレクティブと同じ応答にoutputSpeechを含めると、Alexaはあらかじめ用意されたテキストを読み上げてからオーディオのストリーミングを開始します。

  • 任意のDialogディレクティブ

    Dialog.Delegateの場合: dialogStateCOMPLETEDの場合、updatedIntentも別のインテントに設定する必要があります。updatedIntentがないか、元のインテントに設定されている場合、COMPLETEDのダイアログにDialog.Delegateを返すとエラーになります。dialogStateSTARTEDまたはIN_PROGRESSの場合、updatedIntentは元のインテントまたは新しいインテントに設定できます。

SessionEndedRequest

SessionEndedRequestは、セッションが終了したことを通知するために、Alexaスキルに対して行われたリクエストを表すオブジェクトです。開いているセッションが以下のいずれかの理由で閉じられた場合、サービスはSessionEndedRequestを受け取ります。

  1. ユーザーが「終了して」または「終了」と言った場合。
  2. ユーザーが応答しなかった場合。またはユーザーが、デバイスによるユーザーの応答聞き取り中に、音声インターフェースに定義されているインテントと一致しない言葉を発した場合。
  3. エラーが発生した場合。
{
  "type": "SessionEndedRequest",
  "requestId": "string",
  "timestamp": "string",
  "reason": "string",
  "locale": "string",
  "error": {
    "type": "string",
    "message": "string"
  }
}

SessionEndedRequestパラメーター

パラメーター 説明

type

リクエストのタイプを表す値: "SessionEndedRequest"

string

requestId

特定のリクエストの固有IDを表します。

string

timestamp

ISO 8601形式で表された文字列で、Alexaがリクエストを送信した日時を提供します。スキルをウェブサービスとしてホスティングしているときに、リクエストを検証するために使用されます。

string

reason

セッションが終了した理由を示します。取りうる値:

  • USER_INITIATED: ユーザーが明示的にセッションを終了しました。
  • ERROR: エラーが発生したために、セッションが終了しました。
  • EXCEEDED_MAX_REPROMPTS: ユーザーが応答しないか、音声インターフェースで定義されたインテントのいずれとも一致しない発話で応答しました。

string

locale

ユーザーのロケールを示すstringです。例:ja-JPサポートされているロケールコードを参照してください。

string

error

発生したエラーに関する詳細な情報を提供するエラーオブジェクトです。このオブジェクトには、次のプロパティが含まれています。

  • type:発生したエラーのタイプを示すstringINVALID_RESPONSEDEVICE_COMMUNICATION_ERRORINTERNAL_SERVICE_ERRORENDPOINT_TIMEOUT)。
  • message:エラーについての詳細な情報を提供するstring

object

有効な応答タイプ

スキルは、SessionEndedRequestに応答を返すことはできません。

リクエストの例

LaunchRequestの例

{
  "version": "1.0",
  "session": {
    "new": true,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {},
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "deviceId": "string",
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "LaunchRequest",
    "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "locale": "string"
  }
}

IntentRequestの例

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {
      "supportedHoroscopePeriods": {
        "daily": true,
        "weekly": false,
        "monthly": false
      }
    },
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "IntentRequest",
    "requestId": " amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "dialogState": "COMPLETED",
    "locale": "string",
    "intent": {
      "name": "GetZodiacHoroscopeIntent",
      "confirmationStatus": "NONE"
      "slots": {
        "ZodiacSign": {
          "name": "ZodiacSign",
          "value": "virgo",
          "confirmationStatus": "NONE"
        }
      }
    }
  }
}

SessionEndedRequestの例

{
  "version": "1.0",
  "session": {
    "new": false,
    "sessionId": "amzn1.echo-api.session.0000000-0000-0000-0000-00000000000",
    "application": {
      "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
    },
    "attributes": {
      "supportedHoroscopePeriods": {
        "daily": true,
        "weekly": false,
        "monthly": false
      }
    },
    "user": {
      "userId": "amzn1.account.AM3B00000000000000000000000"
    }
  },
  "context": {
    "System": {
      "application": {
        "applicationId": "amzn1.echo-sdk-ams.app.000000-d0ed-0000-ad00-000000d00ebe"
      },
      "user": {
        "userId": "amzn1.account.AM3B00000000000000000000000"
      },
      "device": {
        "supportedInterfaces": {
          "AudioPlayer": {}
        }
      }
    },
    "AudioPlayer": {
      "offsetInMilliseconds": 0,
      "playerActivity": "IDLE"
    }
  },
  "request": {
    "type": "SessionEndedRequest",
    "requestId": "amzn1.echo-api.request.0000000-0000-0000-0000-00000000000",
    "timestamp": "2015-05-13T12:34:56Z",
    "reason": "USER_INITIATED",
    "locale": "string"
  }
}

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

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

インターフェース