ページング方式
IT Management API の主なページング方式はカーソルベースです。一部のエンドポイント（users）ではページ番号ベースを使用します。
カーソルベースページング（主要方式）
ほとんどの一覧取得エンドポイント（people / services / devices / identity / event-logs / contracts / alerts など）はカーソルベースです。
リクエストパラメータ
| パラメータ | 型 | デフォルト | 最大値 | 説明 |
|---|
cursor | string | — | — | 前回レスポンスの nextCursor 値。省略時は先頭から取得 |
limit | number | — | 200 | 1回に返す件数 |
event-logs エンドポイントでは、リクエストパラメータ名が cursor ではなく nextCursor になります。
レスポンス形式
{
"meta": {
"nextCursor": "F3UdkoSbpBNrjwP93AX2HQ",
"totalItems": 100
},
"items": [
// リソースの配列
]
}
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|
meta.nextCursor | string | null | 次ページ取得用カーソル。null のとき最終ページ |
meta.totalItems | integer | null | 総件数。null になることがある |
items | array | 取得したリソースの配列 |
使用例
# 最初のページを取得
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.itmc.i.moneyforward.com/api/v1/organizations/YOUR_ORG_ID/people?limit=50"
# 次のページを取得（前回レスポンスの nextCursor を使用）
curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://api.itmc.i.moneyforward.com/api/v1/organizations/YOUR_ORG_ID/people?cursor=F3UdkoSbpBNrjwP93AX2HQ&limit=50"
async function fetchAllPeople(orgId) {
const allItems = [];
let cursor = undefined;
do {
const params = new URLSearchParams({ limit: '200' });
if (cursor) params.set('cursor', cursor);
const response = await fetch(
`https://api.itmc.i.moneyforward.com/api/v1/organizations/${orgId}/people?${params}`,
{ headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
const data = await response.json();
allItems.push(...data.items);
cursor = data.meta.nextCursor;
} while (cursor);
return allItems;
}
ページ番号ベースページング（users エンドポイント）
GET /api/v1/organizations/{id}/users はページ番号ベースのページングを使用します。
リクエストパラメータ
| パラメータ | 型 | 説明 |
|---|
page | number | ページ番号（1 始まり） |
limit | number | 1ページあたりの件数 |
レスポンス形式
{
"metadata": {
"prevPage": 1,
"nextPage": 3
},
"users": [
// ユーザーの配列
]
}
ベストプラクティス
nextCursor が null になるまでループして全件取得する- 必要以上に大きな
limit を指定しない（上限: 200）
totalItems は null になることがあるためループ終了の判定には使用せず、nextCursor の有無で判断する
