Intégration Apify SDK

Ajouter l'exécution d'Apify Actor à une application existante. Cette skill couvre le package apify-client pour JS/TS et Python, plus l'API REST pour les autres langages.

Quand utiliser cette skill

• Ajouter du web scraping ou de l'automatisation à une app existante
• Appeler des Apify Actors programmatiquement depuis le code de l'application
• Construire un produit qui utilise Apify comme service backend
• Intégrer les résultats d'Actor dans un pipeline de données

Critique : noms de packages

apify-client est le client API pour appeler des Actors depuis votre app. apify est le SDK pour construire des Actors (mauvais package pour ce cas d'usage).

Installez toujours apify-client. N'installez jamais apify pour des travaux d'intégration.

Prérequis

L'utilisateur a besoin d'un APIFY_TOKEN. Dirigez-le vers Console > Settings > Integrations sur https://console.apify.com/settings/integrations pour en créer un. S'il n'a pas de compte : https://console.apify.com/sign-up (gratuit, sans carte bancaire).

Stockez le token de manière sécurisée — variable d'environnement ou gestionnaire de secrets, jamais en dur.

Trouver le bon Actor

Avant d'écrire le code d'intégration, trouvez l'Actor qui correspond aux besoins de l'utilisateur. Utilisez les outils MCP s'ils sont disponibles :

• search-actors — chercher dans l'Apify Store par mot-clé
• fetch-actor-details — obtenir le schéma d'input, le format de sortie et les tarifs de l'Actor

Sinon, parcourez https://apify.com/store. Ajoutez .md à l'URL Store de n'importe quel Actor pour obtenir sa documentation en markdown.

JavaScript / TypeScript

Installation

npm install apify-client

Exécution synchrone (attendre les résultats)

import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });

const run = await client.actor('apify/web-scraper').call({
    startUrls: [{ url: 'https://example.com' }],
    maxPagesPerCrawl: 10,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();

.call() bloque jusqu'à la fin de l'Actor. À utiliser pour les Actors de courte durée (moins de quelques minutes).

Exécution asynchrone (démarrer et poll/récupérer plus tard)

const run = await client.actor('apify/web-scraper').start({
    startUrls: [{ url: 'https://example.com' }],
});

// Poll jusqu'à completion
const finishedRun = await client.run(run.id).waitForFinish();

// Récupérer les résultats
const { items } = await client.dataset(finishedRun.defaultDatasetId).listItems();

Utilisez .start() + .waitForFinish() pour les Actors de longue durée ou quand vous avez besoin du run ID immédiatement.

Récupération des résultats

// Éléments du dataset (données structurées de pushData)
const { items } = await client.dataset(run.defaultDatasetId).listItems({
    limit: 100,
    offset: 0,
});

// Key-value store (fichiers, captures d'écran, etc.)
const record = await client.keyValueStore(run.defaultKeyValueStoreId).getRecord('OUTPUT');

Gestion des erreurs

try {
    const run = await client.actor('apify/web-scraper').call(input);

    if (run.status !== 'SUCCEEDED') {
        const log = await client.log(run.id).get();
        throw new Error(`Actor failed with status ${run.status}: ${log}`);
    }

    const { items } = await client.dataset(run.defaultDatasetId).listItems();
} catch (error) {
    if (error.message?.includes('not found')) {
        // L'ID d'Actor est incorrect ou l'Actor a été supprimé
    } else if (error.statusCode === 401) {
        // APIFY_TOKEN invalide ou manquant
    }
    throw error;
}

Python

Installation

pip install apify-client

Exécution synchrone

from apify_client import ApifyClient
import os

client = ApifyClient(token=os.environ['APIFY_TOKEN'])

run = client.actor('apify/web-scraper').call(run_input={
    'startUrls': [{'url': 'https://example.com'}],
    'maxPagesPerCrawl': 10,
})

items = client.dataset(run['defaultDatasetId']).list_items().items

Exécution asynchrone

run = client.actor('apify/web-scraper').start(run_input={
    'startUrls': [{'url': 'https://example.com'}],
})

# Poll jusqu'à completion
finished_run = client.run(run['id']).wait_for_finish()

items = client.dataset(finished_run['defaultDatasetId']).list_items().items

Client asynchrone (asyncio)

from apify_client import ApifyClientAsync

client = ApifyClientAsync(token=os.environ['APIFY_TOKEN'])

run = await client.actor('apify/web-scraper').call(run_input={
    'startUrls': [{'url': 'https://example.com'}],
})

items = (await client.dataset(run['defaultDatasetId']).list_items()).items

API REST (n'importe quel langage)

Pour les langages sans client officiel, utilisez directement l'API REST.

Démarrer une exécution

POST https://api.apify.com/v2/acts/{actorId}/runs
Authorization: Bearer <APIFY_TOKEN>
Content-Type: application/json

{ "startUrls": [{ "url": "https://example.com" }] }

Obtenir le statut d'une exécution

GET https://api.apify.com/v2/acts/{actorId}/runs/{runId}
Authorization: Bearer <APIFY_TOKEN>

Obtenir les éléments du dataset

GET https://api.apify.com/v2/datasets/{datasetId}/items?format=json
Authorization: Bearer <APIFY_TOKEN>

Référence API complète : https://docs.apify.com/api/v2

Bonnes pratiques

• Définir des timeouts : Passez timeoutSecs en input de l'Actor ou utilisez waitSecs sur .call() pour éviter les attentes infinies.
• Paginer les grands datasets : Utilisez limit et offset lors de la récupération des éléments du dataset. La limite par défaut est 250 K éléments.
• Réutiliser les clients : Créez une seule instance ApifyClient et réutilisez-la entre les appels.
• Gérer l'input spécifique à l'Actor : Chaque Actor a son propre schéma d'input. Utilisez l'outil MCP fetch-actor-details ou ajoutez .md à l'URL Store de l'Actor pour obtenir le schéma avant de construire l'input.

Documentation

• Client API Apify pour JS : https://docs.apify.com/api/client/js
• Client API Apify pour Python : https://docs.apify.com/api/client/python
• Référence API REST : https://docs.apify.com/api/v2
• Docs Apify (optimisées pour LLM) : https://docs.apify.com/llms.txt
• Docs Apify (complètes) : https://docs.apify.com/llms-full.txt

Si le serveur MCP Apify est disponible, utilisez les outils search-apify-docs et fetch-apify-docs pour des recherches de documentation contextuelle pendant le développement.