Paginação - Qoder CN Series: Central de Documentação do Alibaba Cloud

Especificação de paginação baseada em cursor e exemplos de iteração para endpoints de lista da API do Qoder Cloud Agents.

Os endpoints de lista da API do Qoder Cloud Agents usam paginação baseada em cursor. Passe o valor next_page da resposta anterior como parâmetro page na próxima requisição. Os cursores permanecem estáveis mesmo quando os dados mudam.

Parâmetros da requisição

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
`limit`	integer	Não	20	Quantidade de itens por página, intervalo de 1 a 100
`page`	string	Não	—	Cursor opaco retornado por `next_page` na resposta anterior
`before_id`	string	Não	—	Cursor de compatibilidade: retorna registros anteriores a este ID
`after_id`	string	Não	—	Cursor de compatibilidade: retorna registros posteriores a este ID

Os parâmetros page, before_id e after_id são mutuamente exclusivos. Enviar múltiplos cursores simultaneamente resulta no erro 400 invalid_request_error.

Estrutura da resposta

Todos os endpoints de lista retornam um envelope de paginação unificado:

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

Descrição dos campos

Campo	Tipo	Descrição
`data`	array	Recursos da página atual
`next_page`	string \	null	Cursor opaco para a próxima página. Passe-o como parâmetro `page` na próxima requisição
`first_id`	string \	null	ID do primeiro registro na página atual
`last_id`	string \	null	ID do último registro na página atual
`has_more`	boolean	Indica se há mais dados disponíveis

Uso básico

Obter a primeira página

# Get the first 10 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10" \
  -H "Authorization: Bearer $QODER_PAT"

Obter a próxima página

Use o valor next_page da resposta anterior como page:

# Get the next 10 Agents
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&page=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

Cursores de compatibilidade

Alguns endpoints também aceitam before_id e after_id como cursores de compatibilidade baseados em ID:

# Get the 10 records after agent_def456
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=10&after_id=agent_def456" \
  -H "Authorization: Bearer $QODER_PAT"

Exemplo completo de iteração

O script a seguir itera sobre todos os Agents:

#!/bin/bash
# Iterate over all Agents and print names
BASE_URL="https://api.qoder.com.cn/api/v1/cloud"
next_page=""
page_num=1

while true; do
  # Build URL
  url="$BASE_URL/agents?limit=50"
  if [ -n "$next_page" ]; then
    url="$url&page=$next_page"
  fi

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

  # Parse response
  count=$(echo "$response" | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['data']))")
  next_page=$(echo "$response" | python3 -c "import sys,json; print(json.load(sys.stdin).get('next_page') or '')")

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

  if [ -z "$next_page" ]; then
    break
  fi

  page_num=$((page_num + 1))

  # Delay between requests to avoid throttling
  sleep 0.1
done

echo "Done"

Comportamento do parâmetro limit

Valor	Comportamento
Omitido	Assume o padrão de 20 registros
1	Valor mínimo, retorna 1 registro
100	Valor máximo, retorna 100 registros
0 ou negativo	Retorna 400 `invalid_request_error` com a mensagem `Field 'limit' must be a positive integer.`
> 100	Retorna 400 `invalid_request_error` com a mensagem `limit exceeds maximum of 100`

Enviar limit > 100 retorna 400. Se precisar de mais dados, defina limit=100 e pagine usando page.

# Fetch only 1 record to check whether data exists
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=1" \
  -H "Authorization: Bearer $QODER_PAT"

Resultados vazios

Quando não há dados disponíveis ou o fim da lista é atingido:

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

Observações

Estabilidade do cursor — page é um cursor opaco; reenvie-o exatamente como recebido na resposta
Ordem de classificação — os registros retornam em ordem decrescente de criação por padrão (mais recentes primeiro)
Cursores de compatibilidade — before_id e after_id funcionam como cursores de compatibilidade baseados em ID
Segurança em concorrência — múltiplos clientes podem paginar simultaneamente com segurança