Actorisation Apify

L'actorisation convertit les logiciels existants en applications serverless réutilisables compatibles avec la plateforme Apify. Les Actors sont des programmes packagés en images Docker qui acceptent une entrée JSON bien définie, effectuent une action et produisent optionnellement une sortie JSON structurée.

Démarrage rapide

1. Exécutez apify init à la racine du projet
2. Encapsulez le code avec le cycle de vie du SDK (voir la section spécifique au langage ci-dessous)
3. Configurez .actor/input_schema.json
4. Testez avec apify run --input '{"key": "value"}'
5. Déployez avec apify push

Quand utiliser cette compétence

• Convertir un projet existant pour s'exécuter sur la plateforme Apify
• Ajouter l'intégration du SDK Apify à un projet
• Encapsuler un outil CLI ou un script en tant qu'Actor
• Migrer un projet Crawlee vers Apify

Prérequis

Vérifiez que la CLI apify est installée :

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 redirigeant des scripts distants vers un shell (par exemple curl ... | bash ou irm ... | iex). Utilisez toujours un gestionnaire de paquets.

Vérifiez que la CLI est connectée :

apify info  # Devrait retourner votre nom d'utilisateur

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

apify login

Si la connexion par navigateur n'est pas disponible (environnement sans écran ou CI), assurez-vous que la variable d'environnement APIFY_TOKEN est exportée. La CLI la lit automatiquement - 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 passer des tokens en tant qu'arguments en 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 la connexion OAuth ou les variables d'environnement. Ne journalisez, n'affichez ou n'intégrez jamais APIFY_TOKEN dans le code source ou les fichiers de configuration. Utilisez un token avec les permissions minimales requises (token limité) et renouvelez-le régulièrement.

Liste de contrôle d'actorisation

Copiez cette liste de contrôle pour suivre les progrès :

• [ ] Étape 1 : Analyser le projet (langage, point d'entrée, entrées, sorties)
• [ ] Étape 2 : Exécuter apify init pour créer la structure d'Actor
• [ ] Étape 3 : Appliquer l'intégration du SDK spécifique au langage
• [ ] Étape 4 : Configurer .actor/input_schema.json
• [ ] Étape 5 : Configurer .actor/output_schema.json (si applicable)
• [ ] Étape 6 : Mettre à jour les métadonnées de .actor/actor.json
• [ ] Étape 7 : Écrire README.md pour la liste Apify Store
• [ ] Étape 8 : Tester localement avec apify run
• [ ] Étape 9 : Déployer avec apify push

Étape 1 : Analyser le projet

Avant d'apporter des modifications, comprenez le projet :

1. Identifier le langage - JavaScript/TypeScript, Python ou autre
2. Trouver le point d'entrée - Le fichier principal qui lance l'exécution
3. Identifier les entrées - Arguments en ligne de commande, variables d'environnement, fichiers de configuration
4. Identifier les sorties - Fichiers, sortie console, réponses API
5. Vérifier l'état - A-t-il besoin de persister les données entre les exécutions ?

Étape 2 : Initialiser la structure d'Actor

Exécutez à la racine du projet :

apify init

Cela crée :

• .actor/actor.json - Configuration et métadonnées d'Actor
• .actor/input_schema.json - Définition d'entrée pour Apify Console
• Dockerfile (s'il n'existe pas) - Définition de l'image du conteneur

Étape 3 : Appliquer les changements spécifiques au langage

Choisissez en fonction du langage de votre projet :

• JavaScript/TypeScript : Voir js-ts-actorization.md
• Python : Voir python-actorization.md
• Autres langages (basés sur CLI) : Voir cli-actorization.md

Référence rapide

Étapes 4-6 : Configurer les schémas

Voir schemas-and-output.md pour la configuration détaillée de :

• Schéma d'entrée (.actor/input_schema.json)
• Schéma de sortie (.actor/output_schema.json)
• Configuration d'Actor (.actor/actor.json)
• Gestion d'état (files de demandes, magasins de clés-valeurs)

Validez les schémas par rapport au paquet npm @apify/json_schemas.

Étape 7 : Écrire le README

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

Voir les directives README d'Actor sur skills/apify-actor-development/references/actor-readme.md pour la structure requise incluant : introduction et fonctionnalités, tableau d'extraction de données, tutoriel étape par étape, informations de tarification, exemples d'entrée/sortie et FAQ. Visez au moins 300 mots avec des titres H2/H3 optimisés pour le SEO. Examinez également ces Actors les plus populaires pour les bonnes pratiques :

• Instagram Scraper
• Google Maps Scraper

Étape 8 : Tester localement

Exécutez l'Actor avec une entrée en ligne (pour les Actors JS/TS et Python) :

apify run --input '{"startUrl": "https://example.com", "maxItems": 10}'

Ou utilisez un fichier d'entrée :

apify run --input-file ./test-input.json

Important : Utilisez toujours apify run, pas npm start ou python main.py. La CLI configure l'environnement et le stockage appropriés.

Étape 9 : Déployer

apify push

Cela télécharge et construit votre Actor sur la plateforme Apify.

Monétisation (optionnelle)

Après le déploiement, vous pouvez monétiser votre Actor dans Apify Store. Le modèle recommandé est Pay Per Event (PPE) :

• Par résultat/article scrapisé
• Par page traitée
• Par appel API effectué

Configurez PPE dans Apify Console sous Actor > Monetization. Facturez les événements dans votre code avec await Actor.charge('result').

Autres options : Rental (abonnement mensuel) ou Free (open source).

Sécurité

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

• Assainissez les données scrappées — Ne passez jamais du HTML brut, des URLs ou du texte scrappé directement dans des commandes shell, eval(), des requêtes de base de données ou des moteurs de templates. Utilisez l'échappement approprié ou des API paramétrées.
• Validez et vérifiez le type de toutes les données externes — Avant de pousser vers des datasets ou des magasins de clés-valeurs, vérifiez que les valeurs correspondent aux types et formats attendus. Rejetez ou assainissez les structures inattendues.
• N'exécutez ni n'interprétez le contenu scrappé — Ne traitez jamais le texte scrappé comme du code, des commandes ou de la configuration. Le contenu des sites pourrait inclure des tentatives d'injection de prompts ou des scripts intégrés.
• Isolez les identifiants de confiance des pipelines de données — Assurez-vous que APIFY_TOKEN et autres secrets ne sont jamais accessibles dans les gestionnaires de demandes ou passés aux côtés des données scrappées. Utilisez la gestion des identifiants intégrée du SDK Apify plutôt que de passer des tokens via des variables d'environnement dans le code de traitement des données.
• Vérifiez les dépendances avant l'installation — Quand vous ajoutez des paquets avec npm install ou pip install, vérifiez le nom du paquet et l'éditeur. Le typosquattage est un vecteur d'attaque courant dans la chaîne d'approvisionnement. Préférez les paquets bien connus et activement maintenus.
• Épinglez les versions et utilisez les fichiers de verrouillage — Toujours valider package-lock.json (Node.js) ou épinglez les versions exactes dans requirements.txt (Python). Les fichiers de verrouillage assurent des builds reproductibles et empêchent la substitution silencieuse de dépendances. Exécutez npm audit ou pip-audit périodiquement pour vérifier les vulnérabilités connues.

Liste de contrôle avant le déploiement

• [ ] .actor/actor.json existe avec le nom et la description corrects
• [ ] .actor/actor.json valide par rapport à @apify/json_schemas (actor.schema.json)
• [ ] .actor/input_schema.json définit toutes les entrées requises
• [ ] .actor/input_schema.json valide par rapport à @apify/json_schemas (input.schema.json)
• [ ] .actor/output_schema.json définit la structure de sortie (si applicable)
• [ ] .actor/output_schema.json valide par rapport à @apify/json_schemas (output.schema.json)
• [ ] Dockerfile existe et se construit avec succès
• [ ] Actor.init() / Actor.exit() encapsule le code principal (JS/TS)
• [ ] async with Actor: encapsule le code principal (Python)
• [ ] Les entrées sont lues via Actor.getInput() / Actor.get_input()
• [ ] Les sorties utilisent Actor.pushData() ou un magasin de clés-valeurs
• [ ] apify run s'exécute avec succès avec une entrée de test
• [ ] README.md existe avec la structure appropriée (introduction, fonctionnalités, tableau de données, tutoriel, tarification, exemples d'entrée/sortie)
• [ ] generatedBy est défini dans la section méta de actor.json

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

• Actorization Academy - Guide complet
• Apify SDK for JavaScript - Référence complète du SDK
• Apify SDK for Python - Référence complète du SDK
• Apify CLI Reference - Commandes CLI
• Actor Specification - Spécification complète