データファイルレコード取得APIを実装したい
回答
本記事では、貴社の基幹システム/アプリケーションからb→dash上のデータファイルのレコードを取得するための「データファイルレコード取得API」の仕様について紹介しています。
本記事の構成は、大きく下記の4つです。
1. APIの概要
2. 利用にあたっての前提事項
3. リクエスト仕様
4. レスポンス仕様
各項目の詳細は、以下をご参照ください。
1. APIの概要
データファイルレコード取得APIとは、貴社の基幹システム/アプリケーションとb→dashを繋ぐことで、b→dash上のデータファイルのレコードの値を取得できるAPIです。
b→dash管理画面の「データファイル詳細画面」の操作と同様に、カラムに対して条件指定を行うことでレコードを絞り込むことができます。
※ データファイルレコード取得APIはレコードを取得することはできますが、b→dashにデータを送信し新しくデータファイルを作成することはできません。新規にデータファイルを作成したい場合は「データファイル新規作成API(未リリース)」をご活用ください
2. 利用にあたっての前提事項
● 事前準備: 本APIを利用する事前準備として、b→dash管理画面上でレコードの値を取得したいデータファイルの「取込設定」を完了させておく必要があります。取込設定がまだ完了していない場合は「データを取り込みたい」をご参照ください
● 共通仕様: 本APIでは、b→dash APIの共通仕様も参照する必要があります。詳細は「b→dash APIの共通仕様を知りたい」をご参照ください
3. リクエスト仕様
URIと各パラメータ
● APIのURI
● URIパラメータ
プロパティ |
データ型/サイズ |
必須 |
値 |
説明 |
| datafile_id | string/255byte | ○ |
{データファイルID} | レコードを取得したいデータファイルのID |
● クエリパラメータ
プロパティ |
データ型/サイズ |
必須 |
値 |
説明 |
| limit | string/5byte | - |
1〜10000 | レコードの最大取得件数(最大10000レコード、未指定時:10000レコード) |
● リクエストURIサンプル
リクエストボディパラメータ
json形式のファイル(拡張子: .json)に取得したいレコードの情報を送信するためのリクエストボディを準備します。リクエストボディパラメータの主要なものは下記の通りです。
プロパティ |
データ型/サイズ |
必須 |
説明 |
| query_condition | object/153400byte | - |
検索条件の指定 |
| └ condition_or | object[]/153400byte | - |
OR条件のブロック(最大10個まで設定可能) |
| └ condition | object[]/15340byte | - |
AND条件のブロック(1つのORブロック内で最大20個まで設定可能) |
| └ column_id | string/255byte | △ |
検索対象のデータファイル上でのカラムID(「condition」の指定がある場合、必須) |
| └ condition_name | string/2byte | ○ |
条件指定(下記「レコード絞り込み条件と指定方法の一覧」参照) |
| └ condition_value | object/510byte | △ |
条件値(条件指定が「BL」「NB」「NL」「NN」「T」「F」以外の場合必須) |
| └ value | string/255byte | △ |
条件値(条件指定が「BW」「NW」以外の場合必須) |
| └ from | string/255byte | △ |
範囲/期間指定の条件の開始値(「BW」「NW」の場合は必須) |
| └ to | string/255byte | △ |
範囲/期間指定の条件の終了値(「BW」「NW」の場合は必須) |
| sort_condition | object/2590byte | - |
ソート条件 |
| └ condition | object[]/2590byte | - |
ソート条件のブロック(最大10個まで設定可能) |
| └ column_id | string/255byte | △ |
ソート対象のカラムID |
| └ sort_order | string/4byte | - |
ソート方法(『asc』:昇順、『desc』:降順、未指定時: 昇順) |
● リクエストボディサンプル
本APIで利用可能な「絞り込み条件」と「コードの指定方法」の一覧です。データ型ごとに使用できる条件が異なります。
データ型 |
絞込み条件 |
抽出条件の定義 |
指定方法 |
| テキスト型以外 | NULL | NULLを抽出する | NL |
| テキスト型以外 | NULLではない | NULL以外を抽出する | NN |
| テキスト | 空文字 | 空文字を抽出する(スペースは含まれない) | BL |
| テキスト | 空文字ではない | 空文字以外を抽出する | NB |
| テキスト | 次を含む | 指定した文字列を含む値を抽出する | LK |
| テキスト | 次を含まない | 指定した文字列を含まない値を抽出する | NI |
| テキスト | 次で始まる | 指定した文字列の前方一致で抽出する | L% |
| テキスト | 次で終わる | 指定した文字列の後方一致で抽出する | %L |
| テキスト | 次に完全一致 | 指定した文字列の完全一致で抽出する | EQ |
| テキスト | 次に完全一致しない | 指定した文字列の完全不一致で抽出する | NE |
| 整数/小数 | 次より大きい / 以上 / 次より小さい / 以下 | 指定した数値の大小比較で抽出する | GT/GE/LT/LE |
| 整数/小数 | 次の値の間 / 次の値の間にない | 指定した2つの数値の間にある/ない値を抽出する | BW/NW |
| 整数/小数 | 次と等しい / 次と等しくない | 指定した数値と等しい/等しくない値を抽出する | EQ/NE |
| 日付 | 次より前 / 後 / 次の日付 | 指定した日付との比較(yyyyMMdd形式) | LT/GT/EQ |
| 日付 | 次の期間にある / にない | 指定した2つの日付の間(yyyyMMdd形式) | BW/NW |
| 日時 | 次より前 / 後 / 日付 / 次の期間にある/にない | 指定した日時との比較(yyyyMMddhh24miss形式) | LT/GT/EQ/BW/NW |
| 真偽値 | TRUE / FALSE | 「true」「false」を抽出する | T/F |
リクエスト形式とヘッダ
リクエスト形式は「GET」です。リクエストヘッダパラメータは下記の通りです。
プロパティ |
型/サイズ |
必須 |
値 |
説明 |
| Authorization | string/2055字 | ○ |
Bearer {アクセストークン} | 「認証方式を選択したい」で取得したアクセストークン |
| Range | string/255字 | - |
{リクエスト開始行数}-{リクエスト終了行数} | レコードを取得する範囲(未指定:先頭レコードから{limit}件数を取得) |
● リクエストコードサンプル
2回目以降のAPI呼び出しは、データファイルから任意のレコードを指定できる「Range」パラメータを利用して1万件以降のレコードを指定してください。
例: 2万件取得したい場合、1回目で1〜10000番目、2回目で10001〜20000番目を「Range」パラメータで指定・取得します。
4. レスポンス仕様
リクエストの送信に成功すると、下記のレスポンスボディパラメータでデータファイルレコード取得APIからレスポンスが返されます。
パラメータ名 |
データ型 |
説明 |
| Content-Type | string |
レスポンス形式 application/json charset=UTF-8(b→dashAPI共通仕様) |
| Content-Range | string |
リクエスト範囲 {リクエスト開始行数}-{リクエスト終了行数}/{合計件数} |
● レスポンスボディサンプル
リクエストエラーが発生した場合、HTTPステータスコード「400」とともに下記のエラーメッセージが返されます。
# |
エラーメッセージ |
説明 |
1 |
リクエストヘッダ「Range」には10,000行以内でリクエスト開始行数とリクエスト終了行数を指定してください | 「Range」の指定が10,000行を超過した |
2 |
condition_nameに「{condition_name}」を指定時は、condition_value.valueを指定してください | 「BL」「NB」「NL」「NN」「BW」「NW」「T」「F」以外を指定時にvalueが未指定 |
3 |
condition_nameに「{condition_name}」を指定時は、condition_value.fromを指定してください | 「BW」「NW」を指定時にfromが未指定 |
4 |
condition_nameに「{condition_name}」を指定時は、condition_value.toを指定してください | 「BW」「NW」を指定時にtoが未指定 |
5 |
{sort_order}には以下のいずれかを指定してください asc / desc | ソート方法に不正な文字列が指定された |
6 |
limitには1〜10,000を指定してください | 最大取得件数に範囲外の値が指定された |
7 |
データファイル「{datafile_id}」カラム「{column_id}」が存在しません | 検索対象のカラムIDがデータファイルに存在しない |
8 |
データファイル「{datafile_id}」にカラム「{column_id}」が存在しません | ソート対象のカラムIDがデータファイルに存在しない |
9〜14 |
各データ型(テキスト/整数/小数/日付/日時/真偽値)のカラムの{condition_name}には対応する指定子のみ指定可能 | データ型に対して許可されていない条件指定が使用された |
15〜26 |
各データ型の{value}/{from}/{to}には対応する型に変換可能な文字列を指定してください | 条件値が対象のデータ型と一致しない |
27 |
「query_condition.condition_or.condition.column_id」が存在しません | 検索条件のカラムが未指定 |
28 |
「sort_condition.condition.column_id」が存在しません | ソート条件のカラムが未指定 |