カスタムルールを追加してAPIのレスポンスを変える

APIの応答を、デフォルトのものからカスタマイズする方法について記載します。
例えば、「テレビが欲しい」という入力に対して「METHOD:shopping、PARAM_QUERY:テレビ」のように独自の応答ドメインや応答パラメータを含んだレスポンスを返却させることができるようになります。

仕様

「sample<n>=<応答ドメイン>,<発話パターン>」のようなリクエストパラメータをparams/context以下に追加することで、指定された<発話パターン>に対して<応答ドメイン>をレスポンスで返却できます（<n>は0 1 ... 999のみ）。
また、「dict<m>=<辞書名>,<単語リスト>」のようなリクエストパラメータもあわせて使用することで、<発話パターン>で独自の辞書を参照することができます（<m>は0 1 ... 99のみ）。

詳細は下記をご覧ください。

ユースケース

a. 特定の入力テキストに対して応答ドメインを変更したい

例 追加するリクエストパラメータ
「こんにちは」の応答ドメインをhelloに sample0=hello,こんにちは

下記は「q=こんにちは&sample0=hello,こんにちは」に対するレスポンス例です。

{
"result": {
  "INTEXT": "こんにちは",
  "METHOD": "hello",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521532126",
  "VAR_TEST_BTSC": "46"
}
}

b.1. aに加えて、入力の一部をキャプチャして応答パラメータに含めたい

例 追加するリクエストパラメータ
「テレビが欲しい」の応答ドメインをshoppingにし、テレビの部分をPARAM_QUERYとしてレスポンスパラメータに含める sample0=shopping,(?<query>テレビ)が欲しい

下記は「q=テレビが欲しい&sample0=shopping,(?<query>テレビ)が欲しい」に対するレスポンス例です。

{
"result": {
  "INTEXT": "テレビが欲しい",
  "METHOD": "shopping",
  "PARAM_QUERY": "テレビ",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521532675",
  "VAR_TEST_BTSC": "55"
}
}

b.2. aに加えて、入力の一部をキャプチャして応答パラメータに含めたい

例 追加するリクエストパラメータ
「テレビが欲しい」の応答ドメインをshoppingにし、テレビの部分をPARAM_QUERYとしてレスポンスパラメータに含める sample0=shopping,(?<query>.+)が欲しい

正規表現に似た記法にも一部対応しています。

c. 複数の入力に対してまとめて応答ドメインを変更したい

例 追加するリクエストパラメータ
「こんにちは」でも「おはよう」でも応答ドメインをhelloに sample0=hello,{おはよう|こんにちは}

下記は「q=こんにちは&sample0=hello,{おはよう|こんにちは}」に対するレスポンス例です。

{
"result": {
  "INTEXT": "こんにちは",
  "METHOD": "hello",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521532126",
  "VAR_TEST_BTSC": "46"
}
}

d.1. 複数のカスタマイズを組み合わせたい

例 追加するリクエストパラメータ
「こんにちは」でも「おはよう」でも応答ドメインをhelloに
  • sample0=hello,おはよう
  • sample1=hello,こんにちは

下記は「q=こんにちは&sample0=hello,おはよう&sample1=hello,こんにちは」に対するレスポンス例です。

{
"result": {
  "INTEXT": "こんにちは",
  "METHOD": "hello",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521532126",
  "VAR_TEST_BTSC": "46"
}
}

d.2. 複数のカスタマイズを組み合わせたい

例 追加するリクエストパラメータ
「こんにちは」ではhello、「はい」ではyesを応答ドメインに
  • sample0=hello,こんにちは
  • sample1=yes,はい

下記は「q=こんにちは&sample0=hello,こんにちは&sample1=yes,はい」に対するレスポンス例です。

{
"result": {
  "INTEXT": "こんにちは",
  "METHOD": "hello",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521532126",
  "VAR_TEST_BTSC": "46"
}
}

e. カスタム辞書を利用したい

例 追加するリクエストパラメータ
「傘が欲しい」や「長靴が欲しい」などの、「<雨のアイテム>が欲しい」でneed_rain_itemを応答ドメインにし、<雨のアイテム>をparam_rain_itemとして応答パラメータに含める。
  • sample0=need_rain_item,(?<rain_item>{$RAIN_ITEM})が欲しい
  • dict0=$RAIN_ITEM,長靴,傘,合羽,折り畳み傘

下記は「q=長靴が欲しい&sample0=need_rain_item,(?<rain_item>{$RAIN_ITEM})が欲しい&dict0=$RAIN_ITEM,長靴,傘,合羽,折り畳み傘」に対するレスポンス例です。 

{
"result": {
    "INTEXT": "長靴がほしい",
    "METHOD": "need_rain_item",
    "PARAM_RAIN_ITEM": "長靴",
    "STATUS": "200",
    "VAR_INTEXT_TIMESTAMP": "1521533741",
    "VAR_TEST_BTSC": "41"
}
}

f. システム辞書を利用したい

例 追加するリクエストパラメータ
「<地名>のイベント情報」で、event_infoを応答ドメインにし<地名>をparam_placeとして応答パラメータに含める。
  • sample0=event_info,(?<place>{$SYS.LOCATION})のイベント情報

下記は「q=大阪のイベント情報&sample0=event_info,(?<place>{$SYS.LOCATION})のイベント情報」に対するレスポンス例です。

{
"result": {
  "INTEXT": "大阪のイベント情報",
  "METHOD": "event_info",
  "PARAM_PLACE": "大阪",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1524126275",
  "VAR_TEST_BTSC": "35"
}
}

g. システム辞書に単語を追加したい

例 追加するリクエストパラメータ
オリジナルのレシピ名である「ふわとろオムそば」をレシピ名として認識させたい。
  • dict0=$SYS.RECIPE-DISH,ふわとろオムそば

下記は「q=ふわとろオムそばのレシピ」（単語追加前）と「q=ふわとろオムそばのレシピ&dict0=$SYS.RECIPE-DISH,ふわとろオムそば」（単語追加後）のレスポンス例です。

{
"result": {
  "INTEXT": "ふわとろオムそばのレシピ",
  "METHOD": "SEARCH",
  "PARAM_METHOD_SUBCAT": "RECIPE",
  "PARAM_QUERY": "そば",
  "STATUS": "200",
  "VAR_INTEXT": "ふわとろオムそばのレシピ",
  "VAR_INTEXT_NORMALIZED": "ふわとろオムそばのレシピ",
  "VAR_INTEXT_TIMESTAMP": "1524126837",
  "VAR_TEST_BTSC": "57"
}
}
{
"result": {
  "INTEXT": "ふわとろオムそばのレシピ",
  "METHOD": "SEARCH",
  "PARAM_METHOD_SUBCAT": "RECIPE",
  "PARAM_QUERY": "ふわとろオムそば",
  "STATUS": "200",
  "VAR_INTEXT": "ふわとろオムそばのレシピ",
  "VAR_INTEXT_NORMALIZED": "ふわとろオムそばのレシピ",
  "VAR_INTEXT_TIMESTAMP": "1524126765",
  "VAR_TEST_BTSC": "45"
}
}

z. より本格的な例

例 追加するリクエストパラメータ
最小限の機能を備えた対話アシスタント
  • dict0=$PLACE,東京,大阪,青森
  • dict1=$VOLUME,音,声,音量,ボリューム
  • sample0=help,使い方
  • sample1=help,{何|なに}が?{できる|出来る}
  • sample2=volume_up,{$VOLUME}を?{大きく|アップ}
  • sample3=volume_up,{$VOLUME}が?小さい
  • sample4=volume_down,{$VOLUME}を?{小さく|ダウン}
  • sample5=volume_down,{$VOLUME}が?大きい
  • sample6=launch_app,(?<APP>.+)を起動
  • sample7=weather,(?<DATE>{今日|明日})の?天気
  • sample8=weather,(?<DATE>{今日|明日})の?(?<PLACE>${PLACE})の?天気
  • sample9=weather,{傘|かさ}は?{必要|いらない}
  • sample10=transit,(?<FROM>${PLACE})から(?<TO>${PLACE})まで
  • sample11=transit,(?<TO>${PLACE})に?行きたい
  • sample12=news,{今日|最新|現在}の?{ニュース|トピックス|出来事}
  • sample13=news,{今日|最新|現在}の?(?<CATEGORY>{芸能|経済|科学|スポーツ})の?{ニュース|トピックス|出来事}
  • sample14=maps,(?<PLACE>${PLACE})の?地図
  • sample15=local,(?<PLACE>${PLACE}駅?)の?{近く}?の(?<QUERY>{レストラン|歯医者|ラーメン屋})
  • sample16=clock,{今|現在}の?{時刻|時間}
  • sample17=clock,{今|現在}何時
  • sample18=stock,(?<QUERY>{LINEヤフー|ソフトバンク})の?株価
  • sample19=stock,(?<QUERY>{日経平均|ダウ})は?{いくら|教えて}?
  • sample20=recipe,(?<DISH>{カレー|肉じゃが|ハンバーグ})の?{レシピ|作り方}
  • sample21=video,(?<CATEGORY>{映画|アニメ|ドラマ|お笑い})の?動画
  • sample22=shopping,(?<ITEM>{靴|洋服|バッグ})を?買いたい
  • sample23=shopping,(?<ITEM>.+)が?{ほしい|欲しい}
  • sample24=search,(?<QUERY>.+)を検索
  • sample25=agent_birthday,{誕生日|生年月日}は
  • sample27=agent_name,{あなた|お前|君}の?名前
  • sample28=agent_marry_me,結婚して
  • sample29=thank_you,{ありがとう|感謝してます}
  • sample30=greetings,{こんにちは|こんばんは|ハロー}
  • sample31=bye,{さようなら|バイバイ}
  • sample32=you_are_welcome,{どういたしまして|いいんですよ}

下記に、いくつかの入力テキストに対するレスポンス例を示します。

「何ができる」

{
"result": {
  "INTEXT": "何ができる",
  "METHOD": "help",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521534816",
  "VAR_TEST_BTSC": "36"
}
}

「トゲアリトゲナシトゲトゲを検索」

{
"result": {
  "INTEXT": "トゲアリトゲナシトゲトゲを検索",
  "METHOD": "search",
  "PARAM_QUERY": "トゲアリトゲナシトゲトゲ",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521535181",
  "VAR_TEST_BTSC": "41"
}
}

「東京のレストラン」

{
"result": {
  "INTEXT": "東京のレストラン",
  "METHOD": "local",
  "PARAM_PLACE": "東京",
  "PARAM_QUERY": "レストラン",
  "STATUS": "200",
  "VAR_INTEXT_TIMESTAMP": "1521535308",
  "VAR_TEST_BTSC": "48"
}
}

アプリケーションの管理

目次

利用のルール

開発のヒント