API リファレンス‚¹トレージのAPI リフアレンスのURL を追加 1.3 2018/4/26 2.2 暗号化プロトコルのサポートについて記載 3/64 ... 408 Request

1/64

1 / 64

自然文解析

API リファレンス

第 1.5 版

2019 年 6 月 26 日

富士通株式会社

2/64

2 / 64

変更履歴

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

1.0 2017/10/19 初版

1.1 2017/12/4 4.6.3 リクエストの実行例について誤植を修

正

namde10 → named10

1.2 2018/2/15 1.2

5.6

5.7

付録 D

以下の API を追加

解析（ファイル入出力）

解析状態取得

5.1

5.2

学習データのフォーマットチェックメッセー

ジを追加

4.1

4.2

4.3

5.1

5.2

5.3

学習時のメッセージボディにコメントを追

加

学習状態取得のレスポンスにコメントを

追加

5.4 パラメータにスコアの閾値を追加

2.7

付録 B

ストレージの API リフアレンスの URL を

追加

1.3 2018/4/26 2.2 暗号化プロトコルのサポートについて記

載

3/64

3 / 64

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

1.4 2018/8/7 2.5

2.6.1

3.1.2

4.1.2

4.2.2

4.3.2

4.4.2

4.5.2

4.6.2

4.7.2

5.1.2

5.2.2

5.3.2

5.4.2

5.5.2

5.6.2

5.7.2

5.8.2

ステータスコードの追記

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

1.5 2019/6/26 Copyright 表記

2.5

2.6.1

2018 から 2019 に変更

ステータスコードの追記

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

4/64

4 / 64

はじめに

本書の目的

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

本書の対象読者

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

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

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

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

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

お願い

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

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

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

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

はその責を負いません。

輸出管理規制について

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

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

登録商標について

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

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

自然文解析 API リファレンス

All Rights Reserved, Copyright©FUJITSU LIMITED 2017-2019

5 / 64

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

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

1.2 API 一覧 ................................................................................................... 8

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

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

2.2 プロトコル .................................................................................................. 10

2.3 文字コード ................................................................................................ 10

2.4 HTTP ヘッダ .............................................................................................. 10

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

2.6 エラー形式 ................................................................................................ 12

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

2.7 ファイルの登録 ............................................................................................ 14

2.8 ファイル（パス形式）の選択 ............................................................................ 14

2.9 モデル ID の付与 ........................................................................................ 14

2.10 注意事項 ............................................................................................... 14

第 3 章 API 詳細（地名・座標推定） ....................................................................... 15

3.1 解析 ...................................................................................................... 15

3.1.1 リクエスト ............................................................................................ 15

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

3.1.3 実行例 .............................................................................................. 17

第 4 章 API 詳細（固有名抽出） ........................................................................... 18

4.1 学習（カスタムルール作成） ........................................................................... 18

4.1.1 リクエスト ............................................................................................ 18

4.1.2 レスポンス ........................................................................................... 20

4.1.3 実行例 .............................................................................................. 21

4.2 学習（カスタムルール更新） ........................................................................... 22

4.2.1 リクエスト ............................................................................................ 22

4.2.2 レスポンス ........................................................................................... 23

4.2.3 実行例 .............................................................................................. 24

4.3 学習（標準ルールからカスタムルール作成） .......................................................... 25

4.3.1 リクエスト ............................................................................................ 25

4.3.2 レスポンス ........................................................................................... 26

4.3.3 実行例 .............................................................................................. 27

4.4 学習状態取得 ........................................................................................... 28

4.4.1 リクエスト ............................................................................................ 28



6 / 64

4.4.2 レスポンス ........................................................................................... 29

4.4.3 実行例 .............................................................................................. 30

4.5 解析（カスタムルール） ................................................................................. 31

4.5.1 リクエスト ............................................................................................ 31

4.5.2 レスポンス ........................................................................................... 32

4.5.3 実行例 .............................................................................................. 32

4.6 解析（標準ルール） .................................................................................... 33

4.6.1 リクエスト ............................................................................................ 33

4.6.2 レスポンス ........................................................................................... 34

4.6.3 実行例 .............................................................................................. 34

4.7 ルール削除 ............................................................................................... 35

4.7.1 リクエスト ............................................................................................ 35

4.7.2 レスポンス ........................................................................................... 35

4.7.3 実行例 .............................................................................................. 36

第 5 章 API 詳細（文章分類） .............................................................................. 37

5.1 学習（カスタムルール作成） ........................................................................... 37

5.1.1 リクエスト ............................................................................................ 37

5.1.2 レスポンス ........................................................................................... 38

5.1.3 実行例 .............................................................................................. 39

5.2 学習（カスタムルール更新） ........................................................................... 40

5.2.1 リクエスト ............................................................................................ 40

5.2.2 レスポンス ........................................................................................... 41

5.2.3 実行例 .............................................................................................. 42

5.3 学習状態取得 ........................................................................................... 43

5.3.1 リクエスト ............................................................................................ 43

5.3.2 レスポンス ........................................................................................... 44

5.3.3 実行例 .............................................................................................. 45

5.4 ルール精度評価 .......................................................................................... 46

5.4.1 リクエスト ............................................................................................ 46

5.4.2 レスポンス ........................................................................................... 47

5.4.3 実行例 .............................................................................................. 48

5.5 解析 ...................................................................................................... 49

5.5.1 リクエスト ............................................................................................ 49

5.5.2 レスポンス ........................................................................................... 50

5.5.3 実行例 .............................................................................................. 51

5.6 解析（ファイル入出力） ................................................................................ 52

5.6.1 リクエスト ............................................................................................ 52

5.6.2 レスポンス ........................................................................................... 53



7 / 64

5.6.3 実行例 .............................................................................................. 54

5.7 解析状態取得 ........................................................................................... 55

5.7.1 リクエスト ............................................................................................ 55

5.7.2 レスポンス ........................................................................................... 56

5.7.3 実行例 .............................................................................................. 57

5.8 ルール削除 ............................................................................................... 58

5.8.1 リクエスト ............................................................................................ 58

5.8.2 レスポンス ........................................................................................... 58

5.8.3 実行例 .............................................................................................. 59

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

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

B.1 固有名抽出学習データ ................................................................................ 61

B.2 固有名抽出単語辞書 ................................................................................. 61

B.3 固有名抽出単語列辞書 .............................................................................. 61

B.4 固有名辞書ユーザー辞書 ............................................................................. 62

B.5 文章分類学習データ ................................................................................... 62

B.6 文章分類辞書 ......................................................................................... 62

B.7 文章分類テストデータ .................................................................................. 62

付録 C 標準ルール .............................................................................................. 63

付録 D ステータス一覧 .......................................................................................... 64



8 / 64

第1章 API概要

自然文解析APIは、日本語で記載されたテキストの文章情報から、地名・座標推定、固有名抽出、文章

分類を行うための機能を提供します。

1.1 基本利用方法

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

1. 地名・座標推定

入力したテキストの文章情報から、地名辞書と推定ルールを用いて地名・住所・座標（経度・緯

度）を推定することができます。

2. 固有名抽出

入力文章から、固有名の抽出とタグ付けを行うことができます。

3. 文章分類

分類したいトピックに合致した文章に対し、ラベルと確度を付与することができます。

1.2 API一覧

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

機能概要 URI メソッド参照

地名・座

標推定

解析 /NaturalLanguageProcessing/v1/location/

actions/analyze

POST 3.1

固有名抽

出

学習（カスタム

ルール作成）

/NaturalLanguageProcessing/v1/annotatio

n/models

POST 4.1


ルール更新）


n/models/{model_id}/actions/update

POST 4.2

学習（標準ル

ールからカスタ

ムルール作

成）


n/hostedModels/{hosted_model_name}/a

ctions/update

POST 4.3

学習状態取得 /NaturalLanguageProcessing/v1/annotatio

n/models/{model_id}/actions/check

GET 4.4

解析（カスタム

ルール）


n/models/{model_id}/actions/analyze

POST 4.5

解析（標準ル

ール）


n/hostedModels/{hosted_model_name}/a

ctions/analyze

POST 4.6

ルール削除 /NaturalLanguageProcessing/v1/annotatio

n/models/{model_id}

DELETE 4.7



9 / 64

機能概要 URI メソッド参照

文章分類学習（カスタム

ルール作成）

/NaturalLanguageProcessing/v1/classificat

ion/models

POST 5.1


ルール更新）


ion/models/{model_id}/actions/update

POST 5.2

学習状態取得 /NaturalLanguageProcessing/v1/classificat

ion/models/{model_id}/actions/check

GET 5.3

ルール精度評

価


ion/models/{model_id}/actions/evaluate

POST 5.4

解析 /NaturalLanguageProcessing/v1/classificat

ion/models/{model_id}/actions/analyze

POST 5.5

解析（ファイル

入出力）


ion/models/{model_id}/actions/file_analy

ze

POST 5.6

解析状態取得 /NaturalLanguageProcessing/v1/classificat

ion/analysis/{analysis_id}/actions/check

GET 5.7

ルール削除 /NaturalLanguageProcessing/v1/classificat

ion/models/{model_id}

DELETE 5.8



10 / 64

第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 桁]”

例: FJAI000012-00006

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



11 / 64

2.5 HTTP ステータスコード

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

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

201 Created 作成完了しました。

202 Accepted 処理受付しました。

204 No Content 処理受付しました。返すべきレスポンスエンティティは

ありません。

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

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

403 Forbidden リソースにアクセスして拒否されました。

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

405 Method Not

Allowed

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

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

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

409 Conflict リソースへのアクセスが競合しています。

415 Unsupported

Media Type

リクエストヘッダのContent-Typeがサポート対象外

です。

500 Internal Server

Error

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

503 Service

Unavailable

・サービスを一時的に利用できません。

・予期しないエラーが発生しました。



12 / 64

2.6 エラー形式

以下の２つの JSON 形式のエラー情報を返します。

※ただし、一部のエラーコードは HTML 形式で返却されます。

名前説明

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

code エラーコード

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

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

※レスポンス例

JSON 形式

{

"error": {

"code": 404,

"title": "Not Found",

"message": "We could not find the resource you requested. (GWI14023)"

}

}



13 / 64

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. (XXXXXXXX)


・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.





14 / 64

2.7 ファイルの登録

各 API で用いる学習データや各種辞書データをサーバに登録（アップロード）する場合、自然文解

析のサービスコード（FJAI000012）フォルダの配下に、ファイルを格納する必要があります。

学習データや各種辞書データは、ストレージサービス API のファイル登録 APIを用いてアップロードする

ことが可能です。

ストレージサービス API については以下のリファレンスを参照してください。

https://k5-doc.jp-east-1.paas.cloud.global.fujitsu.com/doc/jp/zinrai-pf/docum

ent/reference/reference_storage.pdf

2.8 ファイル（パス形式）の選択

ストレージサービス API によって登録した学習データや各種辞書データを、以下のように指定します。

例）fs://FJAI000012/xxxxxx/xxxxxx/training_data

（補足）

・ fs://FJAI000012 から始まり、ファイル名までのパスを指定します。

・ FJAI000012 配下であれば、ディレクトリの階層やファイル名は任意です。

2.9 モデル IDの付与

モデル ID は学習の度にシステムが自動作成して付与されます。

・使用文字列：半角英大文字、半角英小文字、数字

・桁数：8 桁

例：iYoUy9Ms

2.10 注意事項

自然文解析の学習処理は非同期処理であり、API 実行での正常レスポンスは学習処理の開始を

意味します。学習処理の状態を把握するには、学習状態取得 API を実行する必要があります。

https://k5-doc.jp-east-1.paas.cloud.global.fujitsu.com/doc/jp/zinrai-pf/document/reference/reference_storage.pdf




15 / 64

第3章 API詳細（地名・座標推定）

本章では、地名・座標推定について、各 API の詳細仕様を説明します。パラメータの表記については、「付

録 Aパラメータ仕様」をご参照ください。

3.1 解析

自然文を受け取り、文中の地名を判別し、推定される住所とその座標を返却します。推定結果は確度の

高い順に出力されます。

URI /NaturalLanguageProcessing/v1/location/actions/analyze

HTTP メソッド POST

3.1.1 リクエスト

ヘッダ

名前値補足

X-Service-Code FJAI000012-00101 -

Content-Type application/json;charset=UTF-8 -

パラメータ

なし

メッセージボディ

形式：JSON

名前説明必須既定値

sentence 自然文（解析対象）

※文字数上限 1000 文字を超えている場合はエラー

◯ -



16 / 64

3.1.2 レスポンス

ヘッダ

名前値補足



形式：JSON

名前説明型

locations 推定結果のリスト

詳細は下記の「location」を参照。

object(location)[]

※推定結果が 0 件の場合、空のリスト（{"locations": []}）が返却されます。

location

名前説明型

name 地名 string

address 住所 string

longitude 緯度 number

latitude 経度 number

エラー情報


400 Bad Request The sentence is empty.

400 Bad Request The sentence length exceeded upper

limit value 1000 characters.

400 Bad Request The sentence is not UTF-8.

400 Bad Request The sentence is not JSON.

500 Internal Server Error The server encountered an internal

error.(エラーコード)

503 Service Unavailable Access is flooded. Please request

again for a while.(NLP00009)



17 / 64

3.1.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/location/actions/analyze -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00101" -H "Content-Type: application/json;charset=utf-8" -d '{"sentence": "港区でたこ焼きなう"}'

レスポンス

{ "locations": [ { "name": "港区", "address": "大阪府大阪市港区", "longitude": 135.461837, "latitude": 34.663038 } ] }



18 / 64

第4章 API詳細（固有名抽出）

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

パラメータ仕様」をご参照ください。

4.1 学習（カスタムルール作成）

学習データと辞書データを用いて、カスタムルールを作成します。

URI /NaturalLanguageProcessing/v1/annotation/models



ヘッダ

名前値補足



パラメータ

なし



19 / 64


形式：JSON


training_data 学習データ（パス形式）

※ファイルサイズ上限 50MB を超えている

場合はエラー。学習（カスタムルール更

新）API にて超える分を学習可能で

す。

※「付録 B.1 固有名抽出学習データ」

を参照

◯ -

word_dictionary 単語辞書（パス形式）


場合はエラー

※「付録 B.2 固有名抽出単語辞書」を

参照

- -

word_group_dictionary 単語列辞書（パス形式）


場合はエラー

※「付録 B.3 固有名抽出単語列辞

書」を参照

- -

user_dictionary ユーザー辞書（パス形式）


場合はエラー

※「付録 B.4 固有名抽出ユーザー辞

書」を参照

- -

comment コメント

※文字数上限 256 文字を超えている場

合はエラー

- -



20 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

model_id モデル ID string

accept 受付結果 boolean

エラー情報


400 Bad Request (指定したファイル) is empty file.

400 Bad Request The file size is too large.(NLP10002)(指

定したファイルのパス)/(指定したファイルのサイズ)

400 Bad Request The training data format error. Number

of [（該当行）] lines.

404 Not Found （指定したファイル）does not exist.



503 Service Unavailable Access is flooded. Please request again

for a while.(NLP00013)



21 / 64

4.1.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/models -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00201" -H "Content-Type: application/json;charset=utf-8" -d'{"training_data":"fs://FJAI000012/xxxxx/xxxxx/training_data_file","word_dictionary":"fs://FJAI000012/xxxxx/xxxxx/word_dictionary_file","word_group_dictionary":"fs://FJAI000012/xxxxx/xxxxx/word_group_dictionary_file","user_dictionary":"fs://FJAI000012/xx

xxx/xxxxx/user_dictionary_file","comment":"○○モデル"}'

レスポンス

{ "model_id":"XXXXXXXX", "accept": true }



22 / 64

4.2 学習（カスタムルール更新）

既存のカスタムルールに学習データを追加して、カスタムルールを更新します。

URI /NaturalLanguageProcessing/v1/annotation/models/{model_

id}/actions/update



ヘッダ

名前値補足



パラメータ

名前説明種別必須既定値

model_id モデル ID

対象ルールのモデル ID を設定します。

ユーザーが作成したルールのモデル ID について

は、ストレージサービスのフォルダ内容一覧取得

API にて確認可能です。

path ○ -


形式：JSON





新）API を再度実行することで超える

分を学習可能です。

※「付録 B.1 固有名抽出学習データ」を

参照

◯ -



合はエラー

- -



23 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型



エラー情報














24 / 64

4.2.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/models/xxxxxxxx/actions/update -H "Content-Type: application/json;charset=utf-8" -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00204" -d '{"training_data": "fs://FJAI000012/xxxxx/xxxxx/training_data_file", "comment":"○○モデル"}'

レスポンス




25 / 64

4.3 学習（標準ルールからカスタムルール作成）

標準ルールに学習データを追加して、カスタムルールを更新します。

URI /NaturalLanguageProcessing/v1/annotation/hostedModels/{h

osted_model_name}/actions/update



ヘッダ

名前値補足



パラメータ


hosted_model_name 標準ルールのモデル名

学習のベースとする標準ルールの

モデル名を設定します。

※標準ルールについては、「付録

C 標準ルール一覧」を参照。

path ○ -


形式：JSON





新）API にて超える分を学習可能で

す。

※「付録 B.1 固有名抽出学習データ」を

参照

◯ -



合はエラー

- -



26 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型



エラー情報







404 Not Found Common rule path does not exist.








27 / 64

4.3.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/hostedModels/named10/actions/update -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00302" -H "Content-Type: application/json;charset=utf-8" -d '{"training_data": "fs://FJAI000012/xxxxx/xxxxx/training_data_file", "comment":"○○モデル"}'

レスポンス




28 / 64

4.4 学習状態取得

学習処理の処理状態を確認します。学習処理は非同期処理のため、処理完了を把握するためには、当

API で確認する必要があります。


id}/actions/check

HTTP メソッド GET


ヘッダ

名前値補足


パラメータ







path ○ -


なし



29 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

status 学習状態（ステータス）

※各ステータスの説明については、「付

録 D ステータス一覧」を参照。

string

create_date 作成日時（UTC）

※フォーマット

YYYY-MM-DD hh:mm:ss

string

update_date 更新日時（UTC）


YYYY-MM-DD hh:mm:ss

string

training_data 学習データ（パス形式） string[]

training_data_size 学習データサイズ（byte）


NNN（整数）

※単位

byte

string

comment コメント string

エラー情報


404 Not Found Rule not found.


error. (エラーコード)



30 / 64

4.4.3 実行例

リクエスト

curl -X GET https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/models/xxxxxxxx/actions/check -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00202"

レスポンス

{ "status": "finished_without_error", "create_date": "2017-08-16 07:38:09", "update_date": "2017-08-16 07:38:09", "training_data": [

"fs://FJAI000012/xxxxx/xxxxx/training_data_file1", "fs://FJAI000012/yyyyy/yyyyy/training_data_file2"

], "training_data_size": "6,540,021 byte",

"comment":"○○モデル"

}



31 / 64

4.5 解析（カスタムルール）

学習処理で作成したカスタムルールを用いて、解析処理を実行します。


id}/actions/analyze



ヘッダ

名前値補足



パラメータ







path ○ -


形式：JSON


sentence 日本語文章

※サイズ上限 1MB を超えている場合はエラー

◯ -



32 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

result 固有名タグ付き日本語文章 string

エラー情報


400 Bad Request Given sentence is empty.

400 Bad Request The size of sentence exceeded the

upper limit value 1 MB







4.5.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/models/xxxxxxxx/actions/analyze -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00203" -H "Content-Type: application/json;charset=utf-8" -d '{"sentence": "宮崎県で宮崎さんに会う"}'

レスポンス

{ "result":"<LOCATION>宮崎</LOCATION>県で<PERSON>宮崎</PERSON>さんに会う" }



33 / 64

4.6 解析（標準ルール）

標準ルールを用いて、解析処理を実行します。

URI /NaturalLanguageProcessing/v1/annotation/hostedModels/{h

osted_model_name}/actions/analyze



ヘッダ

名前値補足



パラメータ


hosted_model_name 標準ルールのモデル名

学習のベースとする標準ルールの

モデル名を設定します。

※標準ルールについては、「付録

C 標準ルール一覧」を参照。

path ○ -


形式：JSON



※サイズ上限 1MB を超えている場合はエラー

◯ -



34 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

result 固有名タグ付き日本語文章 string

エラー情報




upper limit value 1 MB



404 Not Found Common rule path does not exist.





4.6.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/hostedModels/named10/actions/analyze -H "Content-Type: application/json;charset=utf-8" -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00301" -d '{"sentence": "宮崎県で宮崎さんに会う"}'

レスポンス

{ "result":"<Location>宮崎県</Location>で<Person>宮崎</Person>さんに会う" }



35 / 64

4.7 ルール削除

学習処理で作成したカスタムルールを削除します。


id}

HTTP メソッド DELETE


ヘッダ

名前値補足


パラメータ







path ○ -


なし


ヘッダ

名前値補足



なし

エラー情報


404 Not Found (モデル ID) does not exist.





36 / 64

4.7.3 実行例

リクエスト

curl -X DELETE https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/annotation/models/xxxxxxxx -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00205"

レスポンス

（なし）



37 / 64

第5章 API詳細（文章分類）

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

ラメータ仕様」をご参照ください。

5.1 学習（カスタムルール作成）

学習データと辞書データを用いて、カスタムルールを作成します。

URI /NaturalLanguageProcessing/v1/classification/models



ヘッダ

名前値補足



パラメータ

なし


形式：JSON


training_data 学習データファイル（パス形式）

※ファイルサイズ上限 100MB を超えている場合はエラ

ー。学習（カスタムルール更新）API にて超える分を学

習可能です。

※「付録 B.5 文章分類学習データ」を参照

◯ -

dictionary 辞書ファイル（パス形式）

※ファイルサイズ上限 10MB を超えている場合はエラー

※「付録 B.6 文章分類辞書」を参照

- -

max_length ルールに含まれる手がかりの最大数 (整数)

※最小 1~最大 5 範囲外はエラー

- 3

online オンライン学習回数 (整数)

※最小 0～最大 20 範囲外はエラー

- 10



- -



38 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型



エラー情報




定した学習データのパス)/(指定した学習データの

サイズ)










39 / 64

5.1.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00401" -H "Content-Type: application/json;charset=utf-8" -d '{"training_data": "fs://FJAI000012/xxxxx/xxxxx/training_data", "dictionary": "fs://FJAI000012/xxxxx/xxxxx/dictionary", "max_length": x, "online": xx, "comment":"○○モデル"}'

レスポンス

{ "model_id":"XXXXXXXX", "accept":true

}



40 / 64

5.2 学習（カスタムルール更新）

既存のカスタムルールに学習データを追加して、カスタムルールを更新します。

URI /NaturalLanguageProcessing/v1/classification/models/{mode

l_id}/actions/update



ヘッダ

名前値補足



パラメータ







path ○ -


形式：JSON



※ファイルサイズ上限 50MB を超えている場合はエラ

ー。学習（カスタムルール更新）API を再度実行す

ることで超える分を学習可能です。

※「付録 B.5 文章分類学習データ」を参照

◯ -



- -



41 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型



エラー情報




定した学習データのパス)/(指定した学習データの

サイズ)










42 / 64

5.2.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/xxxxxxxx/actions/update -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00405" -H "Content-Type: application/json;charset=utf-8" -d '{"training_data": "fs://FJAI000012/xxxxx/xxxxx/training_data", "comment":"○○モデル"}'

レスポンス


}



43 / 64

5.3 学習状態取得

学習処理の処理状態を確認します。学習処理は非同期処理のため、処理完了を把握するためには、当

API で確認する必要があります。


l_id}/actions/check



ヘッダ

名前値補足


パラメータ







path ○ -


なし



44 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

status 学習状態（ステータス）



string

create_date 作成日時（UTC）


YYYY-MM-DD hh:mm:ss

string

update_date 更新日時（UTC）


YYYY-MM-DD hh:mm:ss

string

training_data 学習データ（パス形式） string[]

training_data_size 学習データサイズ（byte）


NNN（整数）

※単位

byte

string

max_length ルールに含まれる手がかりの最大数 number

min_length ※次バージョン以降で使用予定 number

online オンライン学習回数 number

comment コメント string

エラー情報







45 / 64

5.3.3 実行例

リクエスト

curl -X GET https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/xxxxxxxx/actions/check -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00402"

レスポンス

{ "status":"learning", "create_date":"2017-08-17 04:17:00", "update_date":"2017-08-17 04:19:10", "training_data":[

"fs://FJAI000012/xxxxx/xxxxx/training_data_file1", "fs://FJAI000012/yyyyy/yyyyy/training_data_file2"

], "training_data_size":"6,540,073 byte", "max_length":3, "min_length":1, "online":10,

"comment":"○○モデル"

}



46 / 64

5.4 ルール精度評価

既存のカスタムルールに対して、精度を評価します。


l_id}/actions/evaluate



ヘッダ

名前値補足



パラメータ







path ○ -

threshold スコアの閾値

※15 桁以内の整数または小数（正負）。

number - 0


形式：JSON


test_data テストデータファイル（パス形式）

※ファイルサイズ上限 1MB を超えている場

合はエラー

※「付録 B.7 文章分類テストデータ」を

参照

◯ -



47 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

result 評価結果のリスト

詳細は下記の「evaluation」を参照。

object(evaluation)[]

evaluation

名前説明型

label ラベル string

precision 適合率 number

recall 再現率 number

f-measure F 値 number

エラー情報














48 / 64

5.4.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/k9j7nAhM/actions/evaluate -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00403" -H "Content-Type: application/json;charset=utf-8" -d '{"test_data": "fs://FJAI000012/xxxxx/xxxxx/training_data", "threshold": -0.123}'

レスポンス

{ "result":[

{ "label":"emg", "precision":1, "recall":1, "f_measure":1

}, {

"label":"usual", "precision":0.5, "recall":1, "f_measure":0.666666666666667

} ]

}



49 / 64

5.5 解析

学習処理で作成したカスタムルールを用いて、解析処理を実行します。


l_id}/actions/analyze



ヘッダ

名前値補足



パラメータ







path ○ -


形式：JSON




合はエラー

◯ -



50 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

result 解析結果のリスト

詳細は下記の「classification」を参

照。

object(classification)[]

classification

名前説明型

label ラベル string

score スコア number

エラー情報




upper limit value 1000 characters.









51 / 64

5.5.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/xxxxxxxx/actions/analyze -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00404" -H "Content-Type: application/json;charset=utf-8" -d '{"sentence": "暴風雨で停電だ"}'

レスポンス

{ "result":[

{ "label":"emg", "score":0.365833274

}, {

"label":"usual", "score":-0.365833274

} ]

}



52 / 64

5.6 解析（ファイル入出力）

学習処理で作成したカスタムルールを用いて、解析処理を実行します。複数文章が記述されたファイルを指

定することで、複数文章を一括して解析することが可能です。


l_id}/actions/file_analyze



ヘッダ

名前値補足



パラメータ







path ○ -


形式：JSON


sentence_file 日本語文章ファイル

※サイズ上限 50MB を超えている場合はエ

ラー

◯ -

output_dir 出力フォルダ

※指定しない場合は sentence_file が存

在するフォルダが自動的に指定される

- -



53 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

analysis_id 解析 ID string


エラー情報


400 Bad Request (指定したファイル) file is empty.

400 Bad Request The size of (指定した日本語文章ファイル)

exceeded the upper limit value

50MB.








54 / 64

5.6.3 実行例

リクエスト

curl -X POST https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/xxxxxxxx/actions/file_analyze -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00407" -H "Content-Type: application/json;charset=utf-8" -d '{"sentence_file": "fs://FJAI000012/xxxxx/xxxxx/sentence_file.txt", "output_folder": "fs://FJAI000012/classification/output"}'

レスポンス


}



55 / 64

5.7 解析状態取得

解析（ファイル入出力）処理の処理状態を確認します。解析（ファイル入出力）処理は非同期処理の

ため、処理完了を把握するためには、当 API で確認する必要があります。

URI /NaturalLanguageProcessing/v1/classification/analysis/{anal

ysis_id}/actions/check



ヘッダ

名前値補足


パラメータ


analysis

_id

解析 ID

状態取得対象の解析 ID を設定します。

解析 IDは解析（ファイル入出力）APIのレスポ

ンスに設定されています。

path ○ -


なし



56 / 64


ヘッダ

名前値補足



形式：JSON

名前説明型

status 解析状態（ステータス）



string


analysis_date 解析日時（UTC）


YYYY-MM-DD hh:mm:ss

string

sentence_file 日本語文章ファイル（パス形式） string

sentence_file_size 日本語文章サイズ（byte）


NNN（整数）

※単位

byte

string

output_file 解析結果ファイル（パス形式） string

エラー情報







57 / 64

5.7.3 実行例

リクエスト

curl -X GET https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/analysis/xxxxxxxx/actions/check -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00408"

レスポンス

{ "status":"finished_without_error", "model_id":"zzzzzzzz", "date":"2017-12-15 13:09:29", "sentence_file":"fs://FJAI000012/xxxxx/sentence.txt", "sentence_file_size":15, "output_file":"fs://FJAI000012/yyyyy/sentence_zzzzzzzz.out"

}



58 / 64

5.8 ルール削除

学習処理で作成したカスタムルールを削除します。


l_id}

HTTP メソッド DELETE


ヘッダ

名前値補足


パラメータ







path ○ -


なし


ヘッダ

名前値補足



なし

エラー情報


404 Not Found (モデル ID) does not exist.





59 / 64

5.8.3 実行例

リクエスト

curl -X DELETE https://zinrai-pf.jp-east-1.paas.cloud.global.fujitsu.com/NaturalLanguageProcessing/v1/classification/models/xxxxxxxx -H "X-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" -H "X-Service-Code: FJAI000012-00406"

レスポンス

(なし)



60 / 64

付録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 ※()内にオブジェクト名表記オブジェクト（キーと値の組の集まり）



61 / 64

付録B データ仕様

本付録では、学習データや辞書などのデータ仕様について説明します。

なお、学習データや辞書などのファイルはストレージサービス API を用いて登録を行います。ストレージサービ

ス API については以下のリファレンスを参照してください。

https://k5-doc.jp-east-1.paas.cloud.global.fujitsu.com/doc/jp/zinrai-pf/document/r

eference/reference_storage.pdf

B.1 固有名抽出学習データ

固有名タグを付与した以下のような文章となります。

<Person>宮崎</Person>さんと<Location>宮崎</Location>に行く。

<Location>広島</Location>で<Person>広島</Person>さんに会う。

固有名タグは、新規学習時においてユーザー任意で命名することが出来ます。追加学習時においては、新

規学習時と同じ固有名タグを使う必要があります。

学習データは改行で区切った文章毎に学習されます。文章間の関係については学習されません。

B.2 固有名抽出単語辞書

単語辞書は固有名を抽出するための手がかりとなります。以下のようなフォーマットとなります。

KEY\tVALUE1\tVALUE2\t....

KEY がマッチングを行う KEY で、VALUE1、VALUE2 が KEY に対する値です。

「\t」が値の区切り文字で「タブ」を意味します。KEYにマッチすると、VALUEを使用します。VALUEは「\t」

により区切り、複数定義することが出来ます。

例えば、以下のように定義すると、「株式会社」や「富士通」が組織名として抽出されやすくなります。

株式会社\t 組織関連

富士通\t 組織

B.3 固有名抽出単語列辞書

単語列辞書は、単語辞書と同様に固有名を抽出するための手がかりとなります。フォーマットは単語辞書と

同じですが、単語ではなく単語列を KEY とする点が異なります。

例えば、以下のように定義します。

富士通株式会社\t 組織

富士通研究所\t 組織





62 / 64

B.4 固有名辞書ユーザー辞書

ユーザー辞書は、固有名に対して直接的にタグの振り方を調整することが出来ます。フォーマットは、単語辞

書や単語列辞書と同様にタブ区切りですが、KEY には固有名、VALUE には「固有名-SC=スコア」を定義し

ます。スコアは、その固有名になりやすさを示す点数です。高い数値ほど抽出されやすくなります。スコアは-10

から 10 の整数を半角数字で指定してください。スコアの正の値は、その固有名として抽出するために、負の値

は、その固有名として抽出しないために、指定してください。

次の例は、富士通に組織名（Organization）をスコア 10、人名（Person）をスコア 2 として与えて、

富士通研究所に組織名（Organization）をスコア 5 として与えた場合です。

富士通¥tOrganization-SC=10¥tPerson-SC=2

富士通研究所¥tOrganization-SC=5

B.5 文章分類学習データ

学習データは、分類したいラベルと文章を空白区切りで定義します。フォーマットは以下の通りです。

LABEL TEXT

1 文章に対し、複数のラベルを定義することも可能です。その場合は、各ラベルを以下のように,（カンマ）

区切りにしてください。

LABEL1,LABEL2,LABEL3 TEXT

以下は、emg（緊急）／usual（日常）を分類する場合の学習データ例となります。

emg 強風で停電

usual ご飯を食べた

B.6 文章分類辞書

辞書を使用することによって、素性を増やすことが出来ます。フォーマットは以下の通りです。

KEY\tVALUE1\tVALUE2\t....

KEY が辞書のキーで、VALUE1、VALUE2 がその値です。「\t」はタブで区切り文字です。

例えば、次のように定義した場合、「火事」は「緊急」と「火災」、「強風」は「緊急」として利用されます。

火事\t 緊急\t 火災

強風\t 緊急

B.7 文章分類テストデータ

テストデータは、正解のラベルと評価したい文章で構成されるデータです。フォーマットは、「付録 B.4 文章分

類学習データ」と同様です。



63 / 64

付録C 標準ルール

標準ルールとは、サービスが提供する標準的なルールです。

ユーザーは学習処理でルールを作成せずに解析処理を実行することや、標準ルールからカスタムルールを作

成することができます。

自然文解析の固有名抽出における標準ルールのラインナップを以下に示します。

標準ルール名

{hosted_model_name}

説明

named10 以下の固有名タグ 10 種を付与します。

タグ名定義

Person 人名

Organization 組織名

Location 場所

Artifact 人工物

Phone-number 電話番号

Time 時間

Date 日付

Money 金額

Percent 割合

Zip 郵便番号



64 / 64

付録D ステータス一覧

学習状態取得 API および解析状態取得 API で確認できる非同期処理のステータスを以下に示します。

ステータス説明

queueing 処理開始待ち中

queue_timeout 処理開始待ちでタイムアウト

learning/analyzing 学習処理中／解析処理中

internal_server_error サーバエラーで異常終了

finished_without_error 正常終了

finished_with_error 異常終了

process_timeout プロセスタイムアウト

process_interruption プロセス中断

サーバエラーにより、処理が中断されました。学習処理を再

実行してください。

Documents

API リファレンス‚¹トレージのAPI リフアレンスのURL を 追加 1.3 2018/4/26 2.2 暗号化プロトコルのサポートについて記 載 3/64 ... 408 Request

API リファレンス‚¹トレージのAPI リフアレンスのURL を追加 1.3 2018/4/26 2.2 暗号化プロトコルのサポートについて記載 3/64 ... 408 Request