Principais pontos
- Importe um objeto delimitado ou uma página de um prefixo, em vez de iniciar uma regravação ilimitada em todo o bucket.
- Grave os derivados em um prefixo distinto para que importações recursivas não possam processar as próprias saídas.
- Use o redimensionamento com fit e um tamanho máximo explícito para preservar a proporção, e defina zoom como false para que originais menores não sejam ampliados.
Um reprocessamento retroativo de imagens não é uma edição no local. É uma migração repetível de um objeto de origem conhecido para um derivado versionado, cuja qualidade, dimensões, destino e referência na aplicação podem ser verificados de forma independente. Manter a importação e a exportação no Google Cloud Storage preserva a propriedade do armazenamento e, ao mesmo tempo, tira o processamento de mídia dos servidores da aplicação.
O que mais importa
- Prefira credenciais de Template separadas para leitura e gravação, com as permissões mínimas de que cada Step precisa.
- Mantenha as saídas privadas até que a aplicação as verifique e altere deliberadamente as referências de entrega.
- Persista a geração ou a identidade de versão da origem, a versão do fluxo de trabalho e o caminho de destino para permitir uma reexecução segura.
Trate o trabalho como um reprocessamento retroativo versionado
Não sobrescreva uma biblioteca de imagens só porque um novo formato ou dimensão parece melhor em um único arquivo de teste. Defina primeiro a população de origem, a versão da transformação, o namespace de saída, as verificações de aceitação e a migração das referências. O objeto original deve continuar recuperável até que o derivado tenha sido verificado e os consumidores tenham migrado com segurança.
Use caminhos de saída com escopo de versão para que duas políticas de transformação possam coexistir durante a implantação e a reversão continue sendo uma mudança de referência. O caminho de exemplo é exclusivo de cada execução, em vez de derivado do objeto de origem, então a aplicação precisa evitar processamento duplicado consultando seu próprio registro de origem para resultado antes de criar outra Assembly.
Separe os namespaces de entrada e de saída
Um Step /google/import recursivo pode enumerar um prefixo de origem. Se /google/store gravar sob esse mesmo prefixo, uma página posterior ou uma nova execução pode importar derivados gerados como se fossem originais. Coloque as saídas em um prefixo que não se sobreponha ao de origem ou em um bucket separado, e deixe a distinção evidente na configuração e no monitoramento.
Para um prefixo grande, processe uma página limitada e preserve next_page_token fora da Assembly para a próxima chamada. O exemplo define fields.next_page_token como uma string vazia por padrão para a primeira página. Um agendador confiável fornece o token retornado nesse campo para cada Assembly subsequente, sem desbloquear os Steps. O conteúdo do bucket pode mudar durante uma migração, então combine a paginação com um manifesto da aplicação ou um inventário de origem quando for importante garantir que cada item seja coberto exatamente uma vez.
Prefixo de origem
Contém apenas os originais selecionados para a política de migração atual.
Prefixo de saída
Contém derivados versionados e nunca é percorrido pela importação de origem.
Manifesto de migração
Mapeia a identidade de origem para a versão do fluxo de trabalho, o Assembly ID e o objeto de destino.
Crie o Template de imagens do Google Storage
O Step de importação seleciona um arquivo ou um prefixo limitado, /image/resize cria um WebP cujas dimensões cabem na caixa escolhida, e /google/store grava o derivado como privado. Defina zoom como false quando originais pequenos não devem ser ampliados. Revise o comportamento de transparência e de cor antes de tornar o WebP o contrato para todas as famílias de origem.
O exemplo usa nomes de credencial distintos para acesso de leitura e de gravação. A credencial de leitura precisa de acesso aos objetos de origem; a de gravação precisa poder criar objetos no destino. Adicione permissão de exclusão apenas quando uma política intencional de sobrescrita exigir.
{
"allow_steps_override": false,
"fields": { "next_page_token": "" },
"steps": {
"source_images": {
"robot": "/google/import",
"credentials": "gcs-source-read",
"path": "originals/catalog/",
"recursive": true,
"next_page_token": "${fields.next_page_token}",
"files_per_page": 100
},
"web_derivatives": {
"use": "source_images",
"robot": "/image/resize",
"width": 1600,
"height": 1200,
"resize_strategy": "fit",
"zoom": false,
"format": "webp"
},
"gcs_output": {
"use": "web_derivatives",
"robot": "/google/store",
"credentials": "gcs-output-write",
"path": "derived/web-v1/${assembly.id}/${unique_prefix}/${file.url_name}",
"acl": "private",
"result": true
}
}
}Valide a qualidade das imagens e o comportamento dos objetos
Use arquivos de teste que cubram orientação EXIF, transparência, perfis de cor incorporados, dimensões muito grandes, arquivos de origem pequenos, animação, arquivos malformados e objetos com o mesmo nome em pastas diferentes. Compare a aparência renderizada, além de dimensões, formato e tamanho em bytes. Uma saída menor que altere a cor ou remova uma animação necessária não é uma migração bem-sucedida.
Defina a ACL deliberadamente. O schema de /google/store usa public-read como ACL padrão, então um fluxo de trabalho de revisão privado precisa sobrescrevê-la. Adicione uma política de cache apenas quando ela corresponder ao modelo definitivo de entrega e de autorização.
Implante com pontos de controle e reversão
Registre cada objeto de origem e cada resultado de destino antes de alterar as referências dos consumidores. Reconcilie itens ausentes ou com falha pela identidade de origem em vez de executar novamente o prefixo completo. Se uma página falhar antes de terminar, tente novamente apenas os objetos de origem que a aplicação não registrou como concluídos. O caminho de exemplo é exclusivo de cada execução, então processar a mesma origem novamente grava um novo objeto; a eliminação de repetições vem do registro de origem para resultado da aplicação, consultado antes de a Assembly ser criada.
Mova uma pequena parcela do tráfego para os novos caminhos, compare bytes e métricas visuais e depois amplie. Mantenha os originais e as referências anteriores da aplicação até que a janela de reversão termine. Excluir objetos de origem é uma decisão de retenção separada e nunca deve ser um Step final implícito do processamento de imagens.
Meça a migração como uma carga de trabalho operacional
Acompanhe objetos importados, objetos processados, bytes de saída, falhas por classe, novas tentativas e entradas do manifesto não resolvidas. Compare a economia obtida com os derivados com os custos de importação, processamento, exportação, armazenamento e da futura entrega. Um reprocessamento retroativo que reduz bytes, mas não pode ser retomado nem auditado, não está operacionalmente completo.
Crie alertas para páginas travadas, identidades de origem repetidas, gravações fora do prefixo de destino e ACLs públicas inesperadas. Mantenha um nível de concorrência limitado para que o processamento e a atividade na API do Google não concorram com o tráfego normal da aplicação nem esgotem os limites operacionais do destino.
Detalhes técnicos que vale a pena conhecer
- /google/import aceita um caminho de arquivo, um caminho de diretório terminado em barra ou um array de caminhos. Importações recursivas de diretório paginam com next_page_token e files_per_page, e o token para a próxima chamada é retornado nos metadados dos arquivos importados. Isso difere de /supabase/import, que pagina com page_number.
- /image/resize com resize_strategy definido como fit preserva a proporção e mantém cada lado dentro dos limites solicitados.
- /image/resize usa o formato de entrada quando format é null; definir format como webp cria deliberadamente um derivado WebP.
- /google/store pode definir o caminho do objeto, a ACL, os metadados Cache-Control e modelos de URL de resultado. Sua ACL padrão documentada é public-read, então private precisa ser definido explicitamente em um fluxo de trabalho com revisão antes da publicação.
- Credenciais do Google somente de gravação precisam de storage.objects.create; storage.objects.delete só é necessário quando o fluxo de trabalho sobrescreve intencionalmente caminhos existentes. A documentação de credenciais do Google vinculada descreve apenas a função de gravação, então consulte a documentação de IAM do Google Cloud para saber de quais permissões a credencial de importação precisa.
- Usar o mesmo provedor na origem e no destino não exige a mesma credencial, o mesmo bucket nem a mesma chave. Separar a autoridade de leitura e a de gravação reduz o impacto de uma credencial de Template comprometida.
Uma abordagem prática
- 1
Escolha um prefixo de origem representativo e defina um namespace de saída sem sobreposição.
- 2
Crie credenciais de leitura e gravação com escopo restrito e salve o Template de importação, redimensionamento e armazenamento.
- 3
Processe uma única página delimitada e compare dimensões, cor, transparência, bytes e metadados dos objetos.
- 4
Faça a implantação gradual com pontos de controle, registros idempotentes e uma migração de referências reversível.
Quando a Transloadit é útil
Use /google/import para selecionar um único objeto ou um prefixo paginado, /image/resize para criar o derivado revisado e /google/store para gravar uma saída privada. Separe as credenciais de leitura e gravação quando possível e nunca coloque saídas sob um prefixo que a próxima importação vá ingerir novamente.
Limite da arquitetura
O Google Cloud Storage continua sendo a origem e o destino duráveis. A Transloadit lê os objetos selecionados, cria derivados de imagem e grava novos objetos, enquanto a aplicação é responsável pelo inventário, pela implantação gradual, pela exclusão, pelo versionamento e pela decisão de substituir referências.
Perguntas frequentes
O fluxo de trabalho pode sobrescrever o objeto de origem?
O fluxo de trabalho pode receber permissão para excluir e gravar, mas um destino versionado é mais seguro. Esse destino permite revisão, reversão e coexistência enquanto os consumidores migram.
A importação e o armazenamento podem usar as mesmas credenciais do Google?
Podem, mas credenciais separadas de leitura e gravação reduzem a autoridade concedida e facilitam a auditoria da fronteira entre origem e destino.
Por que o prefixo de saída precisa ser separado?
Caso contrário, uma importação recursiva pode descobrir derivados anteriores e processá-los novamente, multiplicando objetos e degradando a qualidade.
O redimensionamento com fit sempre cria a largura e a altura solicitadas?
Não. O modo fit preserva a proporção e mantém cada lado dentro dos limites. Dimensões exatas exigem outra estratégia e uma decisão explícita de recorte ou preenchimento.
Os derivados devem ser públicos?
Mantenha-os privados durante a validação. Escolha acesso público ou uma camada de entrega depois, de acordo com o modelo de autorização e de cache da aplicação.