ComposioHQ/Automação-Apify

Automação Apify

Execute Atores de web scraping do Apify e gerencie conjuntos de dados diretamente do Claude Code. Execute rastreadores de forma síncrona ou assíncrona, recupere dados estruturados, crie tarefas reutilizáveis e inspecione logs de execução sem sair do seu terminal.

Documentação do toolkit: composio.dev/toolkits/apify

---

Configuração

1. Adicione o servidor MCP do Composio à sua configuração:

   https://rube.app/mcp
   

2. Conecte sua conta Apify quando solicitado. O agente fornecerá um link de autenticação.
3. Navegue pelos Atores disponíveis em apify.com/store. Cada Ator possui seu próprio esquema de entrada único -- sempre verifique a documentação do Ator antes de executá-lo.

---

Fluxos de Trabalho Principais

1. Executar um Ator de Forma Síncrona e Obter Resultados

Execute um Ator e recupere imediatamente seus itens de dataset em uma única chamada. Melhor para trabalhos de scraping rápidos.

Ferramenta: APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS

Parâmetros principais:

• actorId (obrigatório) -- ID do Ator no formato usuario/nome-do-ator (ex.: compass/crawler-google-places)
• input -- Objeto JSON de entrada que corresponde ao esquema do Ator. Cada Ator tem nomes de campos únicos -- verifique em apify.com/store o esquema exato.
• limit -- máximo de itens a retornar
• offset -- pular itens para paginação
• format -- json (padrão), csv, jsonl, html, xlsx, xml
• timeout -- tempo limite da execução em segundos
• waitForFinish -- tempo máximo de espera (0-300 segundos)
• fields -- lista separada por vírgulas de campos a incluir
• omit -- lista separada por vírgulas de campos a excluir

Exemplo de prompt: "Execute o scraper do Google Places para 'restaurantes em Nova York' e retorne os primeiros 50 resultados"

---

2. Executar um Ator de Forma Assíncrona

Dispare uma execução de Ator sem esperar pela conclusão. Use para trabalhos de scraping de longa duração.

Ferramenta: APIFY_RUN_ACTOR

Parâmetros principais:

• actorId (obrigatório) -- slug ou ID do Ator
• body -- Objeto JSON de entrada para o Ator
• memory -- limite de memória em MB (deve ser potência de 2, mínimo 128)
• timeout -- tempo limite da execução em segundos
• maxItems -- limite de itens retornados
• build -- tag de build específica (ex.: latest, beta)

Acompanhe com APIFY_GET_DATASET_ITEMS para recuperar resultados usando o datasetId da execução.

Exemplo de prompt: "Inicie o Ator de web scraping para example.com de forma assíncrona com 1024MB de memória"

---

3. Recuperar Itens de um Dataset

Busque dados de um dataset específico com paginação, seleção de campos e filtragem.

Ferramenta: APIFY_GET_DATASET_ITEMS

Parâmetros principais:

• datasetId (obrigatório) -- identificador do dataset
• limit (padrão/máx. 1000) -- itens por página
• offset (padrão 0) -- deslocamento da paginação
• format -- json (recomendado), csv, xlsx
• fields -- incluir apenas campos específicos
• omit -- excluir campos específicos
• clean -- remover metadados específicos do Apify
• desc -- ordem inversa (mais recentes primeiro)

Exemplo de prompt: "Obtenha os primeiros 500 itens do dataset myDatasetId no formato JSON"

---

4. Inspecionar Detalhes de um Ator

Veja metadados do Ator, esquema de entrada e configuração antes de executá-lo.

Ferramenta: APIFY_GET_ACTOR

Parâmetros principais:

• actorId (obrigatório) -- ID do Ator no formato usuario/nome-do-ator ou ID hexadecimal

Exemplo de prompt: "Mostre-me os detalhes e o esquema de entrada do Ator apify/web-scraper"

---

5. Criar Tarefas Reutilizáveis

Configure tarefas de Ator reutilizáveis com entradas predefinidas para trabalhos de scraping recorrentes.

Ferramenta: APIFY_CREATE_TASK

Configure uma tarefa uma vez e depois dispare-a repetidamente com parâmetros de entrada consistentes. Útil para fluxos de trabalho de coleta de dados programados ou recorrentes.

Exemplo de prompt: "Crie uma tarefa Apify para o scraper de pesquisa do Google com consulta padrão 'startups de IA' e localização EUA"

---

6. Gerenciar Execuções e Datasets

Liste execuções de Atores, navegue por datasets e inspecione detalhes da execução para monitoramento e depuração.

Ferramentas: APIFY_GET_LIST_OF_RUNS, APIFY_DATASETS_GET, APIFY_DATASET_GET, APIFY_GET_LOG

Para listar execuções:

• Filtrar por Ator e opcionalmente por status
• Obter datasetId dos detalhes da execução para recuperação de dados

Para gerenciamento de datasets:

• APIFY_DATASETS_GET -- lista todos os seus datasets com paginação
• APIFY_DATASET_GET -- obtém metadados de um dataset específico

Para depuração:

• APIFY_GET_LOG -- recupera logs de execução de uma execução ou build

Exemplo de prompt: "Liste as últimas 10 execuções do Ator de web scraping e mostre os logs da mais recente"

---

Armadilhas Conhecidas

• Esquemas de entrada de Atores variam muito: Cada Ator tem seus próprios campos de entrada únicos. Nomes genéricos de campos como queries ou search_terms serão rejeitados. Sempre verifique a página do Ator em apify.com/store para nomes exatos de campos (ex.: searchStringsArray para Google Maps, startUrls para scrapers web).
• Requisitos de formato de URL: Sempre inclua o protocolo completo (https:// ou http://) nas URLs. Muitos Atores exigem URLs como objetos com uma propriedade url: {"startUrls": [{"url": "https://example.com"}]}
• Limite de paginação do dataset: APIFY_GET_DATASET_ITEMS tem um limit máximo de 1000 por chamada. Para datasets grandes, faça um loop com offset para coletar todos os itens.
• Valores de enum em minúsculas: A maioria dos Atores espera valores de enum em minúsculas (ex.: relevance não RELEVANCE, all não ALL).
• Timeout síncrono de 5 minutos: APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS tem um waitForFinish máximo de 300 segundos. Para execuções mais longas, use APIFY_RUN_ACTOR (assíncrono) e faça polling com APIFY_GET_DATASET_ITEMS.
• Custos de volume de dados: Datasets grandes podem ser caros para buscar. Prefira limites moderados e processamento incremental para evitar timeouts ou pressão de memória.
• Formato JSON recomendado: Embora formatos CSV/XLSX estejam disponíveis, JSON é o mais confiável para processamento automatizado. Evite CSV/XLSX para automação downstream.

---

Referência Rápida

Slug da Ferramenta	Descrição
APIFY_RUN_ACTOR_SYNC_GET_DATASET_ITEMS	Executa Ator de forma síncrona e obtém resultados imediatamente
APIFY_RUN_ACTOR	Executa Ator de forma assíncrona (dispara e retorna)
APIFY_RUN_ACTOR_SYNC	Executa Ator de forma síncrona, retorna registro de saída
APIFY_GET_ACTOR	Obtém metadados e esquema de entrada do Ator
APIFY_GET_DATASET_ITEMS	Recupera itens de um dataset (com paginação)
APIFY_DATASET_GET	Obtém metadados do dataset (contagem de itens, etc.)
APIFY_DATASETS_GET	Lista todos os datasets do usuário
APIFY_CREATE_TASK	Cria uma tarefa de Ator reutilizável
APIFY_GET_TASK_INPUT	Inspeciona a entrada armazenada de uma tarefa
APIFY_GET_LIST_OF_RUNS	Lista execuções de um Ator
APIFY_GET_LOG	Obtém logs de execução de uma execução

---

Desenvolvido por Composio