Qoder CN シリーズ:ページネーション

リクエストパラメーター

パラメーター	タイプ	必須	デフォルト	説明
limit	integer	いいえ	20	ページあたりの項目数。範囲は 1～100 です。
before_id	string	いいえ	—	この ID より前のレコードを返します (逆方向ページング)。
after_id	string	いいえ	—	この ID より後のレコードを返します (順方向ページング)。

レスポンス構造

すべてのリストエンドポイントは、同じページネーションエンベロープを返します。

{
  "data": [
    { "id": "agent_abc123", "name": "my-agent", "...": "..." },
    { "id": "agent_def456", "name": "another-agent", "...": "..." }
  ],
  "first_id": "agent_abc123",
  "last_id": "agent_def456",
  "has_more": true
}

フィールドの説明

フィールド	タイプ	説明
data	array	現在のページのリソース。
first_id	string | null	このページの最初のレコードの ID。
last_id	string | null	このページの最後のレコードの ID。
has_more	boolean	さらにレコードが残っているかどうか。

基本的な使用法

最初のページのフェッチ

# 最初の 10 エージェントを取得
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

順方向ページング

前のレスポンスの last_id を after_id として使用します。

# agent_def456 以降の 10 レコードを取得
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

逆方向ページング

現在のページの first_id を before_id として使用します。

# agent_abc123 以前の 10 レコードを取得
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&before_id=agent_abc123" \
  -H "Authorization: Bearer $QODER_PAT"

完全なトラバーサルの例

次のスクリプトは、すべてのエージェントを反復処理します。

#!/bin/bash
# すべてのエージェントを反復処理し、名前を出力
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
has_more=true
after_id=""
page=1

while [ "$has_more" = "true" ]; do
  url="$BASE_URL/agents?limit=50"
  if [ -n "$after_id" ]; then
    url="$url&after_id=$after_id"
  fi

  response=$(curl -s "$url" \
    -H "Authorization: Bearer $QODER_PAT")

  count=$(echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data']))")
  has_more=$(echo "$response" | python3 -c "import sys,json; print(str(json.load(sys.stdin)['has_more']).lower())")
  after_id=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin)['last_id'] or '')")

  echo "Page ${page}: ${count} records"

  echo "$response" | python3 -c "
import sys, json
data = json.load(sys.stdin)['data']
for item in data:
    print(f\"  - {item['id']}: {item.get('name', 'unnamed')}\")
"

  page=$((page + 1))
  sleep 0.1
done

echo "Done"

limit の動作

値	動作
省略	デフォルトで 20 になります。
1	最小値。1 つのレコードを返します。
100	最大値。100 個のレコードを返します。
0 または負の値	400 を返します。
> 100	サイレントに 100 を上限とします (HTTP 200、エラーなし)。has_more は、追加のレコードが残っているかどうかを示します。

limit > 100 を渡しても 400 は返されません。API はサイレントにページを 100 レコードに制限します。limit=500 を設定するコードは、エラーなしで最初の 100 件のみを受け取ります。残りのレコードをページングするには、after_id を使用してください。

# データが存在するかどうかを確認するために単一レコードをフェッチ
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

空の結果

利用可能なデータがない場合、またはリストの末尾に達した場合：

{
  "data": [],
  "first_id": null,
  "last_id": null,
  "has_more": false
}

注意事項

1. カーソルの安定性 — カーソルはリソース ID に基づいているため、並行書き込みによって重複やスキップが発生することはありません。
2. ソート順 — デフォルトでは、レコードは作成日時の降順 (新しいものから順) で返されます。
3. 削除されたリソース — 削除されたリソースの ID をカーソルとして使用すると、400 が返される場合があります。
4. 並行ページング — ページングは、複数のクライアントから並行して安全に実行できます。