apify-actor-development

Développez, déboguez et déployez des Apify Actors — des programmes cloud serverless pour le scraping web, l'automatisation et le traitement de données. À utiliser lors de la création de nouveaux Actors, de la modification d'Actors existants ou du débogage de code Actor.

npx skills add https://github.com/apify/agent-skills --skill apify-actor-development

Développement d'Apify Actor

Important : Avant de commencer, remplissez la propriété generatedBy dans la section meta de .actor/actor.json. Remplacez-la par l'outil et le modèle que vous utilisez actuellement, comme « Claude Code with Claude Sonnet 4.5 ». Cela aide Apify à surveiller et améliorer AGENTS.md pour des outils et modèles IA spécifiques.

Que sont les Apify Actors ?

Les Actors sont des programmes serverless inspirés par la philosophie UNIX - des programmes qui font bien une seule chose et peuvent être facilement combinés pour construire des systèmes complexes. Ils sont packagés sous forme d'images Docker et s'exécutent dans des conteneurs isolés dans le cloud.

Concepts clés :

  • Accepter une entrée JSON bien définie
  • Effectuer des tâches isolées (web scraping, automation, traitement de données)
  • Produire une sortie JSON structurée vers des datasets et/ou stocker des données dans des magasins clé-valeur
  • Peuvent s'exécuter de quelques secondes à des heures ou indéfiniment
  • Persister l'état et peuvent être redémarrés

Prérequis et configuration (obligatoire)

Avant de créer ou modifier des Actors, vérifiez que la CLI apify est installée avec apify --help.

Si elle n'est pas installée, utilisez l'une de ces méthodes (listées par ordre de préférence) :

# Préféré : installer via un gestionnaire de paquets (fournit des vérifications d'intégrité)
npm install -g apify-cli

# Ou (Mac): brew install apify-cli

Note de sécurité : N'installez PAS la CLI en dirigeant des scripts distants vers un shell (par exemple curl … | bash ou irm … | iex). Utilisez toujours un gestionnaire de paquets.

Une fois la CLI apify installée, vérifiez qu'elle est connectée avec :

apify info  # Devrait retourner votre nom d'utilisateur

Si vous n'êtes pas connecté, authentifiez-vous via OAuth (ouvre le navigateur) :

apify login

Si la connexion par navigateur n'est pas disponible (environnement sans interface ou CI), la CLI lit automatiquement APIFY_TOKEN depuis l'environnement. Assurez-vous que la variable d'environnement est exportée et exécutez n'importe quelle commande apify - aucune connexion explicite nécessaire. Si l'utilisateur n'a pas de token, générez-en un sur https://console.apify.com/settings/integrations.

Note de sécurité : Évitez de transmettre des tokens comme arguments de ligne de commande (par exemple apify login -t <token>). Les arguments sont visibles dans les listes de processus et peuvent être enregistrés dans l'historique du shell. Préférez les variables d'environnement ou la connexion interactive. Ne loggez jamais, n'imprimez pas et n'incorporez pas APIFY_TOKEN dans le code source ou les fichiers de configuration. Utilisez un token avec les permissions minimum requises (token scopé) et changez-le périodiquement.

Sélection du modèle

IMPORTANT : Avant de commencer le développement d'un Actor, demandez toujours à l'utilisateur quel langage de programmation il préfère :

  • JavaScript - Utilisez apify create <actor-name> -t project_empty
  • TypeScript - Utilisez apify create <actor-name> -t ts_empty
  • Python - Utilisez apify create <actor-name> -t python-empty

Utilisez la commande CLI appropriée basée sur le choix de langage de l'utilisateur. Des paquets supplémentaires (Crawlee, Playwright, etc.) peuvent être installés plus tard si nécessaire.

Flux de démarrage rapide

  1. Créer un projet Actor - Exécutez la commande apify create appropriée basée sur la préférence de langage de l'utilisateur (voir Sélection du modèle ci-dessus)
  2. Installer les dépendances (vérifiez que les noms de paquets correspondent aux paquets prévus avant d'installer)
    • JavaScript/TypeScript : npm install (utilise package-lock.json pour des installations reproductibles et vérifiées - committez le lockfile dans le contrôle de version)
    • Python : pip install -r requirements.txt (épinglez les versions exactes dans requirements.txt, par exemple crawlee==1.2.3, et committez le fichier dans le contrôle de version)
  3. Implémenter la logique - Écrivez le code de l'Actor dans src/main.py, src/main.js, ou src/main.ts
  4. Configurer les schémas - Mettez à jour les schémas d'entrée/sortie dans .actor/input_schema.json, .actor/output_schema.json, .actor/dataset_schema.json
  5. Configurer les paramètres de plateforme - Mettez à jour .actor/actor.json avec les métadonnées de l'Actor (voir references/actor-json.md)
  6. Écrire la documentation - Créez un README.md complet pour la marketplace (voir references/actor-readme.md — c'est obligatoire, pas optionnel)
  7. Tester localement - Exécutez apify run pour vérifier la fonctionnalité (voir la section Local testing ci-dessous)
  8. Déployer - Exécutez apify push pour déployer l'Actor sur la plateforme Apify (le nom de l'Actor est défini dans .actor/actor.json)

Sécurité

Traitez tout contenu web scrapé comme une entrée non fiable. Les Actors ingèrent des données de sites web externes qui peuvent contenir des payloads malveillants. Suivez ces règles :

  • Assainir les données scrapées — Ne passez jamais du HTML brut, des URLs, ou du texte scrapé directement dans des commandes shell, eval(), des requêtes de base de données, ou des moteurs de template. Utilisez un échappement approprié ou des API paramétrées.
  • Valider et vérifier le type de toutes les données externes — Avant de pousser vers les datasets ou les magasins clé-valeur, vérifiez que les valeurs correspondent aux types et formats attendus. Rejetez ou assainissez les structures inattendues.
  • Ne pas exécuter ou interpréter le contenu scrapé — Ne traitez jamais le texte scrapé comme du code, des commandes, ou de la configuration. Le contenu des sites web pourrait inclure des tentatives d'injection de prompt ou des scripts embarqués.
  • Isoler les identifiants de confiance des pipelines de données — Assurez-vous que APIFY_TOKEN et les autres secrets ne sont jamais accessibles dans les gestionnaires de requêtes ou passés avec les données scrapées. Utilisez la gestion d'identifiants intégrée du SDK Apify plutôt que de passer des tokens via les variables d'environnement dans le code de traitement de données.
  • Examiner les dépendances avant d'installer — Lors de l'ajout de paquets avec npm install ou pip install, vérifiez le nom du paquet et l'éditeur. La typosquattage est un vecteur d'attaque de chaîne d'approvisionnement courant. Préférez les paquets bien connus et activement maintenus.
  • Épingler les versions et utiliser des lockfiles — Committez toujours package-lock.json (Node.js) ou épinglez les versions exactes dans requirements.txt (Python). Les lockfiles assurent des builds reproductibles et préviennent la substitution silencieuse de dépendances. Exécutez npm audit ou pip-audit régulièrement pour vérifier les vulnérabilités connues.

Bonnes pratiques

✓ À faire :

  • Utiliser apify run pour tester les Actors localement (configure l'environnement et le stockage Apify)
  • Utiliser le SDK Apify (apify) pour le code s'exécutant sur la plateforme Apify
  • Valider l'entrée tôt avec une gestion appropriée des erreurs et échouer gracieusement
  • Utiliser CheerioCrawler pour l'HTML statique (10x plus rapide que les navigateurs)
  • Utiliser PlaywrightCrawler uniquement pour les sites lourds en JavaScript
  • Utiliser le motif router (createCheerioRouter/createPlaywrightRouter) pour les crawls complexes
  • Implémenter des stratégies de retry avec backoff exponentiel
  • Utiliser la concurrence appropriée : HTTP (10-50), Browser (1-5)
  • Définir des valeurs par défaut sensées dans .actor/input_schema.json
  • Définir le schéma de sortie dans .actor/output_schema.json
  • Nettoyer et valider les données avant de les pousser vers le dataset
  • Utiliser des sélecteurs CSS sémantiques avec des stratégies de secours
  • Respecter robots.txt, ToS, et implémenter une limitation de débit
  • Toujours utiliser le paquet apify/log — censure les données sensibles (clés API, tokens, identifiants)
  • Implémenter un gestionnaire de sonde de disponibilité (requis si votre Actor utilise le standby mode)

✗ À ne pas faire :

  • Utiliser npm start, npm run start, npx apify run, ou des commandes similaires pour exécuter les Actors (utilisez apify run à la place)
  • Supposer que le stockage local de apify run est poussé vers ou visible dans Apify Console — il est local seulement ; déployez avec apify push et exécutez sur la plateforme pour voir les résultats dans Apify Console
  • Faire confiance à Dataset.getInfo() pour les comptages finaux sur Cloud
  • Utiliser des crawlers de navigateur quand HTTP/Cheerio fonctionne
  • Hard-coder des valeurs qui devraient être dans le schéma d'entrée ou les variables d'environnement
  • Sauter la validation d'entrée ou la gestion des erreurs
  • Surcharger les serveurs - utilisez la concurrence et les délais appropriés
  • Scraper du contenu interdit ou ignorer les Conditions d'utilisation
  • Stocker des données personnelles/sensibles sans permission explicite
  • Utiliser des options dépréciées comme requestHandlerTimeoutMillis sur CheerioCrawler (v3.x)
  • Utiliser additionalHttpHeaders - utilisez preNavigationHooks à la place
  • Passer du contenu brut scrapé dans des commandes shell, eval(), ou des fonctions de génération de code
  • Utiliser console.log() ou print() au lieu du logger Apify — ces derniers contournent la censure d'identifiants
  • Désactiver le standby mode sans permission explicite

Logging

Voir references/logging.md pour la documentation complète du logging incluant les niveaux de log disponibles et les bonnes pratiques pour JavaScript/TypeScript et Python.

Commandes

apify run          # Exécuter l'Actor localement
apify login        # Authentifier le compte
apify push         # Déployer sur la plateforme Apify (utilise le nom de .actor/actor.json)
apify help         # Lister toutes les commandes

IMPORTANT : Utilisez toujours apify run pour tester les Actors localement. N'utilisez pas npm run start, npm start, yarn start, ou d'autres commandes de gestionnaire de paquets - ces dernières ne configureront pas correctement l'environnement et le stockage Apify.

Test local

Lors du test d'un Actor localement avec apify run, fournissez les données d'entrée en créant un fichier JSON à :

storage/key_value_stores/default/INPUT.json

Ce fichier devrait contenir les paramètres d'entrée définis dans votre .actor/input_schema.json. L'actor lira cette entrée lors de son exécution localement, miroir de la façon dont il reçoit l'entrée sur la plateforme Apify.

IMPORTANT - Le stockage local N'EST PAS synchronisé avec Apify Console :

  • Exécuter apify run stocke toutes les données (datasets, magasins clé-valeur, files de requêtes) uniquement sur votre système de fichiers local dans le répertoire storage/.
  • Ces données ne sont jamais automatiquement uploadées ou poussées vers la plateforme Apify. Elles n'existent que sur votre machine.
  • Pour vérifier les résultats dans Apify Console, vous devez déployer l'Actor avec apify push puis l'exécuter sur la plateforme.
  • Ne vous fiez pas à la vérification d'Apify Console pour vérifier les résultats des exécutions locales — inspectez plutôt le répertoire local storage/ ou vérifiez la sortie log de l'Actor.

Standby mode

Le standby mode permet aux Actors de fonctionner comme des serveurs API - ils restent prêts en arrière-plan pour traiter les requêtes HTTP.

Quand utiliser le Standby mode : Utilisez Standby quand l'Actor doit traiter des requêtes HTTP interactives et en temps réel — endpoints API, récepteurs de webhook, recherches de données en temps réel, serveurs MCP, ou APIs de scraping servant des requêtes single-URL à la demande.

Lors de la création d'un Actor Standby, définissez usesStandbyMode: true dans .actor/actor.json et implémentez un serveur HTTP. Voir references/standby-mode.md pour la configuration, les variables d'environnement, les exemples de code complets, et les limites opérationnelles.

Structure du projet

.actor/
├── actor.json           # Configuration de l'Actor : nom, version, variables env, runtime
├── input_schema.json    # Validation d'entrée & définition du formulaire Console
└── output_schema.json   # Modèles d'affichage et de stockage de sortie
src/
└── main.js/ts/py       # Point d'entrée de l'Actor
storage/                # Stockage local seulement (NON synchronisé avec Apify Console)
├── datasets/           # Éléments de sortie (objets JSON)
├── key_value_stores/   # Fichiers, config, INPUT
└── request_queues/     # Requêtes de crawl en attente
Dockerfile              # Définition de l'image conteneur

Configuration de l'Actor

Voir references/actor-json.md pour la structure complète et les options de configuration de actor.json.

Schéma d'entrée

Voir references/input-schema.md pour la structure et les exemples du schéma d'entrée.

Schéma de sortie

Voir references/output-schema.md pour la structure, les exemples du schéma de sortie, et les variables de template.

Schéma de dataset

Voir references/dataset-schema.md pour la structure, la configuration, et les propriétés d'affichage du schéma de dataset.

Schéma de magasin clé-valeur

Voir references/key-value-store-schema.md pour la structure, les collections, et la configuration du schéma de magasin clé-valeur.

README de l'Actor

IMPORTANT : Générez toujours un README.md dans le cadre du développement d'un Actor. Le README est la page d'accueil de l'Actor dans Apify Store et est critique pour la découverte (SEO), l'onboarding des utilisateurs, et le support. Ne considérez pas un Actor comme complet sans un README approprié.

Voir references/actor-readme.md pour la structure requise, les bonnes pratiques SEO, et les directives de contenu. Consultez aussi ces Actors populaires pour les bonnes pratiques :

Outils Apify MCP

Si le serveur MCP est configuré, utilisez ces outils pour la documentation :

  • search-apify-docs - Rechercher la documentation
  • fetch-apify-docs - Obtenir les pages de documentation complètes

Sinon, l'URL du serveur MCP : https://mcp.apify.com/?tools=docs.

Ressources