2.4.3 データ検索API

データをメタデータで検索し、検索条件に合致する伝票データ一覧のID（ticket_id）リストを取得する際に用いるWeb APIです。

取得されたIDはデータダウンロードAPIで利用されます。

データ種別識別子以外の項目に対して、値の最後に“*”を付与することでAND検索、“-”を付与することでOR検索を項目間の条件として指定することができます。指定がない場合はAND検索を行います。
項目内の値をカンマ区切りで指定することで複数の条件のOR検索が可能です。

例）

以下のように指定されていた場合、発送元拠点コードが“1234567890123”または“1234567890321”かつ、発送先拠点コードが“1234567890123”のデータを検索します。

src_location_code=1234567890123,1234567890321*&dst_location_code=1234567890123*

正常に処理が完了した場合は検索条件に合致した伝票データのIDリストがJSON形式で返却されます。

マスキング機能が有効な場合、実行したユーザーのアクセス権限チェックを行います。返却する伝票データのIDリストに対してマスキングすることが可能です。

検索条件に応じたデータが存在しない場合はその旨が返却されます。

図2.3 データ検索APIの呼び出し関係

(1) データ種別識別子に応じた検索用パラメータを取得します。

(2) 伝票抽出用メタデータデータベース(FUJITSU Software Enterprise Postgres)に対してSQLを実行します。

アクセス権限コントロール連携ありの場合、伝票データIDにマスキング処理を行うため、以下(3)を実施します。
(アクセス権限コントロール連携なしの場合、マスキング処理は行われません。)

(3) ユーザー情報からアクセスルールを取得し、取得したアクセスルールを元に伝票データのIDリストをマスキングします。

2.4.3.2 リクエスト設計

2.4.3.2.1 リクエストフォーマット

項目		値			備考
APIエンドポイント (相対URI)		/search
クエリパラメーター	data_type	必須		データ種別識別子	任意の値(数字文字列)を指定することができます例) 出荷予定データの場合：10 出荷確定データの場合：20
	get_status	任意		取得フラグ	0: 未取得，1: 取得済, 2: 未取得・取得済み両方注)初期値: 0，データダウンロードAPIで取得された場合: 1,未指定時: 0
	src_location_code	任意		発送元拠点コード	未指定時は全ヒット
	dst_location_code	任意		発送先拠点コード	未指定時は全ヒット
	from_create_datetime	任意		検索範囲の始点日時	YYYYmmddHHMMSS形式未指定時は全ヒット
	to_create_datetime	任意		検索範囲の終点日時	YYYYmmddHHMMSS形式未指定時は全ヒット
	key名	任意		検索用パラメータ	パラメータ名は定義されている検索用パラメータの項目名が設定されます最大で20個設定可能とします
	separator	任意		検索値の区切り文字	指定がない場合はカンマとしますエスケープ文字も指定可能です例) & → %26
HTTPメソッド		GET
HTTPリクエストヘッダ	Authorization	任意	Bearer {token}		使用する認証サービスのユーザー認証用トークンを指定します

例)

curl -i -s http://<開発実行環境サーバのIPアドレス>:<ポート番号(注)>/search?data_type=10"&"get_status=0"&"src_location_code=1234567890321"&"dst_location_code=1234567890123"&"from_create_datetime=20210524120130"&"to_create_datetime=20210624120130 -X GET

注)インベントリファイルのapi_tomcat_portに設定した値を指定

参照

Apahe Tomcatに配備されたAPIエンドポイント(相対URI)は、Apache Tomcatの設定により異なります。

Apache Tomcatに配備されたAPIエンドポイント(相対URI)の確認方法については、Apache Tomcatのオンラインマニュアルなどを参照してください。

2.4.3.3 レスポンス設計

2.4.3.3.1 レスポンスフォーマット

項目		値	備考
HTTPステータス		int(3桁)	正常時200、異常時は後述
HTTPレスポンスヘッダ	Cache-Control	キャッシュに関する情報
	Content-Type	application/json;charset=UTF-8
	Transfer-Encoding	符号化方式
	Date	日付
HTTPレスポンスボディ	ticket_id	ticket_id一覧	JSON配列 (要素はstring) データダウンロードAPIで利用

例)

HTTP/1.1 200
Cache-Control: no-cache
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 26 Jan 2022 02:53:22 GMT

{"ticket_id":["xxxxxxxxxxxxxxxxxxxx","xxxxxxxxxxxxxxxxxxxx","xxxxxxxxxxxxxxxxxxxx"]}

2.4.3.3.2 HTTPステータスコード

HTTPステータスコード	メッセージ	利用場面
200	OK	リクエストの処理に成功した
400	Bad Request	リクエスト違反(Content-Typeが空など)や他の400番台が適さない
401	Unauthorized	認証されていない、または認証に失敗した
403	Forbidden	認証以外の理由でリソースへアクセスできない
404	Not Found	サーバーがリクエストされたリソースを発見できない
405	Method Not Allowed	指定以外のHTTPメソッドを指定された
408	Request Time-out	リクエストがタイムアウトした
415	Unsupported Media Type	サポートしていないメディアタイプが指定された
500	Internal Server Error	APIで障害が発生した
503	Service Unavailable	APIが一時的に処理を行うことができない

2.4.3.4 メッセージボディ

HTTPステータスコード	メッセージボディ
200	リソース内容を表示
400/500番台	エラーコードと説明文を表示

2.4.3.5 エラーメッセージ

形式

分類	内容
code	エラーの詳細な種類（HTTPステータスコードではない）
message	エラーメッセージ本文

例）

HTTP/1.1 400
Content-Type: application/json;charset=UTF-8
Transfer-Encoding: chunked
Date: Tue, 08 Jun 2021 17:56:21 GMT
Connection: close

{"error_codes":[{"code":"103","message":"Invalid dst location code."}]}

エラーリスト

HTTPステータスコード	エラーコード	内容
400	001	リクエストボディの形式が誤っている（JSON形式でない）
400	002	データ種別識別子の値が設定されていない
400	101	データ種別識別子の値が不正である
400	102	発送元拠点コードの値が不正である
400	103	発送先拠点コードの値が不正である
400	105	取得済みフラグの値が不正である
400	106	検索範囲の始点日時の値が不正である
400	107	検索範囲の終点日時の値が不正である
401	201	認証用トークンによる認証に失敗した
403	202	アクセスが許可されていないユーザーのアクセスによる認可エラー
404	203	存在しないデータにアクセスした
405	206	指定以外のHTTPメソッドを指定された
408	204	データへのアクセスがタイムアウトした
413	205	リクエストボディのサイズが上限値を超えた
500	301	予期せぬエラーが発生した
503	303	API側の不具合によるエラー