Actorização Apify

Actorização converte software existente em aplicações serverless reutilizáveis compatíveis com a plataforma Apify. Atores são programas empacotados como imagens Docker que aceitam entrada JSON bem definida, realizam uma ação e, opcionalmente, produzem saída JSON estruturada.

Início Rápido

1. Execute apify init na raiz do projeto
2. Envolva o código com o ciclo de vida do SDK (veja a seção específica da linguagem abaixo)
3. Configure .actor/input_schema.json
4. Teste com apify run --input '{"key": "value"}'
5. Implante com apify push

Quando Usar Esta Habilidade

• Converter um projeto existente para rodar na plataforma Apify
• Adicionar integração com o SDK Apify a um projeto
• Empacotar uma ferramenta de linha de comando (CLI) ou script como um Ator
• Migrar um projeto Crawlee para Apify

Pré-requisitos

Verifique se a CLI apify está instalada:

apify --help

Se não estiver instalada:

brew install apify-cli

# Or: npm install -g apify-cli
# Or install from an official release package that your OS package manager verifies

Verifique se a CLI está logada:

apify info  # Should return your username

Se não estiver logada, verifique se a variável de ambiente APIFY_TOKEN está definida. Se não estiver, peça ao usuário para gerar uma em https://console.apify.com/settings/integrations, adicione-a ao seu shell ou gerenciador de segredos sem colocar o token literal no histórico de comandos, e então execute:

apify login

Checklist de Actorização

Copie este checklist para acompanhar o progresso:

• Passo 1: Analisar o projeto (linguagem, ponto de entrada, entradas, saídas)
• Passo 2: Executar apify init para criar a estrutura do Ator
• Passo 3: Aplicar a integração do SDK específica da linguagem
• Passo 4: Configurar .actor/input_schema.json
• Passo 5: Configurar .actor/output_schema.json (se aplicável)
• Passo 6: Atualizar metadados de .actor/actor.json
• Passo 7: Testar localmente com apify run
• Passo 8: Implantar com apify push

Passo 1: Analisar o Projeto

Antes de fazer alterações, entenda o projeto:

1. Identifique a linguagem - JavaScript/TypeScript, Python ou outra
2. Encontre o ponto de entrada - O arquivo principal que inicia a execução
3. Identifique as entradas - Argumentos de linha de comando, variáveis de ambiente, arquivos de configuração
4. Identifique as saídas - Arquivos, saída do console, respostas de API
5. Verifique o estado - Precisa persistir dados entre execuções?

Passo 2: Inicializar a Estrutura do Ator

Execute na raiz do projeto:

apify init

Isso cria:

• .actor/actor.json - Configuração e metadados do Ator
• .actor/input_schema.json - Definição de entrada para o Console Apify
• Dockerfile (se não presente) - Definição da imagem do container

Passo 3: Aplicar Alterações Específicas da Linguagem

Escolha com base na linguagem do seu projeto:

• JavaScript/TypeScript: Veja js-ts-actorization.md
• Python: Veja python-actorization.md
• Outras Linguagens (baseadas em CLI): Veja cli-actorization.md

Referência Rápida

Passos 4-6: Configurar Schemas

Veja schemas-and-output.md para configuração detalhada de:

• Schema de entrada (.actor/input_schema.json)
• Schema de saída (.actor/output_schema.json)
• Configuração do Ator (.actor/actor.json)
• Gerenciamento de estado (filas de requisição, lojas chave-valor)

Valide schemas contra o pacote npm @apify/json_schemas.

Passo 7: Testar Localmente

Execute o ator com entrada inline (para atores JS/TS e Python):

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

Ou use um arquivo de entrada:

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

Importante: Sempre use apify run, não npm start ou python main.py. A CLI configura o ambiente e o armazenamento adequados.

Passo 8: Implantar

apify push

Isso carrega e constrói seu ator na plataforma Apify.

Monetização (Opcional)

Após implantar, você pode monetizar seu ator na Apify Store. O modelo recomendado é Pagamento Por Evento (PPE):

• Por resultado/item raspado
• Por página processada
• Por chamada de API realizada

Configure o PPE no Console Apify em Ator > Monetização. Cobrança por eventos no seu código com await Actor.charge('result').

…