レコード一覧の検索

パスで指定されたエンティティのレコードを検索し、一覧で返却する

📬 リクエスト

GET {resource_api_url}/records/{entity_name}

リクエストヘッダ

キー	値
Authorization	Bearer {アクセストークン}

パスパラメータ

パラメータ	形式	必須	説明	値の例
entity_name	文字列	YES	検索対象レコードのエンティティ名	account

クエリパラメータ

パラメータ	形式	必須	説明	値の例
fields	文字列	YES	返却対象の項目名（カンマ区切り）	name,industry,revenue
filter	filterパラメータオブジェクト	NO	レコード検索条件	{ "and": [ { "field": "industry", "operator": "eq", "value": "public_admin" } ] }
group_by	文字列	NO	グループ化する項目名（カンマ区切り）	industry
order_by	order_byオブジェクトの配列	NO	検索結果のソート条件	[{ "field": "industry", "direction": "asc" }]
limit	整数値	NO	1回のリクエストで取得する最大レコード数	100
offset	整数値	NO	取得開始位置（スキップするレコード数）	0
location	locationオブジェクトの配列	NO	ロケーション検索専用オブジェクト	{ "point": { "latitude": 35.6795964, "longitude": 139.7460797 }, "radius": 10000 }

order_byオブジェクト

フィールド	形式	必須	説明	値の例
field	文字列	YES	ソート適用対象の項目名	industry
direction	asc（昇順） desc（降順）	NO	ソート方向（省略時は昇順扱い）	asc

locationオブジェクト

フィールド	形式	必須	説明	値の例
point.latitude	数値	YES	検索対象の緯度	35.6795964
point.longitude	数値	YES	検索対象の経度	139.7460797
radius	数値	YES	検索半径（単位: メートル）	10000

✨ 成功レスポンス

ステータスコード

200 : OK

レスポンスヘッダ

キー	値
Content-Type	application/json

レスポンスボディ

フィールド	形式	必須	説明	値の例
has_next_page	真偽値	YES	レコード検索結果に対して、次ページが存在するかどうか	true
total_size	整数値	YES	レコード検索条件に合致するレコード総数	371
data	オブジェクトの配列	YES	検索結果（レコード一覧） データ型がtextの項目におけるオブジェクト要素の形式: 文字列 or null データ型がnumericの項目におけるオブジェクト要素の形式: 数値 or null データ型がbooleanの項目におけるオブジェクト要素の形式: 真偽値 or null データ型がdateの項目におけるオブジェクト要素の形式: 文字列（ISO8601の日時フォーマット） or null データ型がoptionの項目におけるオブジェクト要素の形式 サブデータ型がsingleの場合 : 文字列 or null サブデータ型がmultiの場合 : 文字列の配列 データ型がreferenceの項目におけるオブジェクト要素の形式 サブデータ型がsingleの場合 : レコード参照オブジェクト or null サブデータ型がmultiの場合 : レコード参照オブジェクトの配列	[ { "name": "株式会社 001132", "industry": "public_admin", "revenue": 336000000 }, ... ]

レコード参照オブジェクト

フィールド	形式	必須	説明	値の例
entity_name	文字列	YES	参照レコードのエンティティ名	lead
id	文字列	YES	参照レコードのID	lead-00000001
title	文字列	YES	参照レコードのタイトル	株式会社 ABC

レスポンスボディのサンプル

レスポンスボディのサンプル

{
  "has_next_page": true,
  "total_size": 371,
  "data": [
    {
      "name": "株式会社 001132",
      "industry": "public_admin",
      "revenue": 336000000
    },
    {
      "name": "株式会社 001566",
      "industry": "it",
      "revenue": 204000000
    },
    ...
  ]
}

💬 具体的な要求事項

• 検索対象のレコードが存在しない場合は、「data」フィールドに空配列を設定してください（「200 : OK」）

「fields」パラメータ

• 指定された項目の値のみを結果に含めてください

「filter」パラメータ

• filterパラメータ仕様に従い実装してください
• 「filter」パラメータが受け取るオブジェクトから貴社システムに対する検索条件を生成し、レコードの検索を行ってください

「group_by」パラメータ

• 「group_by」パラメータが指定された場合、指定の項目で結果をグルーピングする必要があります（SQLのgroup by句と同等）
• 「fields」パラメータに指定された項目が「group_by」パラメータに含まれない場合、それらの項目を無視、もしくは、エラーとしてください
  • UPWARDが送信するリクエストでは、そのようなパラメータの指定は行いません

「order_by」パラメータ

• 「order_by」パラメータが指定された場合、指定の項目で結果をソートする必要があります（SQLのorder by句と同等）
• 「order_by」パラメータが指定されない場合、結果のソート順は任意ですが、冪等になるようルールを設定してください（例: ID順）

「limit」パラメータ

• 「limit」パラメータが指定された場合、指定の件数を最大値としたレコード数を返却する必要があります（SQLのlimit句と同等）

「offset」パラメータ

• 「offset」パラメータが指定された場合、指定の件数分をスキップしたレコード一覧を返却する必要があります（SQLのoffset句と同等）
• UPWARDが送信するリクエストでは、offsetパラメータ指定時はlimitパラメータも必ず指定されます

「location」パラメータ

• 単一エンティティの取得 - レスポンスボディの「has_location」がtrueのエンティティに対する検索時にのみ「location」パラメータが指定されます
  • 該当しないエンティティにおいては対応する必要はありません
• 「location」パラメータが指定された場合、通常の検索条件（「filter」パラメータ）に加え、位置情報と半径に基づいた近傍検索を行ってください
  • 例: 「point」フィールド（例: { "latitude": 35.6795964, "longitude": 139.7460797 }）から「radius」フィールド（例: 10000メートル）以内のレコード
• 「location」パラメータが指定された場合、返却するレコード一覧の順序は「point」フィールドに指定された位置から近いレコード順としてください（「order_by」パラメータの指定よりも優先してください）
• 「location」パラメータと「group_by」パラメータが同時に指定された場合、エラーとしてください
  • UPWARDが送信するリクエストでは、そのようなパラメータの指定は行いません

「has_next_page」レスポンスフィールド

• 「filter」パラメータ + 「limit」パラメータ + 「offset」パラメータを用いて得られる検索結果（= 「data」レスポンスフィールド）に対し、残りの検索結果（ページ）が存在するかどうかを返却してください

「total_size」レスポンスフィールド

• レコード検索条件に合致するレコード総数を返却してください
  • この値は、「limit」パラメータ、および、「offset」パラメータを指定しない場合の「data」レスポンスフィールドの件数と合致します

「data」レスポンスフィールド

• 検索されたレコードの一覧を返却してください

📚 参考資料

• filterパラメータ仕様