Conectar o Apify ao ClickHouse

Apify é uma plataforma de web scraping e automação. Você cria, executa e dimensiona programas serverless na nuvem chamados Actors. Actors fazem scraping de sites, rastreiam a web, processam dados ou automatizam fluxos de trabalho. Cada execução de um Actor gera uma saída estruturada armazenada em Datasets (coleções de objetos JSON).

Carregue dados coletados ou processados no ClickHouse para análises, monitoramento ou pipelines de enriquecimento.

Reúna os dados de conexão do ClickHouse

Para se conectar ao ClickHouse via HTTP(S), você precisa das seguintes informações:

Parâmetro(s)	Descrição
HOST and PORT	Normalmente, a porta é 8443 ao usar TLS ou 8123 quando não se usa TLS.
DATABASE NAME	Por padrão, há um banco de dados chamado default; use o nome do banco de dados ao qual você deseja se conectar.
USERNAME and PASSWORD	Por padrão, o nome de usuário é default. Use o nome de usuário apropriado para o seu caso de uso.

Os detalhes do seu serviço do ClickHouse Cloud estão disponíveis no console do ClickHouse Cloud. Selecione um serviço e clique em Connect:

Escolha HTTPS. Os detalhes de conexão são exibidos em um comando curl de exemplo.

Se você estiver usando ClickHouse autogerenciado, os detalhes de conexão são definidos pelo administrador do seu ClickHouse.

Pré-requisitos do Apify

Você também vai precisar de:

• Uma conta no Apify (com nível gratuito disponível).
• Um token da API do Apify, encontrado em Settings > Integrations no Apify Console.
• Node.js 18+ instalado localmente (para os exemplos em JavaScript).

Instale as dependências

Instale o cliente JavaScript do Apify e o cliente JavaScript do ClickHouse:

npm install apify-client @clickhouse/client

Crie uma tabela de destino no ClickHouse

Crie uma tabela para armazenar os dados coletados. O esquema depende do Actor usado. Este exemplo usa MergeTree para um Actor de coleta de dados de produtos:

CREATE TABLE apify_products
(
    url        String,
    title      String,
    price      Float64,
    currency   String,
    scraped_at DateTime DEFAULT now()
)
ENGINE = MergeTree()
ORDER BY (scraped_at, url);

Busque o dataset do Apify e carregue-o no ClickHouse

O script a seguir busca os resultados da execução de um Actor no Apify e os insere no ClickHouse:

import { ApifyClient } from 'apify-client';
import { createClient } from '@clickhouse/client';

// Inicializar clientes
const apify = new ApifyClient({ token: 'YOUR_APIFY_API_TOKEN' });
const clickhouse = createClient({
    url: 'https://YOUR_CLICKHOUSE_HOST:8443',
    username: 'default',
    password: 'YOUR_CLICKHOUSE_PASSWORD',
    database: 'default',
});

// Buscar itens do dataset da última execução de um Actor
const run = await apify.actor('YOUR_ACTOR_ID').call();
const { items } = await apify.dataset(run.defaultDatasetId).listItems();

console.log(`Foram buscados ${items.length} itens do dataset do Apify.`);

// Inserir no ClickHouse
await clickhouse.insert({
    table: 'apify_products',
    values: items,
    format: 'JSONEachRow',
});

console.log(`Foram inseridas ${items.length} linhas no ClickHouse.`);
await clickhouse.close();

Automatize com webhooks

Em vez de executar o script manualmente, automatize o pipeline para que os dados sejam carregados no ClickHouse sempre que um Actor for concluído:

1. No Apify Console, acesse seu Actor e abra a aba Integrations.
2. Adicione um novo webhook com:
   • Event type: ACTOR.RUN.SUCCEEDED
   • Action: Um HTTP POST para seu endpoint de carregamento ou o acionamento de outro Actor que faça o insert no ClickHouse.
3. O payload do webhook inclui o defaultDatasetId, que você pode usar para buscar os resultados da execução.

Consulte a documentação de webhooks do Apify para ver os detalhes do payload e as opções de configuração.

Como alternativa, você pode usar Apify Schedules para executar Actors em uma programação no estilo cron, combinada com webhooks para a etapa de carregamento.

Use a biblioteca cliente da Apify (apify-client para JavaScript ou Python) em vez de chamadas HTTP diretas. Ela cuida da paginação, das novas tentativas e da autenticação para você. Para datasets grandes, pagine os resultados usando os parâmetros limit e offset do endpoint List dataset items.

Use o formato JSONEachRow ao inserir dados no ClickHouse. Ele corresponde diretamente à saída JSON do Apify, sem necessidade de transformação.

Alinhe o esquema da sua tabela no ClickHouse aos campos de saída do Actor. Verifique o esquema de saída do Actor na página dele na Apify Store ou na aba Dataset após a execução.

Para inserções com alta taxa de transferência a partir do cliente JavaScript, siga as dicas de otimização de desempenho. Agrupe várias linhas em inserções maiores, em vez de inserir uma linha de cada vez, e considere usar async inserts quando o agrupamento no lado do cliente não for prático.

Os exemplos desta página usam o usuário e o banco de dados default para simplificar. Em produção, crie um usuário dedicado com os privilégios mínimos necessários para inserir dados na tabela de destino e armazene as credenciais de forma segura (por exemplo, em variáveis de ambiente ou em um gerenciador de segredos, em vez de fazer commit delas no código-fonte). Consulte Cloud access management para obter orientações.

• Documentação da plataforma Apify
• Referência da API da Apify
• cliente JavaScript do Apify
• Cliente Python da Apify
• Apify Store (Actors prontos para uso)
• Visão geral das integrações da Apify
• Cliente JavaScript do ClickHouse