Comment extraire des données avec le Crawlbase Crawlerla méthode asynchrone basée sur le push pour scraper en volume

La plupart des tutoriels de scraping vous montrent comment récupérer une page et l'analyser sur place. Cette boucle synchrone fonctionne bien jusqu'à ce que vous ayez besoin de milliers de pages, moment auquel votre script passe sa vie à attendre : soumettre une URL, bloquer jusqu'au retour de la réponse, analyser, recommencer. Les nouvelles tentatives, les files d'attente, la rotation des proxies et le rendu s'accumulent tous sur le même thread, et une cible lente bloque toute l'exécution. À grande échelle, vous voulez une forme tout à fait différente.

Ce guide vous explique comment extraire des données à l'aide du Crawlbase Crawler, le produit asynchrone basé sur le push, conçu pour les travaux en volume. Au lieu d'attendre chaque requête, vous poussez un lot d'URL vers le Crawler qui les crawle à grande échelle sur sa propre infrastructure, puis livre chaque résultat terminé à un endpoint webhook que vous contrôlez. La soumission et la récupération sont découplées, votre code n'est donc jamais bloqué en attendant une page. À la fin, vous aurez un serveur de callback fonctionnel, un crawler nommé et un script qui pousse des URL et reçoit des données analysées de l'autre côté.

Synchrone vs asynchrone : choisissez le bon outil

Crawlbase vous offre deux façons de récupérer une page, et la différence porte sur le timing, pas sur la capacité. La Crawling API est synchrone : vous envoyez une requête, vous attendez, le HTML rendu revient dans la même réponse. Elle est parfaite quand vous avez besoin d'une page immédiatement et voulez le résultat en ligne.

Le Crawler est la couche asynchrone construite au-dessus du même moteur. Vous poussez une URL et récupérez immédiatement un accusé de réception avec un identifiant de requête, rien de plus. Le crawl réel se produit en arrière-plan sur les serveurs Crawlbase, et quand une page est prête, le résultat est POSTé à votre URL de callback. Vous ne gardez jamais une connexion ouverte, vous pouvez donc envoyer des milliers d'URL en secondes et laisser les résultats affluer vers votre endpoint au fur et à mesure qu'ils se terminent.

Comment fonctionne le modèle push

Le flux comporte trois éléments mobiles et il est utile de tous les trois avoir en tête avant d'écrire du code.

Premièrement, un crawler : une configuration nommée que vous créez une fois dans le tableau de bord. Elle lie une URL de callback à un type de requête (normale ou JavaScript) pour que le moteur sache où livrer les résultats et comment rendre. Deuxièmement, la requête push : vous appelez l'API avec votre token, l'URL cible et le nom de votre crawler, et il retourne un accusé de réception JSON contenant un identifiant de requête unique (le RID). Troisièmement, le callback : quand la page est crawlée, Crawlbase envoie un HTTP POST à votre URL de callback avec le contenu de la page et le même RID, pour que vous puissiez faire correspondre chaque livraison à l'URL que vous avez soumise.

Votre endpoint de callback doit remplir deux conditions. Il doit être publiquement accessible par les serveurs Crawlbase, et il doit répondre rapidement : répondre au POST en quelques centaines de millisecondes avec un statut 200, 201 ou 204. Le contenu arrive compressé GZIP et, par défaut, en HTML ; vous pouvez demander du JSON analysé à la place en définissant le format sur la requête. Comme le travail est asynchrone, votre rôle côté réception est simplement d'accuser réception rapidement et de transmettre le payload à une file d'attente ou une base de données, pas d'effectuer un traitement lourd en ligne.

Ce que vous allez construire

Un aller-retour complet en Python. Vous mettrez en place un petit webhook Flask qui reçoit les pages crawlées, l'exposez à Internet pour que Crawlbase puisse l'atteindre, créez un crawler nommé dans le tableau de bord pointé sur cette URL publique, et enfin poussez des URL cibles à l'aide du client officiel crawlbase. Nous utiliserons des pages de test publiques pour que vous puissiez exécuter chaque étape avant de pointer sur des cibles réelles.

Configurer l'environnement

Vous avez besoin de Python 3.8 ou ultérieur. Confirmez votre version, créez un environnement virtuel pour que les dépendances restent isolées, puis installez les deux bibliothèques : Flask pour le serveur webhook et le client Crawlbase officiel pour pousser des requêtes.

python --version

python -m venv crawler_env
source crawler_env/bin/activate

pip install flask crawlbase

Sur Windows, activez l'environnement avec crawler_env\Scripts\activate à la place de la ligne source. Vous aurez également besoin de votre token Crawlbase depuis le tableau de bord. Crawlbase propose deux types de tokens : le token normal pour les récupérations HTTP simples et le token JavaScript pour les pages qui rendent le contenu côté client dans un vrai navigateur. Choisissez celui qui correspond aux sites que vous ciblez ; la plupart des pages modernes ont besoin du token JavaScript.

Étape 1 : Construire le webhook qui reçoit les données crawlées

L'endpoint de callback est là où les pages terminées arrivent. Créez un fichier appelé webhook.py. Le gestionnaire lit le corps POST, enregistre le RID pour que vous puissiez le corréler à la réponse push, et retourne 200 immédiatement. Flask décompresse le corps GZIP pour vous, donc le contenu est du texte simple quand vous le lisez.

from flask import Flask, request

app = Flask(__name__)

@app.route("/crawlbase", methods=["POST"])
def webhook():
    rid = request.headers.get("rid")
    original_url = request.headers.get("original_url")
    body = request.get_data(as_text=True)

    print(f"Received RID {rid} for {original_url}")
    print(f"Payload size: {len(body)} bytes")

    # Hand the payload to a queue or database here; keep this fast.
    return "", 200

if __name__ == "__main__":
    app.run(port=3000)

Quelques détails importants ici. Crawlbase envoie l'identifiant de requête dans un en-tête rid et l'URL crawlée dans original_url, vous n'avez donc jamais à deviner à quelle soumission appartient une livraison. Le gestionnaire n'effectue pas de travail lourd : il accuse réception et retourne. La fenêtre de réponse de deux cents millisecondes est stricte, donc tout ce qui est lent (analyse, écriture dans un store lent, appel d'un autre service) appartient à une file d'attente en arrière-plan, pas à l'intérieur de la requête. Lancez le serveur et laissez-le tourner dans son propre terminal.

python webhook.py

Étape 2 : Exposer le serveur local à Internet

Les serveurs Crawlbase doivent pouvoir atteindre votre callback, et un serveur sur localhost n'est pas accessible depuis l'extérieur. Pendant le développement, la solution la plus simple est un outil de tunneling comme ngrok, qui donne à votre port local une URL HTTPS publique. Avec le webhook toujours en cours d'exécution sur le port 3000, ouvrez un second terminal et démarrez le tunnel.

ngrok http 3000

ngrok affiche une URL de transfert publique, quelque chose comme https://random-id.ngrok-free.app. Votre URL de callback complète est cet hôte plus la route de l'application Flask, soit https://random-id.ngrok-free.app/crawlbase. Gardez ce terminal ouvert également ; l'URL change à chaque redémarrage du tunnel. En production, vous pointeriez le crawler vers un endpoint stable réel sur votre propre infrastructure.

Étape 3 : Créer un crawler dans le tableau de bord

Une requête push a besoin d'un crawler nommé pour que le moteur sache où livrer les résultats. Dans votre tableau de bord Crawlbase, accédez à la section Crawler et créez un nouveau crawler. Vous lui donnez un nom unique, collez votre URL de callback publique (l'URL ngrok plus /crawlbase), et choisissez le type de requête : normal pour le HTML simple ou JavaScript pour les pages rendues côté client. Enregistrez-le et le crawler apparaît dans votre liste, prêt à recevoir des pushs.

Le nom que vous choisissez est la valeur que vous passez sur chaque requête push, donc gardez-le simple et mémorable. Un schéma courant est un crawler par projet ou par source de données, chacun pointé vers une route que votre serveur peut distinguer.

Étape 4 : Pousser des URL vers le Crawler

Avec le webhook en direct, le tunnel ouvert et un crawler créé, vous êtes prêt à pousser. Le client officiel crawlbase encapsule l'API, donc un push est un seul appel get avec deux options supplémentaires : callback réglé sur true et crawler réglé sur le nom que vous avez enregistré. Créez un fichier appelé push.py.

from crawlbase import CrawlingAPI

api = CrawlingAPI({"token": "YOUR_CRAWLBASE_TOKEN"})

target = "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html"

response = api.get(target, {
    "callback": "true",
    "crawler": "my-crawler",
    "format": "json",
})

print(response["body"])

Exécutez-le avec python push.py. La réponse n'est pas le contenu de la page. C'est un accusé de réception immédiat avec l'identifiant de requête, ce qui est exactement ce que signifie asynchrone : l'appel retourne avant que le crawl ne se termine. Vous récupérez quelque chose comme ceci.

{ "rid": "e2bbac4e7ea9a4c4be57d2a4" }

Une seconde ou deux plus tard, la page crawlée arrive à votre webhook. Vérifiez le terminal exécutant webhook.py et vous verrez le même RID affiché, confirmant que le circuit est bouclé : le moteur a crawlé la page en arrière-plan et POSTé le résultat terminé à votre callback. Régler format sur json lors du push signifie que le payload livré est du JSON analysé plutôt que du HTML brut, ce qui est généralement ce que vous voulez pour le traitement en aval.

Pousser en volume

Une URL prouve le câblage ; le but du Crawler est le volume. Pousser une liste est juste une boucle, et parce que chaque appel retourne immédiatement, vous pouvez soumettre un grand lot en secondes sans attendre aucun crawl individuel. Le Crawler a une file d'attente push généreuse, vous continuez donc à l'alimenter et laissez les résultats arriver au webhook selon leur propre calendrier.

from crawlbase import CrawlingAPI

api = CrawlingAPI({"token": "YOUR_CRAWLBASE_TOKEN"})

urls = [
    "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    "https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html",
    "https://books.toscrape.com/catalogue/soumission_998/index.html",
]

for url in urls:
    response = api.get(url, {
        "callback": "true",
        "crawler": "my-crawler",
        "format": "json",
    })
    print(f"Pushed {url} -> {response['body']}")

Chaque itération retourne son propre RID, et votre webhook reçoit un POST séparé par URL au fur et à mesure que chaque crawl se termine. Stockez la liste des RID côté push et réconciliez-la avec les livraisons côté callback pour que vous puissiez repérer tout ce qui n'est jamais revenu et le repousser. Cette boucle de réconciliation est l'épine dorsale d'un pipeline en volume fiable, et elle s'intègre naturellement dans un pipeline de données web évolutif plus grand.

Valider et utiliser les données récoltées

Recevoir des données n'est pas la même chose que leur faire confiance. Avant que le payload n'atteigne votre entrepôt, validez-le côté callback : confirmez que le RID correspond à un que vous avez poussé, vérifiez le code de statut que Crawlbase rapporte pour le crawl, et vérifiez que les champs attendus sont présents et non vides. Une page peut revenir avec succès au niveau HTTP alors qu'une refonte ou un blocage doux laisse le contenu qui vous importe manquant, donc une vérification rapide du schéma détecte tôt les lacunes silencieuses.

Une fois validées, les données récoltées alimentent les besoins métier habituels : surveillance des prix et des stocks chez les concurrents, enrichissement de leads et de contacts, recherche de marché et de sentiment, jeux d'entraînement pour des modèles, ou maintien d'un catalogue interne synchronisé avec des sources externes. Parce que le Crawler livre les résultats en continu plutôt qu'en un seul lot bloquant, il s'intègre naturellement dans les pipelines de streaming et incrémentaux où de nouvelles données arrivent dès que chaque page est crawlée. Pour plus d'informations sur l'obtention de résultats propres en volume, voir comment scraper des sites web sans être bloqué.

Si vous préférez acheminer votre propre trafic au lieu d'utiliser le modèle push, le Smart AI Proxy vous offre les mêmes IP résidentielles rotatives comme endpoint, et la Crawling API retourne du JSON pré-analysé pour les sites pris en charge quand vous voulez des champs structurés sans gérer l'analyse vous-même.

Foire aux questions

Quelle est la différence entre le Crawler et la Crawling API ?

La Crawling API est synchrone : vous envoyez une requête et la page rendue revient dans la même réponse, ce qui est idéal pour les récupérations interactives ponctuelles. Le Crawler est la couche asynchrone au-dessus du même moteur : vous poussez une URL, obtenez un identifiant de requête immédiat, et la page terminée est livrée plus tard à votre webhook. Utilisez la Crawling API pour les résultats en ligne et le Crawler pour les travaux en volume où bloquer sur chaque requête limiterait le débit.

Pourquoi mon webhook doit-il être publiquement accessible ?

Les serveurs Crawlbase livrent les pages crawlées en envoyant un HTTP POST à votre URL de callback, ils doivent donc pouvoir l'atteindre via Internet. Un serveur sur localhost est invisible depuis l'extérieur de votre machine, c'est pourquoi vous l'exposez pendant le développement avec un outil de tunneling comme ngrok. En production, vous hébergez le webhook sur un service avec une URL publique stable.

Que retourne la requête push ?

Elle retourne un petit accusé de réception JSON contenant un identifiant de requête unique, le RID, pas le contenu de la page. C'est le contrat asynchrone : l'appel retourne immédiatement pendant que le crawl s'exécute en arrière-plan. La page réelle arrive plus tard à votre webhook, portant le même RID dans ses en-têtes pour que vous puissiez faire correspondre chaque livraison à l'URL que vous avez soumise.

À quelle vitesse mon callback doit-il répondre ?

En environ 200 millisecondes, avec un code de statut 200, 201 ou 204. Crawlbase attend un accusé de réception rapide, votre gestionnaire doit donc lire le payload, le transmettre à une file d'attente ou une base de données, et retourner. Tout ce qui est lent, comme l'analyse ou l'écriture dans un store lent, appartient à un worker en arrière-plan plutôt qu'à l'intérieur de la requête.

Puis-je recevoir du JSON analysé plutôt que du HTML brut ?

Oui. Par défaut le Crawler livre du HTML, mais vous pouvez régler le format sur JSON lors de la requête push, et le payload arrive analysé. Choisissez la forme que préfère votre code en aval ; JSON est généralement plus facile à utiliser pour l'extraction structurée, tandis que HTML est pratique quand vous voulez faire passer votre propre analyseur sur la page complète.

Comment rendre un crawl en volume fiable ?

Suivez le RID pour chaque URL que vous poussez et réconciliez cette liste avec les livraisons qui arrivent à votre webhook. Tout ce qui n'arrive jamais peut être repoussé. Côté réception, validez chaque payload en confirmant le RID, en vérifiant le statut de crawl rapporté, et en vous assurant que les champs attendus sont présents, pour qu'une réponse qui semble réussie mais avec un contenu manquant ne passe pas inaperçue.

AO

Alfrick Opidi

Développeur et rédacteur technique

Développeur et rédacteur technique indépendant ayant contribué des guides de web scraping et de crawling au blog Crawlbase.