Executando uma rotina batch

Neste tutorial, você vai criar um Data App (antigo Carol App) para executar um programa simples em Python. Ele mostra os itens 1, 2 e 3 nos logs e termina. Depois, você muda uma configuração para mostrar cinco itens e executa novamente.

Esse tipo de execução, com início e fim, é um processo batch. Você pode iniciá-lo na hora ou definir um agendamento para ele executar depois.

Para o programa se conectar à plataforma, usaremos o pyCarol, uma biblioteca Python de código aberto. Ela facilita a leitura das configurações do app e o envio de mensagens para os logs. Consulte também a documentação do pyCarol.

Saiba mais: o que construir com um processo batch

Necessidade	Exemplo de rotina com início e fim
Integrar um sistema	Consultar uma API periodicamente e enviar os dados para uma STG
Importar arquivos	Ler um CSV, validar seus campos e registrar linhas aceitas e rejeitadas
Enriquecer dados	Aplicar regras ou um modelo de IA sobre um lote e salvar o resultado
Gerar uma entrega	Produzir um relatório ou uma exportação
Fazer uma conferência	Comparar origem e destino e registrar divergências

O programa implementa a lógica. O app fornece configuração e infraestrutura para executá-lo manualmente ou por agendamento.

Ambiente e recursos do exemplo

Recurso	Configuração
Ambiente	Sua tenant de desenvolvimento, com permissão para criar e editar apps
App	Um nome disponível na plataforma; use um app separado do guia de pipelines
Processo batch	batch_demo
Imagem	guide-batch:1.1.0
Quantidade de itens	ITEM_LIMIT, inicialmente 3
Código	Exemplo no repositório de samples

O exercício não acessa dados de negócio da tenant. Você pode reutilizar a tenant do guia Preparando os dados.

Saiba mais: como obter uma tenant de desenvolvimento

Tenant de desenvolvimento

Se você já tem uma tenant DEVELOPMENT, confira se possui permissão de Tenant Admin para acompanhar o exercício. Caso precise de um ambiente:

1. Abra o formulário da plataforma.
2. Selecione Desenvolvimento e a opção de criar/provisionar ambiente ou tenant.
3. Informe a organização do projeto e acompanhe o chamado até receber o acesso.

Saiba mais: onde desenvolver e onde operar

Neste exercício, e em projetos simples de aprendizado, a rotina pode executar no próprio ambiente de desenvolvimento. Para operação produtiva, a recomendação do time é preparar e validar na DEV e utilizar um ambiente unificado (UNIFIED), com versão do app instalada e parâmetros e agendamentos conferidos nesse ambiente.

Essa recomendação não exige criar um unificado para este tutorial. Considere origens, isolamento dos dados e desenho do projeto. Desenvolver, publicar e instalar uma versão são etapas distintas; veja Antes de começar.

Em produção, mantenha somente dados produtivos. Dados fictícios, simulações e testes deste tutorial ficam na DEV ou em um ambiente próprio de homologação. Não use dados produtivos reais para validar o exemplo de aprendizado. Confira tenant, credenciais e destino antes de executar uma rotina que lê ou grava dados.

Etapas do tutorial

1. Prepare os arquivos
2. Construa a imagem
3. Execute o batch
4. Confira a task e os logs

Enviar o manifesto, construir a imagem e executar o processo são operações distintas. Ao terminar o build, você ainda precisa iniciar a rotina.

Passo 1: Prepare os arquivos

Prepare e teste o código

O exemplo contém estes arquivos:

Arquivo	Responsabilidade
main.py	Lê a quantidade, processa os itens e registra a conclusão
Dockerfile	Define o ambiente Python e o comando que inicia o programa
manifest.json	Associa o processo à imagem e configura sua execução
requirements.txt	Fixa as versões de pyCarol e python-dotenv
.env.example	Configuração local não sensível
.gitignore e .dockerignore	Mantêm .env fora do Git e da imagem

Clone o repositório de samples e selecione a branch do exemplo:

O exemplo usa Python 3.14, também utilizado na imagem Docker.

git clone --branch master https://github.com/totvslabs/carolapp-samples.git
cd carolapp-samples/guides/data-apps/first-batch
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python main.py --local

O modo --local permite conferir a rotina sem autenticar ou chamar a plataforma. O resultado esperado inclui:

Saída da execução com três itens

{"event": "started", "total": 3, "local": true}
{"event": "item_processed", "item": 1, "message": "Guia batch"}
{"event": "item_processed", "item": 2, "message": "Guia batch"}
{"event": "item_processed", "item": 3, "message": "Guia batch"}
{"event": "completed", "total": 3}

O evento completed é uma mensagem do código do exemplo. A conclusão da task é um estado registrado pela plataforma; confira ambos durante a validação.

Saiba mais: executar localmente com API Key e Carol() sem parâmetros

O --local testa a lógica sem conexão. Para ler os Settings do app na plataforma, execute o programa sem esse argumento, usando contexto autorizado no .env:

1. Obtenha um Connector Token (API Key) autorizado para a tenant dev e as operações necessárias, junto com seu Connector ID. Não use uma credencial de produção para este exercício; veja como criar o token.
2. Copie .env.example para .env, ao lado de main.py, e preencha as variáveis de conexão apenas nesse arquivo local. Nunca o envie ao Git.

Onde encontrar os nomes

Com a tenant aberta, confira o endereço no navegador. Por exemplo, em https://exemplo.carol.ai/desenvolvimento/...:

Variável	Onde encontrar	Valor no exemplo
CAROLORGANIZATION	Parte antes de .carol.ai	exemplo
CAROLTENANT	Primeiro trecho depois de .carol.ai/	desenvolvimento
CAROLAPPNAME	Nome técnico do Data App, definido no campo Name na criação	guiabatchdemo

CAROLAPPNAME indica qual Data App o pyCarol vai acessar — por exemplo, para ler seus Settings. Ao criar o app na etapa 2, você informa dois nomes:

• Label: o nome exibido na interface, como Guia de processo batch.
• Name: o nome técnico usado na integração, como guiabatchdemo.

Nesse caso, preencha CAROLAPPNAME=guiabatchdemo no .env. Copie exatamente o Name informado na criação. batch_demo é o processo dentro desse app; o código na URL é o ID do app. Nenhum dos dois substitui o Name.

Se ainda não criou o app, faça isso na etapa 2 antes de testar a conexão local.

Exemplo de formato; substitua os valores somente no seu .env

CAROLORGANIZATION=sua-organizacao
CAROLTENANT=sua-tenant-dev
CAROLAPPNAME=nome-tecnico-do-app
CAROLCONNECTORID=ID_DO_CONNECTOR
CAROLAPPOAUTH=API_KEY_DO_CONNECTOR
ITEM_LIMIT=3
LOG_LEVEL=INFO

3. Execute, com o ambiente Python ativado:

python main.py

O código carrega a configuração e cria a conexão sem passar os valores ao construtor:

load_dotenv(Path(__file__).with_name(".env"), override=False)
carol = Carol()
settings = Apps(carol).get_settings()

Carol() lê as variáveis de contexto configuradas. Isso dispensa repetir organização, tenant, app e autenticação no construtor; não dispensa configurar esses valores. O nome técnico é o do app, não batch_demo, que é o processo.

Sem LONGTASKID, esse teste conectado registra no console e não escreve em uma task existente. Não copie o Task Id de outra execução para simular esse vínculo. Na plataforma, o contexto é injetado e o mesmo código registra também na task corrente. O .env local permanece fora da imagem.

Referências: pyCarol, código e exemplos do SDK.

Saiba mais: imagem e teste com Docker

A imagem empacota o programa e seu ambiente. O Dockerfile do exemplo utiliza uma imagem oficial do Python, instala os pacotes, copia main.py e define python main.py como inicialização. Você pode testar a mesma rotina em um contêiner na sua máquina local. Para isso, mantenha o Docker em execução e rode os comandos abaixo no terminal:

docker build -t guide-batch:1.1.0 .
docker run --rm -e ITEM_LIMIT=3 guide-batch:1.1.0 --local

O programa deve imprimir os eventos e encerrar com código 0. Teste também ITEM_LIMIT=0: a configuração é inválida e deve encerrar com erro.

Esse build local ajuda a conferir a imagem. A construção na plataforma será feita separadamente, a partir do código disponível no Git.

Saiba mais: entenda cada linha do Dockerfile

O Dockerfile segue um padrão amplamente usado no mercado, no ecossistema Docker, para descrever a construção de imagens de contêiner. Ele é a receita da imagem: o build executa suas instruções e a execução do batch inicia o programa empacotado nela. Consulte a referência oficial do Dockerfile.

Dockerfile do exemplo

FROM python:3.14-slim

WORKDIR /app

ENV PYTHONUNBUFFERED=1
ENV LOG_LEVEL=INFO

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY main.py .

HEALTHCHECK NONE

ENTRYPOINT ["python", "main.py"]

Instrução	O que faz
FROM	Usa a imagem oficial do Python, em uma versão estável explícita
WORKDIR	Define /app como diretório de trabalho
ENV	Define padrões não sensíveis; a saída sem buffer ajuda a disponibilizar logs durante a execução
COPY requirements.txt e RUN pip install	Instalam as dependências antes de copiar o programa; mudanças só no código podem aproveitar o cache dessa camada
COPY main.py	Inclui o programa, sem copiar .env ou todo o repositório
HEALTHCHECK NONE	Declara que este batch finito não usa uma verificação periódica de serviço
ENTRYPOINT	Define o comando iniciado quando o processo executa

Os comandos COPY buscam os arquivos na pasta usada para construir a imagem. Neste exemplo, Dockerfile, requirements.txt e main.py ficam juntos; por isso, usamos apenas os nomes dos arquivos.

Ao iniciar, o contêiner executa python main.py. O programa processa os itens e encerra. Se você alterar o Dockerfile ou as dependências, faça um novo build para incluir as mudanças na imagem.

Configure o manifesto

Abra manifest.json, na pasta do exemplo. O arquivo já aponta para o repositório público e a branch usados neste guia. Confira os valores antes do envio:

Campo	Valor no exemplo	Para que serve
algorithmName	batch_demo	Identifica o processo; o comando que inicia o programa fica no ENTRYPOINT do Dockerfile
dockerName	guide-batch	Liga o processo à definição da imagem; deve coincidir nos dois blocos
gitBranch	master	Branch principal que contém o código a construir
gitPath	/guides/data-apps/first-batch	Pasta usada no build; os comandos COPY buscam os arquivos a partir dela
dockerTag	1.1.0	Identifica a imagem do exemplo
instanceType	c1.nano	Recursos para executar a rotina, conforme disponibilidade no ambiente

A quantidade fica em instanceProperties.environments, como texto:

Trecho de instanceProperties

{
  "environments": {"ITEM_LIMIT": "3"},
  "properties": {
    "dockerName": "guide-batch",
    "instanceType": "c1.nano",
    "preemptible": false
  }
}

environments fica no mesmo nível de properties. O programa lê ITEM_LIMIT do ambiente e converte o texto para número.

Saiba mais: manifest.json completo

Este é o arquivo completo do exemplo. Ele declara o processo batch_demo, as variáveis, os recursos de execução e a origem do build. Baixe o manifest.json dos samples para usar os mesmos valores.

manifest.json

{
  "batch": {
    "processes": [
      {
        "name": "batch_demo",
        "algorithmName": "batch_demo",
        "algorithmTitle": {
          "pt-BR": "Processar itens",
          "en-US": "Process items"
        },
        "algorithmDescription": {
          "pt-BR": "Processa itens e encerra.",
          "en-US": "Processes items and exits."
        },
        "dataModels": [],
        "instanceProperties": {
          "environments": {
            "ITEM_LIMIT": "3",
            "LOG_LEVEL": "INFO"
          },
          "properties": {
            "dockerName": "guide-batch",
            "instanceType": "c1.nano",
            "preemptible": false
          }
        }
      }
    ]
  },
  "docker": [
    {
      "dockerName": "guide-batch",
      "dockerTag": "1.1.0",
      "gitRepoUrl": "https://github.com/totvslabs/carolapp-samples",
      "gitBranch": "master",
      "gitPath": "/guides/data-apps/first-batch",
      "gitDockerfileName": "Dockerfile"
    }
  ]
}

Ao adaptar, confira o repositório, a branch e o diretório reais. O dockerName do processo precisa corresponder à entrada em docker[]; a tag precisa ser a mesma construída no build. O agendamento deste guia é configurado pela interface.

Saiba mais: qual branch será usada no build?

Uma branch é uma linha de trabalho no Git. Neste repositório, a principal se chama master; em outros, pode se chamar main. Use o nome que realmente existe.

Local	O que precisa estar correto
Sua máquina	O código foi salvo e commitado
Repositório remoto	O commit foi enviado com git push para a branch escolhida
Manifesto	gitRepoUrl, gitBranch, gitPath e Dockerfile apontam para os arquivos certos
Modal de build	Mantenha Git Branch Name com o valor carregado do manifesto

Para escolher a branch neste tutorial, defina gitBranch no manifesto e reenvie o arquivo antes do build. Mantenha esse valor no campo Git Branch Name. O build usa o código do repositório remoto: alterações que existem só na sua máquina ou em outra branch precisam ser enviadas para a branch indicada.

Depois do merge de um PR, a branch temporária pode ser excluída. Por isso, o manifesto e este guia apontam para master. Usar uma branch de revisão funciona enquanto ela existe, mas não deixa o exemplo independente dessa branch.

Push ou merge não atualizam uma imagem pronta. Após alterar o programa, construa uma nova imagem e confira sua tag no processo. O checkout de pipelines SQL é outro fluxo; não substitui esse build.

Saiba mais: .env, Docker, manifesto, contexto e Settings

Opção	Onde é definida	Como o programa lê	Uso no exemplo
.env local	Arquivo ao lado de main.py, fora do Git	load_dotenv(..., override=False) e os.environ	Experimentar ITEM_LIMIT localmente
ENV do Dockerfile	Na construção da imagem	os.environ	Padrão LOG_LEVEL=INFO e saída Python sem buffer
Variáveis do manifesto	instanceProperties.environments	os.environ	Configurar ITEM_LIMIT e LOG_LEVEL na execução
Contexto da plataforma	Injetado ao executar o app	pyCarol e ambiente	Identificar tenant, app e task e autenticar a integração
Settings	Aba Settings do app, por tenant	Apps(carol).get_settings()	Parâmetro opcional message_prefix
ARG do Dockerfile	Durante o build, quando suportado pelo fluxo	Instruções do Dockerfile	Não utilizado neste exercício

Na sua máquina, o .env guarda a configuração usada nos testes. Se ele tiver ITEM_LIMIT=4, o programa processará quatro itens. Você pode mudar o valor só para uma execução pelo terminal:

ITEM_LIMIT=5 python main.py --local

Nesse caso, serão cinco itens: override=False faz o programa preservar o valor informado pelo terminal, em vez de substituí-lo pelo valor do .env.

Na plataforma, configure ITEM_LIMIT no manifesto. O exemplo não precisa do arquivo .env na imagem. As variáveis do manifesto também podem substituir valores padrão definidos com ENV no Dockerfile, como LOG_LEVEL.

A plataforma fornece automaticamente os dados de conexão e da task em variáveis como CAROLTENANT, CAROLAPPNAME, CAROLAPPOAUTH e LONGTASKID. O Carol() usa esses dados para se conectar; você não precisa preenchê-los no manifesto.

Settings são outra forma de configuração. Neste código, ITEM_LIMIT define a quantidade de itens por uma variável de ambiente; o Setting message_prefix define o texto das mensagens. Cada valor é lido separadamente pelo programa.

Veja os campos disponíveis na referência do manifesto.

Saiba mais: Settings e recomendação para secrets

Um Setting é um parâmetro do app que pode mudar entre tenants sem alterar o código. O programa consulta os Settings e usa message_prefix, quando configurado; caso contrário, usa Guia batch.

settings = Apps(carol).get_settings()
prefix = settings.get("message_prefix") or "Guia batch"

Para usar secrets no app, é necessário abrir um chamado pelo formulário da plataforma. Selecione Quero reportar um tema que não consta em nenhuma das opções anteriores e solicite a configuração de secrets para a organização, a tenant e o app desejados.

Um campo comum em Settings, mesmo quando mascarado na tela, não deve ser presumido equivalente a um gerenciador de secrets.

• Não versione tokens em .env, manifesto ou código; versione apenas .env.example sem segredos.
• Não copie .env para a imagem. O exemplo também o exclui pelo .dockerignore.
• Não use ENV ou ARG para embutir secrets na imagem ou no histórico de build.
• Não imprima todos os Settings, variáveis ou respostas de autenticação nos logs.
• Confirme o suporte do builder e do ambiente antes de adotar um recurso de secrets.

A referência de build secrets do Docker explica secret mounts. Isso não comprova que o builder da plataforma exponha esse recurso; o tutorial não depende dele.

Saiba mais: documentação do pyCarol e ajuda de IA

O pyCarol é o SDK Python de código aberto da plataforma. Consulte a página de documentação, o Read the Docs e os exemplos do repositório. O requirements.txt fixa a versão usada: confira a documentação correspondente.

O Python é a linguagem escolhida para este guia. Você pode seguir o mesmo fluxo para criar um batch em Node.js ou outra linguagem: preparar o código e o Dockerfile, construir a imagem e executar o processo. Nesse caso, a integração com a plataforma pode ser feita pelas APIs HTTP; o pyCarol é específico de Python.

Você pode pedir ajuda a uma IA para entender ou adaptar o código, fornecendo o link da documentação, a versão instalada, a tarefa desejada e dados fictícios:

Usando pyCarol 2.56.15, explique como ler o Setting message_prefix e enviar logs para a task corrente. Preserve o contexto injetado e não registre credenciais. Mostre como testar a lógica localmente.

Confira as chamadas na documentação e teste o resultado em desenvolvimento. Não envie tokens ou dados reais do cliente no pedido à IA.

Passo 2: Construa a imagem

Crie o app e envie o manifesto

1. Na tenant de desenvolvimento, abra Data Apps → Developed Apps → Create new App.
2. Informe um Label, um Name disponível, Version 0.1.0 e uma descrição.
3. Em Low Latency Data Source for Servers (MCP/REST), selecione Customer Tenant. Este exercício não precisa habilitar a baixa latência. Deixe Unified tenant vazio.
4. Clique em Create App e abra o novo app.
5. Em Files → Upload file, envie o manifest.json do exemplo como Monitor Processes.
6. Aguarde a conclusão do deploy e confira se batch_demo aparece em Process.

Resultado esperado: o processo está cadastrado. O envio do manifesto ainda não construiu sua imagem nem executou o programa.

Se reutilizar um app que já tem agendamentos: registre cron e fuso antes de reenviar o manifesto e confira-os depois. Há um problema conhecido de perda de schedules nesse fluxo. O app separado deste tutorial evita afetar o exercício anterior.

Faça o build

1. Clique em Build e selecione a definição pelo nome guide-batch.
2. Em Git Branch Name, mantenha master, carregado do manifesto, sem editar o campo. Confira o repositório e os arquivos indicados pelo manifesto. O campo GitHub Token, apesar do nome, recebe o token de acesso do provedor do repositório: GitHub, Azure DevOps ou outro serviço Git compatível. Como o exemplo é público, deixe esse campo vazio.
3. Em Next, confira o nome da imagem, a tag 1.1.0 e a instância usada para o build.
4. Em Instance type to build docker image → Edit, prefira c1.small ou c1.medium. Esses tamanhos têm menor concorrência e um pool maior para o build, conforme a orientação operacional do time. Neste exemplo, selecione c1.small.
5. Clique em Build image, abra a task e acompanhe o log até a conclusão.

Resultado esperado: build concluído com sucesso e imagem disponível para o processo. Se falhar, confira o log antes de tentar executar a rotina.

A recomendação de small ou medium se refere ao build. O batch simples deste exercício continua configurado com c1.nano para execução; uma máquina maior no build não altera automaticamente os recursos do processo nem garante início imediato.

Máquina	Quando é usada	Onde configurar
Build	Busca o código, instala dependências e constrói a imagem	Modal Build → Instance type to build docker image; prefira small ou medium
Processamento	Inicia o programa e executa o batch a cada Run ou agendamento	instanceProperties.properties.instanceType do processo no manifesto

São alocações distintas. Terminada a construção, a máquina de build não fica reservada para executar o batch. Dimensione o processamento pela carga real.

Saiba mais: PAT para acessar GitHub e Azure DevOps

Um PAT (Personal Access Token) autoriza a integração a acessar o repositório em nome de uma conta. Para baixar código privado, utilize acesso de leitura, restrito ao repositório/organização necessários e com expiração.

Provedor	Onde criar	O que conferir
GitHub	Settings → Developer settings → Personal access tokens → Fine-grained tokens	Selecione o proprietário e o repositório; para ler o código, configure Contents: Read-only, conforme compatibilidade da integração. Confira aprovação da organização e requisitos de SSO.
Azure DevOps	User settings → Personal access tokens → New Token	Selecione a organização e validade; para obter código do Azure Repos, configure Code: Read, conforme as políticas da organização.

Referências: criar e gerenciar PATs no GitHub e usar PATs no Azure DevOps.

Informe o PAT do seu provedor no campo de autenticação da integração Git/build (GitHub Token, nesta interface). Confira URL do repositório e branch antes de iniciar. Este guia usa um repositório público; o fluxo privado com GitHub/Azure não foi homologado nesta revisão.

O PAT do Git serve para baixar o código. A API Key da plataforma serve para o pyCarol acessar a tenant. Não troque um pelo outro nem inclua tokens no manifesto, Dockerfile, URL do repositório ou logs. Confirme as políticas do time para integrações produtivas e renove a credencial antes de expirar.

Em falhas de autenticação, confira acesso da conta ao repositório, escopo, validade, aprovação e SSO. Uma configuração Git já usada nas pipelines SQL não comprova que o build recebeu a mesma credencial.

Passo 3: Execute o batch

Execute manualmente

1. Em Process, localize batch_demo e clique em Run now (ou Run, conforme a versão da interface).
2. Abra a task criada em Activity Management.
3. Confira a conclusão e os logs antes de alterar a configuração ou agendar.

Na plataforma, a imagem inicia sem --local: o pyCarol usa o contexto recebido, lê os Settings e registra os eventos na task. Não informe manualmente o Task Id de outra execução para reutilizá-lo.

Altere a configuração e execute novamente

Antes de criar um agendamento, teste a mudança de um parâmetro:

1. No manifesto local, altere "ITEM_LIMIT": "3" para "ITEM_LIMIT": "5".
2. Reenvie o manifesto em Files e aguarde o deploy.
3. Execute batch_demo novamente, reutilizando a imagem já construída.
4. Confira cinco eventos item_processed, completed com total: 5 e a conclusão da task.

Resultado esperado: a nova execução processa cinco itens, sem outro build.

Isso funciona porque você alterou apenas a configuração recebida pelo programa; a imagem continua sendo a mesma. Já uma mudança no código, nas dependências ou no Dockerfile exige um novo build. Veja Build e atualização.

Saiba mais: versão do app e imagem usada pelo processo

O app reúne os processos e suas configurações. Cada processo executa o programa que foi empacotado em uma imagem Docker.

Neste exemplo:

Item	Valor	O que significa
Versão do app	0.1.0	Identifica o pacote do app para publicação e instalação
Nome do processo	batch_demo	Identifica a rotina dentro do app
Imagem do processo	guide-batch:1.1.0	Identifica o programa que a rotina executa; 1.1.0 é a tag da imagem

O app 0.1.0 contém o processo batch_demo, que executa a imagem guide-batch:1.1.0. A versão do app é o controle de versões do pacote na plataforma, usado na publicação e instalação. A tag da imagem indica qual programa o processo executa. Esses números não precisam ser iguais; mudar a versão do app, por si só, não cria outra imagem.

Quando o código mudar, escolha como distribuir a atualização:

Objetivo	Como fazer
Aplicar um hotfix a todos os ambientes que usam a mesma tag	Faça um novo build e disponibilize a imagem com a mesma tag
Atualizar os ambientes aos poucos	Crie uma nova tag e atualize a referência à imagem nos ambientes escolhidos

Exemplo de hotfix: vários ambientes têm o app instalado e usam guide-batch:1.1.0. Você corrige main.py, envia o código para a branch do manifesto e faz outro build com a tag 1.1.0. A correção é disponibilizada para todos os ambientes que usam essa imagem e tag, sem alterar a versão do app instalada em cada um. Essa escolha compartilha a mudança com todos eles.

Exemplo de atualização gradual: faça o build com uma nova tag, como 1.1.1, e altere dockerTag no manifesto. Publique uma nova versão do app, como 0.1.1, e instale primeiro em um ambiente para validar. Os demais continuam usando guide-batch:1.1.0 até receberem a atualização.

A execução usa a tag indicada no manifesto.

Agende a execução

Depois de validar a execução manual:

1. Em Process, use + Add a Schedule em batch_demo.
2. No modo Visual, configure uma frequência de teste, confira o fuso horário e a conta em Run as. Confira a prévia das próximas execuções e salve.
3. Confira a próxima execução e acompanhe a task gerada pelo agendamento.
4. Verifique a conclusão e o total de cinco itens nos logs.
5. Ao terminar o exercício, pause o agendamento para encerrar as execuções recorrentes.

Saiba mais: execução imediata e agendamento

Run now inicia uma execução sob demanda; você acompanha a task daquela rodada. Um agendamento define execuções futuras, únicas ou recorrentes. O modo Visual oferece frequências como hora, dia, semana e mês. Confira sempre o fuso e a prévia das próximas datas.

A conta de Run as precisa estar disponível e ter as permissões necessárias. Ao publicar e instalar o app em outro ambiente, confira o agendamento e essa conta no destino: a tela de desenvolvimento avisa que Schedule e Last Run não integram automaticamente o app liberado.

Saiba mais: configurar o agendamento no modo Manual

No modo Manual, você informa os horários por uma expressão cron. Para montar essa expressão com mais facilidade, use o gerador de cron Quartz, também indicado no guia de pipelines.

1. Em Process → + Add a Schedule, selecione Manual.
2. No gerador, escolha a frequência desejada e copie a expressão para o campo Cron expression.
3. Confira o fuso horário, a conta em Run as e a prévia das próximas execuções antes de salvar.

Por exemplo, para executar de segunda a sexta às 8h, no fuso selecionado:

Expressão cron

0 0 8 ? * MON-FRI *

A expressão define os horários; o fuso é configurado separadamente na tela. Confira na prévia se as próximas datas correspondem ao que você planejou.

Passo 4: Confira a task e os logs

Abra a task em Activity Management e confirme que terminou com sucesso. Confira também os logs do processo: na primeira execução, procure três eventos item_processed e completed com total: 3. Depois da alteração de configuração, o total esperado é cinco.

Onde olhar	O que verificar
Activity Management → task → Logs	Estado e progresso da execução; logs que o código envia à task pelo CarolHandler do pyCarol
Data Apps → seu app → Logs	Saída do programa e logs do app; confira período, processo e versão nos filtros disponíveis
Explore → Query Editor	Logs centralizados para investigar build, stack traces e erros não encaminhados à task

Investigue erros no Explore

Nem todo erro aparece nos logs da task. Se o programa falhar antes de preparar o envio de logs pelo pyCarol, por exemplo, a mensagem pode aparecer apenas na saída do programa. Para investigar, confira a aba Logs do app ou consulte os logs pelo Explore.

1. Em Activity Management, abra a task da execução e copie o Task ID exibido nos detalhes.
2. Remova os hífens (-) do identificador.
3. No Explore → Query Editor, substitua ID_DA_TASK pelo valor sem hífens e execute a consulta:

select task_id, severity, severity_number, text_payload
from `ideia-dataops-prod.platform.carol_app_logs`
where task_id = 'ID_DA_TASK'
order by timestamp desc
limit 200;

Para procurar erros, acrescente ao WHERE:

and (
  severity_number >= 500
  or regexp_contains(text_payload, r'(?i)traceback|exception|error')
)

Uma linha do traceback pode ter severidade INFO, conforme a captura do console; por isso, não dependa somente da severidade. Se necessário, retire o filtro de erros e leia também as mensagens anteriores. A consulta completa está nos samples.

Saiba mais: como o pyCarol envia logs para a task

O programa usa o logging do Python para registrar mensagens. Cada handler define para onde elas serão enviadas. Neste exemplo, há dois destinos:

• StreamHandler: escreve na saída do programa. Na sua máquina, você vê as mensagens no terminal; na plataforma, essa saída é capturada nos logs do app.
• CarolHandler do pyCarol: envia as mensagens para a aba Logs da task que está executando o batch.

A plataforma informa o identificador dessa execução pela variável LONGTASKID. O código usa esse valor para associar os logs à task correta. No modo --local, usa apenas o StreamHandler, sem enviar mensagens para a plataforma.

O trecho abaixo mostra a configuração dos dois destinos quando há uma task:

# Saída do programa: terminal local ou logs do app.
logger.addHandler(logging.StreamHandler(sys.stdout))

# Logs da task: envio pelo pyCarol.
logger.addHandler(CarolHandler(carol, task_id=task_id))

# A mesma mensagem segue para os dois destinos.
logger.info("Iniciando o processamento")

O nível indica como interpretar a mensagem:

Chamada	Quando usar	Exemplo
logger.info(...)	Acompanhar o andamento normal	“3 itens processados”
logger.warning(...)	Avisar sobre uma situação que merece atenção	“Item sem campo opcional”
logger.error(...)	Registrar um problema	“Falha ao consultar a origem”

Registrar um erro e encerrar com falha são ações diferentes. logger.error(...) só escreve a mensagem; o programa continua executando. Se o problema impede a conclusão do batch, interrompa também o processamento. Por exemplo:

logger.error("Falha ao consultar a origem")
raise RuntimeError("Não foi possível concluir o processamento")

Se essa exceção não for tratada, o programa encerra com código de erro. Assim, a falha não fica apenas como uma mensagem em uma execução que aparenta sucesso.

Acompanhe o consumo

Use a calculadora de custos para estimar o custo das execuções e o Billing para conferir o consumo registrado.

Saiba mais: como estimar o custo deste batch

Na calculadora, selecione a máquina de processamento e informe o tamanho da instância, a duração média e a quantidade de execuções.

Por exemplo, uma rotina de cinco minutos, executada a cada hora por trinta dias, teria 720 execuções e 60 horas de processamento no mês. São valores ilustrativos, não um orçamento para este guia. Acrescente o consumo de armazenamento, ingestão ou consultas, se a sua rotina utilizar esses serviços.

A calculadora produz uma estimativa. Acompanhe o uso no Billing e ajuste a frequência e o tamanho da máquina após medir uma execução representativa. Deixar o agendamento ativo mantém o consumo recorrente.

Dúvidas e problemas comuns

Saiba mais: respostas às dúvidas frequentes sobre Data Apps Batch

Situação	O que fazer
Preciso configurar o GitHub em App config?	Não é necessário configurar a conexão com o GitHub em App config para construir a imagem de um Data App Batch. A origem do código para o build é definida pelos campos gitRepoUrl, gitBranch, gitPath e gitDockerfileName do manifest.json importado. A conexão em App config não substitui essa configuração. Se o repositório for privado, informe a credencial de acesso na etapa de build.
Fiz push do código. Por que o batch continua executando a versão anterior?	Push ou merge não atualizam uma imagem pronta. Após enviar as alterações ao repositório, faça um novo build e confira se o processo referencia a imagem e a tag desejadas. Depois, inicie uma nova execução.
O build terminou. Por que a rotina não executou?	O build constrói a imagem; a execução do batch é uma etapa separada. Acesse Process, localize o processo — batch_demo, neste tutorial — e clique em Run now ou Run, conforme a versão da interface. Acompanhe a task criada em Activity Management.
Por que há erro nos logs do app, mas não nos logs da task?	A aba Logs da task mostra as mensagens enviadas pelo código por meio do CarolHandler do pyCarol; a aba Logs do app mostra a saída do programa. Para investigar erros que não chegaram à task, consulte também Explore → Query Editor, na view ideia-dataops-prod.platform.carol_app_logs. Filtre task_id pelo Task ID sem hífens, copiado dos detalhes da execução em Activity Management. Veja a consulta pronta, com os registros mais recentes primeiro.
Reenviar o manifesto afeta meus agendamentos?	Sim. No comportamento atualmente identificado, reenviar o manifest.json pelo menu Files exclui o agendamento anteriormente configurado. Antes do envio, registre a frequência ou expressão cron, o fuso horário e a conta de Run as. Após a conclusão do deploy, recrie o agendamento e confira as próximas execuções.