Paginazione e raccolta di grandi dataset
Gestione della paginazione, pattern next_cursor, limitazione della frequenza con time.sleep e barre di avanzamento.
Paginazione e raccolta di grandi dataset è una lezione Learn AI with Python gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento Learn AI with Python, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso Learn AI with Python include 4 lezioni in totale.
Perché esiste la paginazione
Le API raramente restituiscono milioni di record in un'unica risposta. Suddividono i risultati in pagine, così ogni risposta rimane piccola e veloce.
Per raccogliere un dataset completo è necessario scorrere tutte le pagine e combinare i risultati. Questa lezione tratta gli stili di paginazione più comuni, oltre alla limitazione della frequenza e al monitoraggio dell'avanzamento.
Paginazione basata sul numero di pagina
Lo schema più semplice utilizza un parametro page. Lo incrementi finché l'API non restituisce una pagina vuota.
import requests
all_items = []
page = 1
while True:
resp = requests.get(url, params={"page": page, "per_page": 100}, timeout=10)
resp.raise_for_status()
items = resp.json()
if not items:
break
all_items.extend(items)
page += 1
print(len(all_items), "items collected")Paginazione con cursore o URL successivo
Molte API moderne restituiscono un URL successivo o un token cursore che indica la pagina seguente. Continui finché esiste un collegamento successivo.
È un approccio robusto perché è il server a stabilire da dove inizia la pagina seguente.
all_items = []
next_url = "https://api.example.com/items?limit=100"
while next_url:
resp = requests.get(next_url, timeout=10)
resp.raise_for_status()
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next") # None when no more pages
print(len(all_items))Rispettare i limiti di frequenza con time.sleep
Le API limitano il numero di richieste che è possibile inviare ogni secondo o ogni minuto. Inviarle in rapida successione restituisce 429 Too Many Requests oppure può causare il blocco dell'accesso.
Inserisca un breve time.sleep tra le richieste per mantenere un comportamento corretto e restare sotto il limite.
import time
while next_url:
resp = requests.get(next_url, timeout=10)
resp.raise_for_status()
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next")
time.sleep(0.5) # 2 requests per secondLeggere gli header dei limiti di frequenza
Le API ben progettate indicano la quota residua negli header, ad esempio X-RateLimit-Remaining e X-RateLimit-Reset.
Può leggerli per rallentare solo quando si avvicina al limite, invece di inserire sempre un'attesa.
remaining = int(resp.headers.get("X-RateLimit-Remaining", 1))
if remaining < 5:
reset = int(resp.headers.get("X-RateLimit-Reset", 1))
print("Near limit, sleeping", reset, "s")
time.sleep(reset)Gestire 429 con il backoff
Se riceve un 429, la risposta spesso include un header Retry-After che indica per quanto tempo attendere. Rispetti questo intervallo prima di riprovare.
resp = requests.get(url, timeout=10)
if resp.status_code == 429:
wait = int(resp.headers.get("Retry-After", 5))
time.sleep(wait)
resp = requests.get(url, timeout=10) # retry onceBarre di avanzamento con tqdm
I processi di raccolta lunghi sembrano bloccati se non forniscono alcun feedback. tqdm racchiude qualsiasi iterabile e mostra una barra di avanzamento aggiornata con velocità e tempo stimato.
from tqdm import tqdm
for page in tqdm(range(1, 101), desc="Fetching"):
resp = requests.get(url, params={"page": page}, timeout=10)
all_items.extend(resp.json())
time.sleep(0.2)tqdm con totali sconosciuti
Con la paginazione tramite cursore il numero totale di elementi non è noto in anticipo. Utilizzi tqdm come contatore manuale e chiami update() a ogni ciclo.
from tqdm import tqdm
pbar = tqdm(desc="Pages")
while next_url:
resp = requests.get(next_url, timeout=10)
data = resp.json()
all_items.extend(data["results"])
next_url = data.get("next")
pbar.update(1)
pbar.close()Raccolta incrementale
Per dataset enormi, non conservi tutto in memoria. La raccolta incrementale scrive ogni pagina su disco man mano che arriva, così un arresto anomalo non fa perdere tutti i progressi.
import json
with open("items.jsonl", "w") as f:
while next_url:
resp = requests.get(next_url, timeout=10)
data = resp.json()
for item in data["results"]:
f.write(json.dumps(item) + "\n")
next_url = data.get("next")Raccolta riprendibile
Salvi l'ultimo cursore o numero di pagina, così una nuova esecuzione può riprendere dal punto raggiunto invece di ricominciare da capo. In questo modo i processi lunghi sono tolleranti ai guasti.
import os
start_page = 1
if os.path.exists("checkpoint.txt"):
start_page = int(open("checkpoint.txt").read()) + 1
for page in range(start_page, 1000):
# ... fetch and store ...
open("checkpoint.txt", "w").write(str(page))Mettere tutto insieme
Un ciclo di raccolta pronto per la produzione combina tutti gli elementi: esegue la paginazione, attende per rispettare i limiti di frequenza, mostra l'avanzamento, scrive in modo incrementale e salva punti di controllo.
from tqdm import tqdm
import time, json
with open("out.jsonl", "a") as f:
next_url = "https://api.example.com/items?limit=100"
pbar = tqdm(desc="Pages")
while next_url:
r = requests.get(next_url, timeout=10)
r.raise_for_status()
d = r.json()
for it in d["results"]:
f.write(json.dumps(it) + "\n")
next_url = d.get("next")
pbar.update(1)
time.sleep(0.3)Controllo rapido: paginazione tramite cursore
Un'API restituisce un campo "next" contenente un URL oppure None nell'ultima pagina.
Riepilogo: raccogliere dataset di grandi dimensioni
Ora può raccogliere dataset distribuiti su molte pagine:
- paginazione basata sul numero di pagina e sul cursore (
while next_url) time.sleepe header dei limiti di frequenza per evitare i 429- backoff con
Retry-Afterin caso di limitazione - barre di avanzamento
tqdmper i processi lunghi - scrittura incrementale e riprendibile per tollerare i guasti
Prossimo argomento: salvare in modo efficiente i dati raccolti.
Domande Frequenti
La lezione «Paginazione e raccolta di grandi dataset» è gratuita?
Sì — il testo completo di «Paginazione e raccolta di grandi dataset» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso Learn AI with Python, passa a CoddyKit PRO. Il corso Learn AI with Python include 4 lezioni in totale.
Cosa imparerò in «Paginazione e raccolta di grandi dataset»?
Gestione della paginazione, pattern next_cursor, limitazione della frequenza con time.sleep e barre di avanzamento. Eserciti Learn AI with Python con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare Learn AI with Python?
Non è richiesta alcuna esperienza precedente. Learn AI with Python su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Paginazione e raccolta di grandi dataset»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione Learn AI with Python?
Sì. Ogni lezione Learn AI with Python include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Fondamenti delle API REST per la raccolta dei dati
- Paginazione e raccolta di grandi dataset
- Archiviazione efficiente dei dati raccolti
- Utilizzo delle API pubbliche per i dati