FAQ 検索•™師データ登録API、教師データ削除API、FAQデータ登録/更新API、FAQデータ削除APIに関する記述を追記 ... 408 Request Timeout リクエストタイムアウトが発生しました。

1/43

1 / 43

FAQ検索

API リファレンス

第 1.9 版

2019 年 6 月 26 日

富士通株式会社

2/43

2 / 43

変更履歴

版数修正日修正箇所修正内容

1.0 2017/7/27 初版

1.1 2017/10/19 2.7

2.8

3.4

3.5

3.6

3.7

付録 B

教師データ登録 API、教師デー

タ削除 API、FAQデータ登録/更

新 API、FAQ データ削除 API に

関する記述を追記

1.2 2017/12/14 3.1

3.2

3.3

リクエストヘッダ―を追記

ハイライト機能について追記

1.3 2018/2/15 3.3 実行例の修正

1.4 2018/3/6 3.1 実行例の修正

1.5 2018/3/23 2.2 暗号化プロトコルのサポートについ

て記載

1.6 2018/6/21 3.1

3.2

3.8

3.9

フレーズ検索について追記

詳細取得 API のパラメータを追

加

日付リスト取得 API、操作ログ取

得 API に関する記述を追記

1.7 2018/8/2 2.5 ステータスコードの追記

3/43

3 / 43

2.6.1 エラーメッセージの修正

1.8 2019/2/27 3.4.1

3.4.2

付録 A

データ登録レコード数の上限につ

いて追記

エラーコードの追記

レスポンスのエスケープに関する注

意書きを追記

1.9 2019/06/26 2.5

2.6.1

ステータスコードの追記

レスポンスのエラーメッセージを見

直し

4/43

4 / 43

はじめに

本書の目的

本書は、Zinrai プラットフォームサービスが提供する API について説明しています。

本書の対象読者

本書は、Zinraiプラットフォームサービスでアプリケーションやサービスを開発・運用する方を対象に記述します。

本書を読むためには、以下の知識が必要です。

・インターネットに関する基本的な知識

・使用するオペレーティングシステムに関する基本的な知識

・WebAPI に関する基本的な知識

お願い

・本書で使用している画面イメージ、実行例などは、最新環境のものとは異なることがあります。

・本書は、予告なしに変更されることがあります。

・本書を無断で他に転用しないようお願いします。

・本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については、当社

はその責を負いません。

輸出管理規制について

本ドキュメントを輸出または第三者へ提供する場合は、お客様が居住する国および米国輸出管理関連法

規等の規制をご確認のうえ、必要な手続きをおとりください。

登録商標について

本書に記載されている会社名および製品名は、それぞれ各社の商標または登録商標である場合があります。

なお、本書では、会社名および製品名に付記される登録表示((TM)または(R))は省略しています。

FAQ 検索 API リファレンス

All Rights Reserved, Copyright©FUJITSU LIMITED 2017-2019

5 / 43

目次第 1 章 API 概要 ................................................................................................. 7

1.1 基本利用方法 ............................................................................................. 7

1.2 API 一覧 ................................................................................................... 7

第 2 章共通仕様 ................................................................................................. 8

2.1 エンドポイント ............................................................................................... 8

2.2 プロトコル .................................................................................................... 8

2.3 文字コード .................................................................................................. 8

2.4 HTTP ヘッダ ................................................................................................ 8

2.5 HTTP ステータスコード ..................................................................................... 9

2.6 エラー形式 .................................................................................................. 9

2.6.1 共通ヘッダ関連のエラー ............................................................................ 10

2.7 学習で使用するデータの説明 ........................................................................... 11

2.8 注意事項 ................................................................................................. 11

第 3 章 API 詳細 ............................................................................................... 12

3.1 検索 ...................................................................................................... 12

3.1.1 リクエスト ............................................................................................ 12

3.1.2 レスポンス ........................................................................................... 16

3.1.3 実行例 .............................................................................................. 19

3.2 詳細取得 ................................................................................................. 20

3.2.1 リクエスト ............................................................................................ 20

3.2.2 レスポンス ........................................................................................... 22

3.2.3 実行例 .............................................................................................. 24

3.3 フィードバック .............................................................................................. 25

3.3.1 リクエスト ............................................................................................ 25

3.3.2 レスポンス ........................................................................................... 26

3.3.3 実行例 .............................................................................................. 27

3.4 教師データ登録 .......................................................................................... 27

3.4.1 リクエスト ............................................................................................ 28

3.4.2 レスポンス ........................................................................................... 29

3.4.3 実行例 .............................................................................................. 30

3.5 教師データ削除 .......................................................................................... 30

3.5.1 リクエスト ............................................................................................ 30

3.5.2 レスポンス ........................................................................................... 31

3.5.3 実行例 .............................................................................................. 31

3.6 FAQ データ登録/更新 ................................................................................... 32



6 / 43

3.6.1 リクエスト ............................................................................................ 32

3.6.2 レスポンス ........................................................................................... 32

3.6.3 実行例 .............................................................................................. 34

3.7 FAQ データ削除 .......................................................................................... 34

3.7.1 リクエスト ............................................................................................ 35

3.7.2 レスポンス ........................................................................................... 35

3.7.3 実行例 .............................................................................................. 36

3.8 日付リスト取得 ........................................................................................... 36

3.8.1 リクエスト ............................................................................................ 36

3.8.2 レスポンス ........................................................................................... 37

3.8.3 実行例 .............................................................................................. 37

3.9 操作ログ取得 ............................................................................................ 37

3.9.1 リクエスト ............................................................................................ 38

3.9.2 レスポンス ........................................................................................... 38

3.9.3 実行例 .............................................................................................. 40

付録 A パラメータ仕様 ........................................................................................... 41

付録 B データ仕様 ............................................................................................... 42

質問データのカラムについて .................................................................................... 42

紐づけデータのカラムについて .................................................................................. 42



7 / 43

第1章 API概要

FAQ 検索では、自然文での FAQ 検索を行うことができます。

1.1 基本利用方法

本 API の基本的な利用方法は以下の通りです。

1. 検索 API により、質問文（自然文）に対する FAQ 検索を行うことができます。

2. 詳細取得 API により、FAQ 検索結果から詳細取得を行うことができます。

3. フィードバック API により、検索に使用した質問文（自然文）と、検索によって得られた結果が参考に

なったかどうかの情報を登録することができます。

4. 教師データ登録 API および教師データ削除 API により、お客様の教師データ※1 を登録・削除すること

ができます。

5. FAQ データ登録/更新 API および FAQ データ削除 API により、検索対象となる FAQ 項目１件を

登録/更新・削除することができます。

6. 日付リスト取得 API および操作ログ取得 API により、操作ログ※2 を取得することで、FAQ 検索におい

て、利用者が検索から問題解決までにどのような操作を実施したかの分析などに利用することができま

す。 ※1

教師データとは、FAQ 検索では質問データと紐づけデータのことを指します。

※2操作ログとは、検索 API、詳細取得 API およびフィードバック API のリクエスト履歴のことを指します。

1.2 API一覧

提供する API 一覧は、以下の通りです。

概要 URI メソッド参照

検索 /FAQSearch/v1/documents/_search POST 3.1

詳細取得 /FAQSearch/v1/documents/{id} GET 3.2

フィードバック /FAQSearch/v1/feedback POST 3.3

教師データ登録 /FAQSearch/v1/admin/data/{type} POST 3.4

教師データ削除 /FAQSearch/v1/admin/data/{type} DELETE 3.5

FAQ データ登録/更新 /FAQSearch/v1/admin/documents/{id} PUT 3.6

FAQ データ削除 /FAQSearch/v1/admin/documents/{id} DELETE 3.7

日付リスト取得 /FAQSearch/v1/admin/operationlogs GET 3.8

操作ログ取得 /FAQSearch/v1/admin/operationlogs/{date} GET 3.9



8 / 43

第2章共通仕様

本章では、本 API の共通仕様を説明します。

2.1 エンドポイント

zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com

2.2 プロトコル

HTTPS

※暗号化プロトコルは TLS1.2 のみサポートしています。

2.3 文字コード

UTF-8

2.4 HTTP ヘッダ

ヘッダ項目名値値の説明

X-Access-Token 例:

5f744f66-56d9-4c8c-87b2-c8

70f3b82817

本サービスでは K5 の API 認証を利用した

アクセス制限を行っております。

API 利用者は本サービスの API をコールす

る前に K5 認証よりアクセストークンを取得

し、本ヘッダの値にアクセストークンを設定し

て API をコールしてください。

※アクセストークンの取得方法等について

は、こちらのリファレンスをご参照ください。

X-Service-Code “サービスコード[10 桁]”-“API 番号

[5 桁]”

例: FJAI000011-00001

K5 PaaS Portal で各サービスに割り振ら

れたコード（10 桁）と、各サービスの各

API が持つ固有の番号（5 桁）をハイフ

ンで繋ぎ合わせた文字列です。実際の値

は、「第 3 章 API 詳細」のリクエストヘッダ

仕様をご参照ください。

https://k5-doc.jp-east-1.paas.cloud.global.fujitsu.com/doc/jp/apiauth/document/index.html



9 / 43

2.5 HTTP ステータスコード

ステータスコード意味説明

200 OK リクエストは正常に処理されました。

201 Created リクエストは正常に処理され、新規リソースが作成さ

れました。

202 Accepted リクエストを正常に受け付けました。

※主に非同期処理へのメッセージ

400 Bad Request リクエストの内容に誤りがあります。

401 Unauthorized 認証に失敗しました。

404 Not Found リソースが見つかりませんでした。

405 Method Not

Allowed

HTTP メソッドに誤りがありました。

408 Request Timeout リクエストタイムアウトが発生しました。

再度、API の実行をお願いします。

500 Internal Server

Error

サーバ内部にエラーが発生しました。

2.6 エラー形式

JSON で以下の情報を返します。

名前説明

error エラー情報のオブジェクト

code エラーコード

title エラータイトル(英語)

message エラーメッセージ(英語)

※レスポンス例

{

“error”: {

”code”: 409,

“title”: “Invalid parameter”,

“message”: “The parameter is invalid.”

}

}



10 / 43

2.6.1 共通ヘッダ関連のエラー

コードタイトルメッセージ

400 Bad Request You have requested incorrect parameters.

上記のエラーが返却された場合、以下を確認してください。

・リクエストに X-Access-Token ヘッダが無い

・X-Access-Token ヘッダの値が正しくない

・リクエストに X-Service-Code ヘッダが無い

・X-Service-Code ヘッダの値のフォーマットが正しくない


401 Unauthorized This server could not verify your authorization to access.




404 Not Found We could not find the resource you requested.


・X-Service-Code ヘッダの値が正しくない

・URL が誤っている


405 Method Not

Allowed

The method is not allowed for the requested URL.


・HTTP メソッドが誤っている


500 Internal Server

Error

The server encountered an internal error.





11 / 43

2.7 学習で使用するデータの説明

本項では学習で使用するデータについて説明します。詳細な仕様については「付録 B データ仕様」をご参照く

ださい。

データ説明容量形式

質問データ質問文などの質問情報合計で

1GB 以下

CSV

紐づけデータ質問 ID に対する FAQ ID CSV

質問データの例

question_id,text01,timestamp,item01,item02

"11-091-132","サーバ壊れました","2017-06-27T10:00:00+09:00","win2016","電

源"

"11-831221","うごきません",,"rhel8","keyboard"

紐づけデータの例

question_id,label_id,timestamp

"11-091-132","a11-09/a12-89","2017-06-27T10:00:00+09:00"

"11-831221","a11-831221",

2.8 注意事項

FAQ 検索の利用開始時は、学習済みモデルの作成が必要です。学習済みモデルの作成は、お客

様により別途、Zinrai 導入支援サービスを契約していただく必要があります。

FAQ 検索の学習済みモデルを更新する際は、お客様により別途 Zinrai 運用サービスを契約してい

ただく必要があります。

FAQ 検索では、定期学習（Zinrai 運用サービスで実施）で作成した学習済みモデルをサービスに

組み込んでいる間はサービスのご利用は出来ません。

FAQ 検索では、登録出来る学習済みモデルの数はクライアント ID 毎に１つです。



12 / 43

第3章 API詳細

本章では、各 API の詳細仕様を説明します。パラメータの表記については、「付録 A パラメータ仕様」をご

参照ください。

3.1 検索

指定された質問文（自然文）で FAQ を検索します。

URI /FAQSearch/v1/documents/_search

HTTPメソッド POST

3.1.1 リクエスト

ヘッダ

名前値必須補足

X-Service-Code FJAI000011-00002 ○ -

Content-Type application/json ○ -

X-Forwarded-User {任意の文字列} 学習で利用されるデータに対する付加

情報。例えば利用者を特定可能なア

カウント情報を指定することで、学習精

度の向上につなげることが可能。

最大文字数は 255 文字。

上限値を超えた場合は 400 エラーが

返却される。

HTTP/1.1 の HTTP ヘッダ仕様で定

められたすべての文字を使用可能。

パラメータ

なし

メッセージボディ

形式：JSON

名前説明必須既定値型

query 質問文を格納するオブジェクト。 ○ - object(Query1)

filter 絞込み条件を格納するオブジェクト。 - object(Filter1)

options その他のオプションを格納するオブジェクト。 - object(Options1)



13 / 43

Query1


text 質問文

自然文を指定可能。

指定した質問文で検索を行う。

値を空で指定した場合は全件がヒットする。

最大文字数は5000文字。上限値を超えた

場合は 400 エラーが返却される。

例:インストールに失敗する。

○ - string

Filter1


fields フィールド※を指定した絞込み・除外キーワ

ードを格納するオブジェクト

複数{フィールド名}要素を指定した場合

はそれぞれの要素を and 条件で検索す

る。最大オブジェクト数は 100 個。

上限値を超えた場合は400エラーが返却

される。

※FAQ を格納している DB のカラム

- object(Filter2)

phrase フレーズによる絞込み条件を格納するオブ

ジェクト

- object(Phrase1)

Filter2


{フィールド

名}

フィールドごとの絞込み・除外キーワードを

格納するオブジェクト

{フィールド名}には絞込み・除外を行いた

いフィールド名を指定する。空文字列を指

定した場合、400 エラーが返却される。

以下の型のフィールドのみ絞込み・除外を

行うフィールドとして指定可能。

text 、 keyword 、 long 、 integer 、

short、byte、double、 float、date、

boolean 、 integer_range 、

float_range 、 long_range 、

double_range、date_range

- object(Filter3)



14 / 43

上記以外の型のフィールドを指定した場合

は、400 エラーが返却される。

絞込みキーワードと除外キーワードを同時

に指定した場合は絞込み条件で絞込んだ

結果から除外条件に該当する FAQ を除

外する。

Filter3


include 絞込みの条件とする値

検索対象のフィールドに対し、フィールドの型によって以

下のように絞り込む。

・フィールドの型が text の場合、include で指定した値

のいずれかをキーワードとして含む FAQ に絞り込む。

・フィールドの型が text 以外の場合、include で指定し

た値のいずれかと値が一致する FAQ に絞り込む。

フィールドの型に合わない値を指定した場合は 400 エラ

ーが返却される。最大リスト長は 500。上限値を超えた


例：[“include1”,“include2”]

- string[]

exclude 除外の条件とする値

検索対象のフィールドに対し、フィールドの型によって以

下のように除外する。

・フィールドの型が textの場合、exclude で指定した値

のいずれかをキーワードとして含む FAQ を除外する。

・フィールドの型が text 以外の場合、exclude で指定

した値のいずれかと値が一致する FAQ を除外する。

フィールドの型に合わない値を指定した場合は 400 エラ

ーが返却される。最大リスト長は 500。上限値を超えた


例：[“exclude1”,“exclude2”]

- string[]

Phrase1


include 絞込みの条件とするフレーズ

自然文を指定可能。

質問文による検索でヒットした FAQデ

- string



15 / 43

ータの内、検索対象フィールドに、指

定したフレーズを含む FAQ データのみ

に絞り込む※。検索対象フィールドは

Zinrai 導入支援サービスで決定され

る。

指定を省略した場合または値が空で

指定された場合はフレーズによる絞込

みを行わない。



返却される。

例: java.sql.SQLException: No

suitable driver

※絞り込みの際は多少の言葉のゆれ

は無視する

Options1


highlight ハイライト表示機能の設定を格納す

るオブジェクト

object(Highlight1)

max_size 返却する FAQ 最大数

最大値：100、最小値：1

最大値を超えて指定した場合は、最

大値が指定されたものとして扱われ

る。下限値を超えた場合は、400 エ

ラーが返却される。

例：50

100 number

Highlight1


enable ハイライトの有効/無効を表す真偽値

ハイライトが有効な場合、ハイライト対象の

フィールド内のキーワードがハイライトタグで

囲まれる。ハイライト対象のフィールドは

Zinrai 導入支援サービスで決定する。

true: ハイライトが有効

true boolean



16 / 43

false: ハイライトが無効

例: false

include_related_

terms

精度向上のため API によって自動的に追

加されたキーワード関連キーワードをハイラ

イトするか否かを表す真偽値

true: 自動的に追加されたキーワードハイ

ライトする

false: 自動的に追加されたキーワードハ

イライトしない

例: false

true boolean

3.1.2 レスポンス

ヘッダ

名前値補足

Content-Type application/json -


形式：JSON

名前説明型

hits 検索結果 object(Hits1)

search_id 質問 ID string

term 質問文中のキーワードのリスト

以下の条件をすべて満たす場合に本フィールドが返却さ

れる。

・ハイライトが有効である

・質問文の中にキーワードが存在する

例: [“単語 1” , “単語 2”]

string[]

related_term 精度向上のため API によって自動的に追加されたキーワ

ードのリスト

以下の条件をすべて満たす場合に本フィールドが返却さ

れる。

・ハイライトが有効である

・リクエスト時の include_related_terms の値が true

・API によって自動的に追加されたキーワードが存在する

例: [“関連キーワード 1” , “関連キーワード 2”]

string[]

Hits1



17 / 43

名前説明型

hits 検索結果のリスト

“_score”の値が大きい順に表示される。

object(Hits2)[]

total 検索でヒットした結果の合計数 number

Hits2

名前説明型

_id FAQ ID string

_score スコア

最大値：1、最小値：0

1 に近いほど、検索に対する正解の確度が高い。

例：0.78

number

_source FAQ の内容 object(Source)

highlight ハイライトされたフィールドの情報

ハイライトが有効な場合に返却される。ハイライト対象のフィ

ールド内のキーワードがハイライトタグで囲まれ返却される。

ハイライト対象のフィールドは Zinrai 導入支援サービスで決

定する。ハイライトタグで囲まれるのは、フィールド毎に最大

256 箇所までとなる。

質問文の中のキーワード、API によって自動的に追加され

たキーワードはそれぞれ下記のハイライトタグで囲まれる。

・質問文の中のキーワード : 

・API によって自動的に追加されたキーワード: 

また、フィールドの値に HTML 特殊文字が含まれる場合

は、値の中に含まれる HTML 特殊文字が HTML エンティ

ティにエスケープされる。

返却されるフィールドの値は長さ 1 の配列である。キーワード

を含むフィールドが存在しない場合、highlight フィールドは

返却されない。

例 : {"text01": " パソコン の

電源ボタン

を押しても、 電源

 ランプが …", "text02": "電源ボタンを押した

object(Highlight)



18 / 43

後、電源ラ

ンプが点灯しなかったり…"}

Source

名前説明型

{field_name} FAQ データのフィールド

返却するフィールドは Zinrai 導入支援サービスで決定する。

Highlight

名前説明型



エラー情報

{}で記載している情報は、エラー内容によって変わります。


400 Bad Request Request format is not JSON format.

400 Bad Request The browser (or proxy) sent a request that

this server could not understand.

400 Bad Request {element_name} is a required property

400 Bad Request Additional properties are not allowed

({element_name} was unexpected)

400 Bad Request {value} is not of type {type}

400 Bad Request {object_value} has too many properties

400 Bad Request {value} is too long

400 Bad Request {value} is less than the minimum of

{minimum_value}

400 Bad Request TransportError(400,

'search_phase_execution_exception',

'Binary fields do not support searching')


'search_phase_execution_exception', 'failed

to create query: {query}')


'illegal_argument_exception', 'field name

cannot be null.')

400 Bad Request The length of header field



19 / 43

'X-Forwarded-User' is over 255 characters.

400 Bad Request The value of header field 'X-Forwarded-User'

contains some invalid characters.

500 Internal Server Error Contact system administrator.

3.1.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/documents/_search' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00002' -H 'X-Forwarded-User: user' -H 'Content-Type: application/json' -X

POST -d ' {"query": {"text": "電源ボタンを押しても、起動しません"}, "filter"

: { "fields": { "text01": { "include":[], "exclude": [ "サーバ" ] }

} , "phrase": {"include": "ケーブルや電源コードが接続されているかを確認する"} }, "options": { "highlight": {"enable": true,"include_related_terms": true}, "max_size": 10} }'

レスポンス

{ "hits": { "hits": [ { "_id": "a1234-5678", "_score": 0.04829693404119895, "_source": { "label_id": "a1234-5678",

"text01": "パソコンの電源ボタンを押しても、電源ランプが…",

"text02": "電源ボタンを押した後、電源ランプが点灯しなかったり…" }, "highlight": { "text01": [

"パソ

コンの電源ボタンを

押しても、電源ランプが…", ],

"text02": [

"電源ボタンを押した後、<s

pan class=¥"highlight¥">電源ランプが点灯しなかったり …"

] } }, { "_id": "a2345-6789", "_score": 0.01860639535733455, "_source": {



20 / 43

"label_id": "a2345-6789",

"text01": " 電源を切ってもパソコンが勝手に起動したり…",

"text02": " パソコン本体やアプリケーションの設定によって…" }, "highlight": { "text01": [

"電源を切ってもパソコン

が勝手に起動したり…" ],

"text02": [

"パソ

コン本体やアプリケーションの設定によって…" ] }

},・・・ ], "total": 11766 }, "terms": [

"電源" ], "related_terms": [

"パソコン" ], "search_id": "1234_20170627100001_1"

}

3.2 詳細取得

FAQ データの詳細情報を取得します。

URI /FAQSearch/v1/documents/{id}{?highlight}{&terms}{&related

_terms}{&search_id}

HTTP メソッド GET


ヘッダ





21 / 43







返却される。



パラメータ

名前説明種別必須既定値

id FAQ ID path ○ -

highlight 事例取得結果に対するハイライトの有効/無

効を表す真偽値

true: ハイライトが有効

false: ハイライトが無効

大文字/小文字は区別する。上記以外の

値が指定された場合は、400 エラーが返却

される。

query true

terms ハイライトを行う質問文の中のキーワード

検索時のレスポンスに含まれた terms 内の

文字列を指定する。文字列が複数存在す

る場合は、本パラメータを複数指定する。

URI で使用できない文字はパーセントエンコ

ードする。

query

related_terms ハイライトを行う API で自動的に追加された

キーワード

検索時のレスポンスに含まれた

related_terms 内の文字列を指定する。

文字列が複数存在する場合は、本パラメー

タを複数指定する。URI で使用できない文

字はパーセントエンコードする。

string

search_id 質問 ID

検索 API のレスポンスに含まれる

search_idを指定する。本パラメータを指定

し、操作ログ取得 API でログを取得すること

string



22 / 43

で利用分析が可能になる。フォーマットは

[0-9]+_[0-9]+_[0-9]+。最大文字数

は 100 文字。フォーマットに沿わない質問

ID が設定された場合は、400 エラーが返却

される。フォーマットは正しいが存在しない

search_id が指定された場合は、エラーに

はならない。


なし


ヘッダ

名前値補足

Content-Type application/json


形式：JSON

名前説明型

_id FAQ ID string

_source FAQ の内容 object(Source)



23 / 43

highlight ハイライトされたフィールドの情報

ハイライトが有効な場合に返却される。ハイライト対象のフ

ィールド内のキーワードがハイライトタグで囲まれ返却され

る。ハイライト対象のフィールドは Zinrai 導入支援サービス

で決定する。ハイライトタグで囲まれるのは、フィールド毎に

最大 256 箇所までとなる。

質問文の中のキーワード、API によって自動的に追加され

たキーワードはそれぞれ下記のハイライトタグで囲まれる。

・質問文の中のキーワード : 

・API によって自動的に追加されたキーワード: 

また、フィールドの値に HTML 特殊文字が含まれる場合

は、値の中に含まれる HTML 特殊文字が HTML エンティ

ティにエスケープされる。

返却されるフィールドの値は長さ 1 の配列である。キーワー

ドを含むフィールドが存在しない場合、highlightフィールド

は返却されない。

例 : {"text01": " パソコン の

電源ボタン

を押しても、 電源

 ランプが …", "text02": "電源ボタンを押した

後、電源ラ

ンプが点灯しなかったり…"}

object(Highlight)

Source

名前説明型


FAQ データの全フィールドが返却される。

Highlight

名前説明型

{field_name} FAQ データのフィールド。




24 / 43

エラー情報


400 Bad Request The length of the specified ID is over 100

characters.


'X-Forwarded-User' is over 255 characters.

400 Bad Request The value of header field 'X-Forwarded-User'

contains some invalid characters.

400 Bad Request The query parameter has an invalid value.


400 Bad Request {value} does not match

{regular_expression}

404 Not Found The document corresponding to the specified

ID cannot be found.

414 Request-URI Too

Large

Request-URI Too Large


3.2.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/documents/a1234-5678?highlight=true&terms=%E9%9B%BB%E6%BA%90&related_terms=%E3%83%91%E3%82%BD%E3%82%B3%E3%83%B3&search_id=1234_20170627100001_1' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00106' -H 'X-Forwarded-User: user'

レスポンス

{ "_id": "a1234-5678", "_source": { "label_id": "a1234-5678",

"text01": "パソコンの電源ボタンを押しても、電源ランプが…",

"text02": "電源ボタンを押した後、電源ランプが点灯しなかったり…", "timestamp": null,

"item01": "メモリ",

"item02": "ハードウェア" }, "highlight": { "text01": [

"電源を切ってもパソコンが勝手に起動

したり…" ],

"text02": [

"パソコン本体やアプリケーションの設

定によって…" ] }

}

3.3 フィードバック

検索した結果のフィードバックを行います。

本 API は、定期学習の学習精度を向上させるため、検索結果として返却された FAQ が参考になったかどう

かを評価する API です。

URI /FAQSearch/v1/feedback



ヘッダ



Content-Type application/json ○ -







返却される。



パラメータ

なし




26 / 43

形式：JSON


document_id FAQ ID

最大文字数は 100 文字。上限値を超えた場

合は400 エラーが返却される。存在しない FAQ

ID を指定した場合はエラーにならない。

例：a1234-5678

○ - string

search_id 質問 ID

検索 API のレスポンスで返却された質問 ID を

指定する。検索APIで返却されていない値を指

定しても、エラーにはならない。

質問 ID のフォーマットに沿わない質問 ID を設

定した場合は、400 エラーが返却される。

例：1234_20170627100000_1

○ - string

key 評価結果。

以下を指定可能。以下以外を指定した場合

は、400 エラーが返却される。

・good: 参考になった

・bad: 参考にならなかった

例：good

○ - string


ヘッダ

名前値補足



形式：JSON

名前説明型

success API の実行結果

成功:true

失敗:false

例:true

boolean

エラー情報





27 / 43


400 Bad Request The browser (or proxy) sent a request

that this server could not understand.


400 Bad Request Additional properties are not allowed




400 Bad Request {value} is not one of {values}




'X-Forwarded-User' is over 255

characters.

400 Bad Request The value of header field

'X-Forwarded-User' contains some invalid

characters.


3.3.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/feedback' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00201' -H 'X-Forwarded-User: user' -H 'Content-Type: application/json' -X POST -d '{"document_id": "a1234-5678","search_id": "1234_20170627100001_1","key": "good"}'

レスポンス

{ "success": true

}

3.4 教師データ登録

教師データを登録します。

URI /FAQSearch/v1/admin/data/{type}



28 / 43



ヘッダ

名前値補足

X-Service-Code FJAI000011-00301 -

Content-Type text/csv -

パラメータ


type 登録するデータの種別

次の種別を指定可能。

・question-data:質問データ

・relation-data:紐づけデータ

上記以外の種別を指定した場合は

404 エラーが返却される。

path ○ -


形式：CSV

登録するデータを指定する。

一度に登録するデータのサイズ上限は 16MB とする。上限値を超えた場合は 413 エラーが返却され

る。また、登録する CSV データに含まれるレコード数の上限はおおよそ 16 万件とする。

上限値を超えた場合は動作保証外となる(504 エラーが返却される場合がある)。

登録済みの教師データのサイズと、登録する教師データのサイズの合計が 1GB を超える場合は


データ登録の例

登録済み教師データ登録する教師データ登録可否

合計 1014MB

・質問データ(900MB)

・紐づけデータ(114MB)

質問データ (10MB) ○

紐づけデータ(10MB) ○

質問データ (11MB) ×

紐づけデータ(11MB) ×

Zinrai 導入支援サービスで決定したデータ形式に違反している場合は、400 エラーが返却される。


登録するデータ登録するデータ ○ -



29 / 43


ヘッダ

名前値補足



形式：JSON

名前説明型

total_data_size 教師データ登録後の、すべての登録済み質問データと

紐づけデータの合計サイズ(Byte)

例：104857600

number

エラー情報



400 Bad Request ※{element_name} is a required property

※エラーが発生した行の行番号がメッセージの先頭に付与されます

400 Bad Request ※ Additional properties are not allowed



400 Bad Request ※{value} is too long


400 Bad Request ※{value} is too short


400 Bad Request ※{value} is not one of {values}


400 Bad Request ※ {value} does not match



400 Bad Request ※ {value} does not match any of the

regexes: {regular_expression}


400 Bad Request Request format is not CSV format.

400 Bad Request Request body is not specified.

400 Bad Request Request character encoding is not UTF-8.

400 Bad Request The number of columns of header part and

data part does not match.

400 Bad Request unexpected end of data

400 Bad Request ',' expected after '"'



30 / 43

400 Bad Request 'utf-8' codec can't decode byte {code} in

position {position}: {message}

404 Not Found The specified data type does not exist.

413 Request Entity Too

Large

The total size of active data and registered

data exceeds the upper limit.


504 Gateway Time-out Gateway Time-out

3.4.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/data/question-data' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00301' -H 'Content-Type: text/csv; charset=UTF-8' -X POST --data-binary @datafile.csv

レスポンス

{ "total_data_size": 104857600

}

3.5 教師データ削除

登録されている教師データを削除します。

URI /FAQSearch/v1/admin/data/{type}

HTTPメソッド DELETE


ヘッダ

名前値補足


パラメータ


type 削除するデータの種別

次の種別を指定可能。

path ○ -



31 / 43

・question-data: 質問データ

・relation-data: 紐づけデータ

指定した種別に該当するデータは全て削

除する。

上記の種別以外を指定した場合は、



なし


ヘッダ

名前値補足



形式：JSON

名前説明型

total_data_size 教師データ削除後の、すべての登録済み質問データと

紐づけデータの合計サイズ(Byte)

number

エラー情報


404 Not Found The specified data type does not exist.


3.5.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/data/question-data' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00302' -X DELETE

レスポンス

{ "total_data_size":104857600

}



32 / 43

3.6 FAQ データ登録/更新

1 件の FAQ 項目を登録/更新します。

指定した FAQ ID に該当する FAQ 項目が存在しない場合は、FAQ 項目を登録します。

指定した FAQ ID に該当する FAQ 項目が存在する場合は、該当する FAQ 項目を更新します。

FAQ の登録件数の上限は 10 万件です。上限値を超える場合は 400 エラーが返却されます。

URI /FAQSearch/v1/admin/documents/{id}

HTTPメソッド PUT


ヘッダ

名前値補足



パラメータ


id FAQ ID

最大文字数は 100 文字。最大文字数を超えて

いる場合は 400 エラーが返却される。半角スラッ

シュ(’/’)を除く UTF-8 でパーセントエンコード可能

な全ての文字を使用可能。ただし、先頭の文字に

半角アンダースコア(’_’)は指定できない。URI で

使用できない文字はパーセントエンコードすること。

path ○ -


形式：JSON

Zinrai 導入支援サービスで決定したデータ形式に違反している場合は、400 エラーが返却される。


{フィールド名} 登録するデータ ○ -


ヘッダ

名前値補足




33 / 43


形式：JSON

名前説明型

_id FAQ ID

登録/更新した FAQ 項目の ID

string

result 実行された操作種別を表す文字列。

登録:created

更新:updated

string

エラー情報




characters.


400 Bad Request The browser (or proxy) sent a request that

this server could not understand.



400 Bad Request {object_value} does not have enough

properties


400 Bad Request {value} is too short

400 Bad Request {value} is less than the minimum of

{minimum_value}

400 Bad Request {value} is not one of {values}




'strict_dynamic_mapping_exception',

'mapping set to strict, dynamic introduction

of {field_name} within {field_name} is not

allowed')


'mapper_parsing_exception', 'failed to

parse')



34 / 43


'mapper_parsing_exception', 'failed to

parse {type}')


'mapper_parsing_exception', 'object

mapping for {field_name} tried to parse

field {field_name} as object, but found a

concrete value')

400 Bad Request The specified ID has an invalid format.

400 Bad Request The number of registered documents

reaches the upper limit.


3.6.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/documents/a1234-5678' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-0

0401' -H 'Content-Type: application/json' -X PUT -d '{"text01":"アプ

リケーションがインストールできません。","text02":"お使いのパソコンのOSがインストールしようとし

ているアプリケーションに対応していない可能性があります。パソコンのOSを確認してください。","label_id":"a1234-5678"}'

レスポンス

{ "_id": "a1234-5678" "result": "created"

}

3.7 FAQ データ削除

指定した FAQ ID に該当する FAQ 項目を 1 件削除します。

URI /FAQSearch/v1/admin/documents/{id}

HTTPメソッド DELETE



35 / 43


ヘッダ

名前値補足


パラメータ


id FAQ ID

最大文字数は 100 文字。最大文字数を超えて

いる場合は 400 エラーが返却される。半角スラッ

シュ(’/’)を除く UTF-8 でパーセントエンコード可能

な全ての文字を使用可能。ただし、先頭の文字に

半角アンダースコア(’_’)は指定できない。URI で

使用できない文字はパーセントエンコードすること。

path ○ -


なし


ヘッダ

名前値補足



形式： JSON

名前説明型

_id FAQ ID

削除した FAQ 項目の ID。

string

result 実行された操作種別を表す文字列。

削除:deleted

string

エラー情報



characters.

400 Bad Request The specified ID has an invalid format.

404 Not Found The document corresponding to the



36 / 43

specified ID cannot be found.


3.7.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/documents/a1234-5678' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00402' -X DELETE

レスポンス

{ "_id":"a1234-5678" "result":"deleted"

}

3.8 日付リスト取得

操作ログのうち取得可能な日付のリストを、日付の昇順でソートして返却します。

取得可能な操作ログが無い場合は、空のリストを返却します。

リクエスト URI の末尾に「/」を付与した場合は 404 エラーを返却します。

URI /FAQSearch/v1/admin/operationlogs

HTTPメソッド GET


ヘッダ

名前値補足


パラメータ

なし


なし



37 / 43


ヘッダ

名前値補足



形式： JSON

名前説明型

date 操作ログを取得可能な YYYYMMDD 形式の日付 string

エラー情報



3.8.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/operationlogs' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00801'

レスポンス

[ {

"date":"20180620" }, {

"date":"20180621" }, {

"date":"20180622" }

]

3.9 操作ログ取得

1 日分※1 の操作ログを取得し、返却します。

本 API は、FAQ 検索がどのように利用されているかなどを分析するため、検索 API/詳細取得 API/フィード

バック API のログを取得する API です。

以下に該当する操作ログは取得できません。

・当日の操作ログ



38 / 43

・保存期間※2 を超過し、削除済みの操作ログ ※1 日付の切り替わりは UTC(協定世界時)での午前 0 時に行われます。 ※2 保存期間は Zinrai 導入支援サービスで決定されます。

URI /FAQSearch/v1/admin/operationlogs/{date}

HTTPメソッド GET


ヘッダ

名前値補足


パラメータ


date ログを取得したい日付を YYYYMMDD 形式で指

定する。操作ログを取得できない日付を指定した

場合は、404 エラーが返却される。不正な日付

(2 月 31 日等)、フォーマットに沿わない文字列を

指定した場合は、400 エラーが返却される。

path ○ -


なし


ヘッダ

名前値補足

Content-Type application/x-ndjson


操作ログは、1 回の操作につき 1 行の JSON 形式で情報を出力する。

操作単位の情報の間は改行で区切られ、各行はリクエスト処理日時の昇順でソートされる。

リクエスト処理日時は、操作ログに UTC(協定世界時)で出力される。

形式： NDJSON

フィールド名説明型

timestamp リクエスト処理日時

ISO 8601 形式でマイクロ秒まで、タイムゾ

ーン付きで出力する。

string



39 / 43

例:

2018-06-20T13:00:00.000000+00

:00

user_id ユーザーID

リクエストヘッダに X-Forwarded-User を

指定したリクエスト操作についてのみ出力す

る。

例: user

string

action 操作種別

・search: 検索 API

・get_document: 詳細取得 API

・feedback: フィードバック

例: search

string

operation_info 操作種別毎の固有情報

各 API のリクエスト操作に失敗した場合は

出力されない場合がある。

object(OperationInfo)

success リクエスト操作の成功/失敗

・成功: true

・失敗: false

例: true

boolean

OperationInfo

操作種別出力内容

検索 search_id: 検索 API のレスポンスで返却された search_id(詳細は検

索 API を参照。リクエスト操作に失敗した場合は出力されない。)

query: 検索 API のリクエストボディの内容(詳細は検索 API を参照。)

document_ids: 検索の結果、ヒットした FAQ ID 一覧(リクエスト操作

に失敗した場合は出力されない。)

例 : {“search_id”: “1234_20180620130000_1”, “query”:

{“query”: {“text”: “電源ボタンを押しても、パソコンが起動しませ

ん。”}}, “document_ids”: [“a1234-5678”, “a2345-6789”]}

詳細取得 search_id: 詳細取得 API のリクエストに指定された search_id(詳細

は詳細取得 API を参照。リクエストに search_id が指定された場合に出

力される。ただし、リクエスト操作に失敗した場合は出力されないことがあ

る。)

document_id: 詳細取得 API のリクエストに指定された id(詳細は詳

細取得 API を参照。)



40 / 43

例 : {“search_id”: “1234_20180620130000_1”,

“document_id”: “a1234-5678”}

フィードバック search_id: フィードバック API のリクエストに指定された search_id(詳

細はフィードバック API を参照。)

document_id: フィードバック API のリクエストに指定された id(詳細はフ

ィードバック API を参照。)

key: フィードバック API のリクエストに指定された key(詳細はフィードバッ

ク API を参照。)

例 : {“search_id”: “1234_20180620130000_1”,

“document_id”: “a1234-5678”, “key”: “good”}

エラー情報


400 Bad Request The specified date has an invalid format.

400 Bad Request The specified date is invalid.

404 Not Found There is no operation log for the specified

date.


3.9.3 実行例

リクエスト

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/FAQSearch/v1/admin/operationlogs/20180620' -H 'X-Access-Token: 000000000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00802'

レスポンス

{"timestamp": "2018-06-20T13:00:00.000000+00:00", "user_id": "user", "action": "search", "operation_info": {"search_id":

"1234_20180620130000_1", "query": {"query": {"text": "電源ボタンを押し

ても、パソコンが起動しません。 "}}, "document_ids": ["a1234-5678", "a2345-6789"]}, "success": true}

{"timestamp": "2018-06-20T13:03:14.000000+00:00", "user_id": "user", "action": "get_document", "operation_info": {"search_id": "1234_20180620130000_1", "document_id": "a1234-5678"}, "success": true}

{"timestamp": "2018-06-20T13:07:39.000000+00:00", "user_id": "user", "action": "feedback", "operation_info": {"search_id": "1234_20180620130000_1", "document_id": "a1234-5678", "key": "good"}, "success": true}



41 / 43

付録A パラメータ仕様

本書では、API 毎にパラメータを以下のように種別分けしています。

種別説明

path URI の中で、クエリ文字列以外（リソース名など）で指定する。

値のみで、パラメータ名は記述されない。

例：/Sample/v1/samp_file/0001

query URI の中で、クエリ文字列で指定する

例：/Sample/v1/samp_file/0001?param1=AAA

本 API におけるリクエスト／レスポンスボディの形式は、JSON を基本とします。JSON の場合、本書では、

型について、以下のように表記します。

型説明

string ダブルクォーテーションで括った文字列

number 数値

boolean 真偽値（true と false）

array ※[]表記配列

object※()内にオブジェクト名表記オブジェクト（キーと値の組の集まり）

本 API のレスポンスに非 ASCII 文字が含まれる場合は、全て¥uxxxx のユニコードエスケープシーケンス形

式で返却します。

※ただし本書のレスポンス例は、可読性向上のため、適宜デコード及び整形済みのものを記載しています。



42 / 43

付録B データ仕様

質問データおよび紐づけデータの仕様について説明します。

はじめに、各データの共通事項は以下です。

1) ヘッダが必要です。

ヘッダに使用する各カラムのカラム名は Zinrai 導入支援サービスで決定します。

2) カラムの順番は任意です。

3) 区切り文字は「,」とし、区切り文字の前後にスペースを入れた場合は、値の一部として扱われます。

値に改行や「,」が含まれる場合は「"」で囲んでください。「"」で囲んだ値に「"」を含む場合は「""」に置

き換えてください。

4) 文字コードは UTF-8 とし、改行コードは CRLF、LF、CR のいずれかとします。

質問データのカラムについて

必須内容文字種文字数備考

○ 質問 ID 「/」以外、かつ先頭は

「_」以外のパーセントエ

ンコーディング可能な文

字

100 文字以内質問を特定するための一意

な ID

○ 質問文任意 5000 文字以内質問文(自然文)のテキスト

データ作成日時 YYYY-MM-DDThh:

mm:ss±hh:mm の

形式

― ―

その他の付加情報任意各 10000 文字

以内

複数定義することが可能

紐づけデータのカラムについて

必須内容文字種文字数備考

○ 質問 ID 「/」以外、かつ先頭は

「_」以外のパーセントエ

ンコーディング可能な文

字

100 文字以内質問を特定するための一意

な ID

○ FAQ ID ID：「/」以外、かつ先

頭は「_」以外のパーセン

トエンコーディング可能な

文字

ID：100 文字

以内

区切り文字：1

文字

FAQ を特定するための一意

な ID

一つの質問に対して複数の

FAQ が紐づく場合、FAQ



43 / 43

区切り文字：「/」のみ ID は区切り文字を用いて

連結する。

連結できる ID の数は 99

個。

データ作成日時 YYYY-MM-DDThh:

mm:ss±hh:mm の

形式

― ―

Documents

FAQ 検索•™師データ登録API、教師デー タ削除API、FAQデータ登録/更 新API、FAQデータ削除APIに 関する記述を追記 ... 408 Request Timeout リクエストタイムアウトが発生しました。

FAQ 検索•™師データ登録API、教師データ削除API、FAQデータ登録/更新API、FAQデータ削除APIに関する記述を追記 ... 408 Request Timeout リクエストタイムアウトが発生しました。