11. metadata¶
11.1. 概要¶
対話APIリクエストボディに設定された metadata情報は、シナリオの変数データ(テキスト、または、JSON)として用いることができます。
また、対話APIレスポンスボディに設定する metadata情報も、シナリオの変数データとして設定することができます。
11.2. 対話APIで設定されたmetadataの利用¶
対話APIリクエストでJSONの要素として指定された metadata情報を、対話シナリオで利用可能な変数に展開した状態で保持します。
APIから渡されたJSON内の
metadata 要素は、変数名 __USER_METADATA__ に展開します。metadata要素がJSON形式の場合、 json タグを用いることで、__USER_METADATA__内の要素を取得することができます。
__USER_METADATA__の内容は、対話APIのレスポンスを返却するまでの間有効です。継続して__USER_METADATA__の内容を利用する場合、別途変数に代入してください。
メタデータ変数__USER_METADATA__はローカル変数（var）として扱いますが、ユーザ毎の管理情報であるため、特別に、レスポンスを返却するまでの間は、srai処理でも引き継いで利用することができます。
11.2.1. metadataの変数への展開方法¶
対話APIからmetadataとして渡されたデータを、変数__USER_METADATA__に展開します。
metadataには、テキストデータと、JSONデータを設定することができ、各々のシナリオでの取り扱い方を説明します。
尚、以下の説明では、myServiceサブエージェントを利用して情報を取得し、以下の結果がJSONデータとして返却されることを前提として記載します。
返却されたデータは、変数
__SUBAGENT__.myService に展開されています。サブエージェント連携についての詳細は、 SubAgent を参照してください。{
"transportation": {
"station": {
"departure": "東京",
"arrival": "京都"
},
"time": {
"departure": "2018/11/1 11:00",
"arrival": "2018/11/1 13:30"
},
"facility": ["鹿苑寺", "清水寺", "伏見稲荷大社"]
}
}
11.2.1.1. テキストデータとしての取り扱い方¶
テキストデータの場合、変数__USER_METADATA__に対する get タグで内容を取得することができます。
対話APIコールのmetadataとして、以下のように文字列が与えられた場合を説明します。
{
"locale": "ja-JP",
"time": "2018-07-01T12:18:45+09:00",
"topic": "*",
"utterance": "subagent こんにちは",
"metadata": "メタデータテスト"
}
シナリオには以下のように記載します。
サブエージェントの返却データは、
__SUBAGENT__.myService に保持されており( 詳細は SubAgent に記載)、要素のキーを指定することでJSON内の値を取得しています。<aiml>
<!-- sub agent execute -->
<category>
<pattern>subagent *</pattern>
<template>
<think>
<sraix service="myService">
<star /><space />
<get var="__USER_METADATA__" />
</sraix>
<set name="departure"><json var="__SUBAGENT__.myService.transportation.station.departure" /></set>
<set name="arrival"><json var="__SUBAGENT__.myService.transportation.station.arrival" /></set>
</think>
<get name="departure"/>から<get name="arrival"/>までを検索します。
</template>
</category>
</aiml>
ユーザ発話が「subagent こんにちは」の場合、以下のように展開されたデータが、サブエージェントに渡ります。
| 引数番号 | サブエージェントに渡された内容 |
|---|---|
| 第1引数 | こんにちは |
| 第2引数 | メタデータテスト |
※ 引数を空白で分離する為に、space要素を使用しています。
11.2.1.2. JSONデータとしての取り扱い方¶
対話APIコールのmetadataとして、以下のようにJSONデータが与えられた場合を説明します。
{
"locale": "ja-JP",
"time": "2018-07-01T12:18:45+09:00",
"topic": "*",
"utterance": "subagent こんにちは",
"metadata": {"arg1": "value1", "arg2": "value2", "arg3": "value3"}
}
metadataがJSONの場合、 json タグを使用することで、JSON形式のデータとして取り扱うことができます。
<aiml>
<!-- sub agent execute -->
<category>
<pattern>subagent *</pattern>
<template>
<think>
<sraix service="myService">
<star /><space />
<json var="__USER_METADATA__.arg1" /><space />
<json var="__USER_METADATA__.arg2" /><space />
<json var="__USER_METADATA__.arg3" />
</sraix>
<set name="departure"><json var="__SUBAGENT__.myService.transportation.station.departure" /></set>
<set name="arrival"><json var="__SUBAGENT__.myService.transportation.station.arrival" /></set>
</think>
<get name="departure"/>から<get name="arrival"/>までを検索します。
</template>
</category>
</aiml>
ユーザ発話が「subagent こんにちは」の場合、以下のように展開されたデータがサブエージェントに渡ります。
| 引数番号 | サブエージェントに渡された内容 |
|---|---|
| 第1引数 | こんにちは |
| 第2引数 | value1 |
| 第3引数 | value2 |
| 第4引数 | value3 |
※ 引数を空白で分離する為に、space要素を使用しています。
11.2.2. サブエージェントにmetadata全てを引き渡す方法¶
対話APIからmetadataとして渡されたJSONデータを、サブエージェントにそのままJSONとして渡すことができます。
json タグの属性に__USER_METADATA__を指定することで、metadataに設定されたデータ全てを取得し、サブエージェントに引き渡します。
<aiml>
<!-- sub agent execute -->
<category>
<pattern>subagent *</pattern>
<template>
<think>
<sraix service="myService">
<star /><space />
<json var="__USER_METADATA__" />
</sraix>
<set name=departure><json var="__SUBAGENT__.myService.transportation.station.departure" /></set>
<set name=arrival><json var="__SUBAGENT__.myService.transportation.station.arrival" /></set>
</think>
<get name='departure'>から<get name='arrival'>までを検索します。
</template>
</category>
</aiml>
ユーザ発話が「subagent こんにちは」の場合、myServiceサブエージェントに対する第2引数で指定されたJSONがそのまま渡ります。
| 引数番号 | サブエージェントに渡された内容 |
|---|---|
| 第1引数 | こんにちは |
| 第2引数 | {‘arg1’: ‘value1’, ‘arg2’: ‘value2’, ‘arg3’: ‘value3’} |
※ 引数を空白で分離する為に、space要素を使用しています。
11.3. 対話APIに返すmetadataの設定¶
対話APIのレスポンスに設定するmetadata要素の指定は、シナリオの返却用メタデータ変数__SYSTEM_METADATA__にデータを設定することで行います。
レスポンスのmetadata要素には、テキストデータ、または、JSONデータを設定することができ、各々のシナリオでの取り扱い方を説明します。
メタデータ変数__SYSTEM_METADATA__はローカル変数（var）として扱いますが、ユーザ毎の管理情報であるため、特別に、レスポンスを返却するまでの間は、srai処理でも引き継いで利用することができます。
11.3.1. テキストデータとしての取り扱い方¶
以下の例では、myServiceサブエージェントから取得したデータの中の”出発地”のテキストを、返却用メタデータ変数に設定しています。
サブエージェントから返却されたJSONから、出発地：”station.departure”の要素(テキスト)を取得し、__SYSTEM_METADATA__に設定します。
これによって、対話APIのレスポンスのmetadata要素として、テキストデータが返却されます。
<aiml>
<!-- sub agent execute -->
<category>
<pattern>subagent *</pattern>
<template>
<think>
<sraix service="myService">
<star />
</sraix>
<set var="__SYSTEM_METADATA__"><json var="__SUBAGENT__.myService.transportation.station.departure" /></set>
</think>
メタデータに出発地を設定しました。
</template>
</category>
</aiml>
Input: subagent 東京
Output: メタデータに出発地を設定しました。
metadataの内容: “東京”
11.3.2. JSONデータとしての取り扱い方¶
以下の例では、myServiceサブエージェントから取得したJSONデータを、返却用メタデータ変数に設定しています。
json タグで、サブエージェントから返却されたJSONデータ全体を__SYSTEM_METADATA__に設定します。
これによって、対話APIのレスポンスのmetadata要素として、JSONデータが返却されます。
<aiml>
<!-- sub agent execute -->
<category>
<pattern>subagent *</pattern>
<template>
<think>
<sraix service="myService">
<star />
</sraix>
<set var="__SYSTEM_METADATA__"><json var="__SUBAGENT__.myService" /></set>
</think>
メタデータにサブエージェントの処理結果を設定しました。
</template>
</category>
</aiml>
Input: subagent 東京
Output: メタデータにサブエージェントの処理結果を設定しました。
metadataの内容:
{“transportation”:
{“station”:
{“departure”: “東京”,
“arrival”: “京都”},
“time”:
{“departure”: “2018/11/1 11:00”,
“arrival”: “2018/11/1 13:30”},
“facility: [“鹿苑寺”, “清水寺”, “伏見稲荷大社”]}}
関連項目: 対話API、 対話APIデータの変数利用、 JSON、 SubAgent