変更履歴版数修正日修正箇所修正内容 /7/27 初版 /10/ 教師データ登録 API 教師データ削除 API FAQ データ登録 / 更新 API FAQ データ削除 API に関する記述を追記付録 B

(1)

FAQ 検索

API リファレンス

第 1.7 版

2018 年 8 月 2 日富士通株式会社

(2)

変更履歴

版数 修正日 修正箇所 修正内容 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)

(4)

はじめに

本書の目的 本書は、Zinrai プラットフォームサービスが提供する API について説明しています。 本書の対象読者 本書は、Zinrai プラットフォームサービスでアプリケーションやサービスを開発・運用する方を対象に記述します。本書を読むためには、以下の知識が必要です。・インターネットに関する基本的な知識・使用するオペレーティングシステムに関する基本的な知識・WebAPI に関する基本的な知識 お願い ・本書で使用している画面イメージ、実行例などは、最新環境のものとは異なることがあります。・本書は、予告なしに変更されることがあります。・本書を無断で他に転用しないようお願いします。・本書に記載されたデータの使用に起因する第三者の特許権およびその他の権利の侵害については、当社はその責を負いません。 輸出管理規制について 本ドキュメントを輸出または第三者へ提供する場合は、お客様が居住する国および米国輸出管理関連法 規等の規制をご確認のうえ、必要な手続きをおとりください。 登録商標について 本書に記載されている会社名および製品名は、それぞれ各社の商標または登録商標である場合があります。なお、本書では、会社名および製品名に付記される登録表示((TM)または(R))は省略しています。

(5)

第 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 レスポンス ... 28 3.4.3 実行例 ... 30 3.5 教師データ削除 ... 30 3.5.1 リクエスト ... 30 3.5.2 レスポンス ... 31 3.5.3 実行例 ... 31 3.6 FAQ データ登録/更新 ... 31

(6)

3.6.1 リクエスト ... 32 3.6.2 レスポンス ... 32 3.6.3 実行例 ... 34 3.7 FAQ データ削除 ... 34 3.7.1 リクエスト ... 34 3.7.2 レスポンス ... 35 3.7.3 実行例 ... 36 3.8 日付リスト取得 ... 36 3.8.1 リクエスト ... 36 3.8.2 レスポンス ... 36 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)

第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

(8)

第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 詳細」のリクエストヘッダ仕様をご参照ください。

(9)

2.5 HTTP ステータスコード

ステータスコード 意味説明 200 OK リクエストは正常に処理されました。 201 Created リクエストは正常に処理され、新規リソースが作成されました。 202 Accepted リクエストを正常に受け付けました。 ※主に非同期処理へのメッセージ 400 Bad Request リクエストの内容に誤りがあります。 401 Unauthorized 認証に失敗しました。 404 Not Found リソースが見つかりませんでした。 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)

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

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

400 Bad Request You have requested incorrect parameters. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。・リクエストに X-Access-Token ヘッダが無い・X-Access-Token ヘッダの値が正しくない・リクエストに X-Service-Code ヘッダが無い・X-Service-Code ヘッダの値のフォーマットが正しくない コード タイトル メッセージ

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

上記のエラーが返却された場合、以下を確認してください。・X-Access-Token ヘッダの値が正しくない

404 Not Found We could not find the resource you requested. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。・X-Service-Code ヘッダの値が正しくない・HTTP メソッドまたは URL が誤っている コード タイトル メッセージ 500 Internal Server Error

The server encountered an internal error. (XXXXXXXX) 上記のエラーが返却された場合、以下を確認してください。

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

(11)

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)

第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)

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

(14)

上記以外の型のフィールドを指定した場合は、400 エラーが返却される。絞込みキーワードと除外キーワードを同時に指定した場合は絞込み条件で絞込んだ結果から除外条件に該当する FAQ を除外する。 Filter3 名前説明 必須既定値 型 include 絞込みの条件とする値検索対象のフィールドに対し、フィールドの型によって以下のように絞り込む。・フィールドの型が text の場合、include で指定した値のいずれかをキーワードとして含む FAQ に絞り込む。・フィールドの型が text 以外の場合、include で指定した値のいずれかと値が一致する FAQ に絞り込む。フィールドの型に合わない値を指定した場合は 400 エラーが返却される。最大リスト長は 500。上限値を超えた場合は 400 エラーが返却される。例：[“include1”,“include2”] - string[] exclude 除外の条件とする値検索対象のフィールドに対し、フィールドの型によって以下のように除外する。・フィールドの型が text の場合、exclude で指定した値のいずれかをキーワードとして含む FAQ を除外する。・フィールドの型が text 以外の場合、exclude で指定した値のいずれかと値が一致する FAQ を除外する。フィールドの型に合わない値を指定した場合は 400 エラーが返却される。最大リスト長は 500。上限値を超えた場合は 400 エラーが返却される。例：[“exclude1”,“exclude2”] - string[] Phrase1 名前説明必須 既定値 型 include 絞込みの条件とするフレーズ自然文を指定可能。質問文による検索でヒットした FAQ デ - string

(15)

ータの内、検索対象フィールドに、指定したフレーズを含む FAQ データのみに絞り込む※_{。検索対象フィールドは} Zinrai 導入支援サービスで決定される。指定を省略した場合または値が空で指定された場合はフレーズによる絞込みを行わない。最大文字数は 500 文字。上限値を超えた場合は 400 エラーが返却される。例: 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)

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)

名前説明型 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": "電源ボタンを押した

(18)

後、電源ランプが点灯しなかったり…"} Source 名前説明型 {field_name} FAQ データのフィールド返却するフィールドは Zinrai 導入支援サービスで決定する。 Highlight 名前説明型 {field_name} FAQ データのフィールド返却するフィールドは Zinrai 導入支援サービスで決定する。  エラー情報 {}で記載している情報は、エラー内容によって変わります。 コード タイトル メッセージ

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') 400 Bad Request TransportError(400,

'search_phase_execution_exception', 'failed to create query: {query}')

'illegal_argument_exception', 'field name cannot be null.')

(19)

'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: 0000000000000 00000001FJAI000000aaaa1' -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_term s": 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,

(20)

"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 3.2.1 リクエスト  ヘッダ 名前値必須補足 X-Service-Code FJAI000011-00106 ○ -

(21)

X-Forwarded-User {任意の文字列} 学習で利用されるデータに対する付加情報。例えば利用者を特定可能なアカウント情報を指定することで、学習精度の向上につなげることが可能。最大文字数は 255 文字。上限値を超えた場合は 400 エラーが返却される。 HTTP/1.1 の HTTP ヘッダ仕様で定められたすべての文字を使用可能。  パラメータ 名前説明種別 必須既定値 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)

で利用分析が可能になる。フォーマットは [0-9]+_[0-9]+_[0-9]+。最大文字数は 100 文字。フォーマットに沿わない質問 ID が設定された場合は、400 エラーが返却される。フォーマットは正しいが存在しない search_id が指定された場合は、エラーにはならない。  メッセージボディ なし 3.2.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json  メッセージボディ  形式：JSON 名前説明型

_id FAQ ID string

(23)

highlight ハイライトされたフィールドの情報ハイライトが有効な場合に返却される。ハイライト対象のフィールド内のキーワードがハイライトタグで囲まれ返却される。ハイライト対象のフィールドは Zinrai 導入支援サービスで決定する。ハイライトタグで囲まれるのは、フィールド毎に最大 256 箇所までとなる。質問文の中のキーワード、API によって自動的に追加されたキーワードはそれぞれ下記のハイライトタグで囲まれる。・質問文の中のキーワード : ・API によって自動的に追加されたキーワード: また、フィールドの値に HTML 特殊文字が含まれる場合は、値の中に含まれる HTML 特殊文字が HTML エンティティにエスケープされる。返却されるフィールドの値は長さ 1 の配列である。キーワードを含むフィールドが存在しない場合、highlight フィールドは返却されない。

例 : {"text01": " パソコン の 電源ボタンを押しても、 電源 ランプが …", "text02": "電源ボタンを押した後、電源ランプが点灯しなかったり…"} object(Highlight) Source 名前説明型 {field_name} FAQ データのフィールド FAQ データの全フィールドが返却される。 Highlight 名前説明型 {field_name} FAQ データのフィールド。返却するフィールドは Zinrai 導入支援サービスで決定する。

(24)

 エラー情報

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

400 Bad Request The length of header field '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} is too long

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

500 Internal Server Error Contact system administrator.

3.2.3 実行例  リクエスト curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/F AQSearch/v1/documents/a1234-5678?highlight=true&terms=%E9%9B%BB%E 6%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: 000000000000000000 001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-00106' -H 'X-Fo rwarded-User: user'  レスポンス { "_id": "a1234-5678", "_source": { "label_id": "a1234-5678", "text01": "パソコンの電源ボタンを押しても、電源ランプが…", "text02": "電源ボタンを押した後、電源ランプが点灯しなかったり…", "timestamp": null, "item01": "メモリ", "item02": "ハードウェア" }, "highlight": { "text01": [

(25)

"highlight highlight_relatedTerm ¥">パソコンが勝手に起動したり…" ], "text02": [ "パソコン本体やアプリケーションの設定によって…" ] } }

3.3 フィードバック

検索した結果のフィードバックを行います。本 API は、定期学習の学習精度を向上させるため、検索結果として返却された FAQ が参考になったかどうかを評価する API です。 URI /FAQSearch/v1/feedback HTTP メソッド POST 3.3.1 リクエスト  ヘッダ 名前値必須補足 X-Service-Code FJAI000011-00201 ○ - Content-Type application/json ○ - X-Forwarded-User {任意の文字列} 学習で利用されるデータに対する付加情報。例えば利用者を特定可能なアカウント情報を指定することで、学習精度の向上につなげることが可能。最大文字数は 255 文字。上限値を超えた場合は 400 エラーが返却される。 HTTP/1.1 の HTTP ヘッダ仕様で定められたすべての文字を使用可能。  パラメータ なし  メッセージボディ

(26)

 形式：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 3.3.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json -  メッセージボディ  形式：JSON 名前説明型 success API の実行結果成功:true 失敗:false 例:true boolean  エラー情報 {}で記載している情報は、エラー内容によって変わります。 コード タイトル メッセージ

(27)

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 {value} is too long

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

400 Bad Request The length of header field '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/F AQSearch/v1/feedback' -H 'X-Access-Token: 000000000000000000001FJ AI000000aaaa1' -H 'X-Service-Code: FJAI000011-00201' -H 'X-Forward ed-User: user' -H 'Content-Type: application/json' -X POST -d '{"d ocument_id": "a1234-5678","search_id": "1234_20170627100001_1","k ey": "good"}'  レスポンス { "success": true }

3.4 教師データ登録

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

(28)

HTTP メソッド POST 3.4.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00301 - Content-Type text/csv -  パラメータ 名前説明種別必須 既定値 type 登録するデータの種別次の種別を指定可能。・question-data:質問データ・relation-data:紐づけデータ上記以外の種別を指定した場合は 404 エラーが返却される。 path ○ -  メッセージボディ  形式：CSV 登録するデータを指定する。一度に登録するデータのサイズ上限は 16MB とする。上限値を超えた場合は 413 エラーが返却される。登録済みの教師データのサイズと、登録する教師データのサイズの合計が 1GB を超える場合は 413 エラーが返却される。データ登録の例 登録済み教師データ 登録する教師データ 登録可否 合計 1014MB ・質問データ(900MB) ・紐づけデータ(114MB) 質問データ (10MB) ○ 紐づけデータ(10MB) ○ 質問データ (11MB) × 紐づけデータ(11MB) × Zinrai 導入支援サービスで決定したデータ形式に違反している場合は、400 エラーが返却される。名前説明必須 既定値 型登録するデータ登録するデータ ○ - 3.4.2 レスポンス  ヘッダ

(29)

名前値補足 Content-Type application/json  メッセージボディ  形式：JSON 名前説明型 total_data_size 教師データ登録後の、すべての登録済み質問データと紐づけデータの合計サイズ(Byte) 例：104857600 number  エラー情報 {}で記載している情報は、エラー内容によって変わります。 コード タイトル メッセージ

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 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 {regular_expression}

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 '"'

404 Not Found The specified data type does not exist. 413 Request Entity Too The total size of active data and registered

(30)

Large data exceeds the upper limit. 500 Internal Server Error Contact system administrator.

3.4.3 実行例

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/F AQSearch/v1/admin/data/question-data' -H 'X-Access-Token: 0000000 00000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-003 01' -H 'Content-Type: text/csv; charset=UTF-8' -X POST --data-bina ry @datafile.csv  レスポンス { "total_data_size": 104857600 }

3.5 教師データ削除

登録されている教師データを削除します。 URI /FAQSearch/v1/admin/data/{type} HTTP メソッド DELETE 3.5.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00302 -  パラメータ 名前説明種別必須 既定値 type 削除するデータの種別次の種別を指定可能。・question-data: 質問データ・relation-data: 紐づけデータ指定した種別に該当するデータは全て削除する。上記の種別以外を指定した場合は、 path ○ -

(31)

404 エラーが返却される。  メッセージボディ なし 3.5.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json  メッセージボディ  形式：JSON 名前説明型 total_data_size 教師データ削除後の、すべての登録済み質問データと紐づけデータの合計サイズ(Byte) number  エラー情報 コード タイトル メッセージ

404 Not Found The specified data type does not exist. 500 Internal Server Error Contact system administrator.

3.5.3 実行例

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/F AQSearch/v1/admin/data/question-data' -H 'X-Access-Token: 0000000 00000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-003 02' -X DELETE  レスポンス { "total_data_size":104857600 }

3.6 FAQ データ登録/更新

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

(32)

指定した FAQ ID に該当する FAQ 項目が存在する場合は、該当する FAQ 項目を更新します。 FAQ の登録件数の上限は 10 万件です。上限値を超える場合は 400 エラーが返却されます。 URI /FAQSearch/v1/admin/documents/{id} HTTP メソッド PUT 3.6.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00401 - Content-Type application/json -  パラメータ 名前説明種別必須 既定値 id FAQ ID 最大文字数は 100 文字。最大文字数を超えている場合は 400 エラーが返却される。半角スラッシュ(’/’)を除く UTF-8 でパーセントエンコード可能な全ての文字を使用可能。ただし、先頭の文字に半角アンダースコア(’_’)は指定できない。URI で使用できない文字はパーセントエンコードすること。 path ○ -  メッセージボディ  形式：JSON Zinrai 導入支援サービスで決定したデータ形式に違反している場合は、400 エラーが返却される。名前説明必須 既定値 型 {フィールド名} 登録するデータ ○ - 3.6.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json  メッセージボディ  形式：JSON 名前説明型

(33)

_id FAQ ID 登録/更新した FAQ 項目の ID string result 実行された操作種別を表す文字列。登録:created 更新:updated string  エラー情報 {}で記載している情報は、エラー内容によって変わります。 コード タイトル メッセージ

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 {value} is not of type {type}

400 Bad Request {object_value} does not have enough properties

400 Bad Request {value} is too long 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')

'mapper_parsing_exception', 'failed to parse {type}')

(34)

'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. 500 Internal Server Error Contact system administrator.

3.6.3 実行例

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/F AQSearch/v1/admin/documents/a1234-5678' -H 'X-Access-Token: 00000 0000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-0 0401' -H 'Content-Type: application/json' -X PUT -d '{"text01":"アプリケーションがインストールできません。","text02":"お使いのパソコンのOSがインストールしようとしているアプリケーションに対応していない可能性があります。パソコンのOSを確認してください。","lab el_id":"a1234-5678"}'  レスポンス { "_id": "a1234-5678" "result": "created" }

3.7 FAQ データ削除

指定した FAQ ID に該当する FAQ 項目を 1 件削除します。 URI /FAQSearch/v1/admin/documents/{id} HTTP メソッド DELETE 3.7.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00402 -

(35)

 パラメータ 名前説明種別必須 既定値 id FAQ ID 最大文字数は 100 文字。最大文字数を超えている場合は 400 エラーが返却される。半角スラッシュ(’/’)を除く UTF-8 でパーセントエンコード可能な全ての文字を使用可能。ただし、先頭の文字に半角アンダースコア(’_’)は指定できない。URI で使用できない文字はパーセントエンコードすること。 path ○ -  メッセージボディ なし 3.7.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json  メッセージボディ  形式： JSON 名前説明型 _id FAQ ID 削除した FAQ 項目の ID。 string result 実行された操作種別を表す文字列。削除:deleted string  エラー情報 コード タイトル メッセージ

400 Bad Request The specified ID has an invalid format. 404 Not Found The document corresponding to the

specified ID cannot be found. 500 Internal Server Error Contact system administrator.

(36)

3.7.3 実行例

curl 'https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/F AQSearch/v1/admin/documents/a1234-5678' -H 'X-Access-Token: 00000 0000000000000001FJAI000000aaaa1' -H 'X-Service-Code: FJAI000011-0 0402' -X DELETE  レスポンス { "_id":"a1234-5678" "result":"deleted" }

3.8 日付リスト取得

操作ログのうち取得可能な日付のリストを、日付の昇順でソートして返却します。取得可能な操作ログが無い場合は、空のリストを返却します。リクエスト URI の末尾に「/」を付与した場合は 404 エラーを返却します。 URI /FAQSearch/v1/admin/operationlogs HTTP メソッド GET 3.8.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00801 -  パラメータ なし  メッセージボディ なし 3.8.2 レスポンス  ヘッダ 名前値補足 Content-Type application/json

(37)

 メッセージボディ  形式： JSON

名前説明型

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

3.8.3 実行例

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

 レスポンス [ { "date":"20180620" }, { "date":"20180621" }, { "date":"20180622" } ]

3.9 操作ログ取得

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

本 API は、FAQ 検索がどのように利用されているかなどを分析するため、検索 API/詳細取得 API/フィードバック API のログを取得する API です。以下に該当する操作ログは取得できません。・当日の操作ログ・保存期間※2_{を超過し、削除済みの操作ログ} ※1_{日付の切り替わりは UTC(協定世界時)での午前 0 時に行われます。} ※2_{保存期間は Zinrai 導入支援サービスで決定されます。}

(38)

URI /FAQSearch/v1/admin/operationlogs/{date} HTTP メソッド GET 3.9.1 リクエスト  ヘッダ 名前値補足 X-Service-Code FJAI000011-00802 -  パラメータ 名前説明種別必須 既定値 date ログを取得したい日付を YYYYMMDD 形式で指定する。操作ログを取得できない日付を指定した場合は、404 エラーが返却される。不正な日付 (2 月 31 日等)、フォーマットに沿わない文字列を指定した場合は、400 エラーが返却される。 path ○ -  メッセージボディ なし 3.9.2 レスポンス  ヘッダ 名前値補足 Content-Type application/x-ndjson  メッセージボディ 操作ログは、1 回の操作につき 1 行の JSON 形式で情報を出力する。操作単位の情報の間は改行で区切られ、各行はリクエスト処理日時の昇順でソートされる。リクエスト処理日時は、操作ログに UTC(協定世界時)で出力される。  形式： NDJSON フィールド名 説明型 timestamp リクエスト処理日時 ISO 8601 形式でマイクロ秒まで、タイムゾーン付きで出力する。例: 2018-06-20T13:00:00.000000+00 :00 string

(39)

リクエストヘッダに X-Forwarded-User を指定したリクエスト操作についてのみ出力する。例: user 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 を参照。)

例 : {“search_id”: “1234_20180620130000_1”, “document_id”: “a1234-5678”}

フィードバック search_id: フィードバック API のリクエストに指定された search_id(詳細はフィードバック APIを参照。)

(40)

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/F AQSearch/v1/admin/operationlogs/20180620' -H 'X-Access-Token: 000 000000000000000001FJAI000000aaaa1' -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)

付録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 ※[]表記配列

(42)

付録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)

区切り文字：「/」のみ ID は区切り文字を用いて連結する。連結できる ID の数は 99 個。データ作成日時 YYYY-MM-DDThh: mm:ss±hh:mm の形式 ― ―

変更履歴 版数 修正日 修正箇所 修正内容 /7/27 初版 /10/ 教師データ登録 API 教師データ削除 API FAQ データ登録 / 更新 API FAQ データ削除 API に関する記述を追記 付録 B