Principais pontos
- Aceite uma única imagem de produto autorizada e limite seu tamanho em bytes antes do início do processamento pago.
- Crie um derivado WebP versionado com redimensionamento fit e zoom desativado, para que origens pequenas não sejam ampliadas.
- Mantenha a conta, o contêiner e a chave do Azure nas Credenciais de Template, e não em campos da Assembly nem em código do navegador.
Imagens de produtos costumam chegar como arquivos de câmera grandes demais, enquanto as páginas do catálogo precisam de um ativo de entrega previsível. Fazer upload da origem diretamente para o Azure deixa formato, dimensões, metadados, comportamento de cache e acesso de revisão a cargo de caminhos de código separados. Um Template bloqueado de três etapas gera um único derivado cuja identidade de armazenamento durável e cuja URL de revisão temporária têm funções diferentes; as configurações da conta e do contêiner do Azure definem o limite de acesso anônimo.
O que mais importa
- Defina deliberadamente o Content-Type e um Cache-Control seguro para a revisão, em vez de depender de suposições do destino.
- Trate uma URL SAS como acesso temporário ao portador (bearer) e armazene o caminho do blob, e não a URL assinada, como identidade durável.
- Reconcilie a exportação bem-sucedida com o produto, a versão de origem, a versão do fluxo de trabalho e o Assembly ID exatos antes da publicação.
Modele a identidade de origem, de processamento e de armazenamento
Uma foto de produto enviada por upload é a entrada de um fluxo de trabalho, não um evento de publicação no catálogo. Autentique quem faz o upload, autorize o registro do produto, valide o tipo de imagem detectado e o tamanho em bytes e crie uma operação de processamento durável antes de aceitar o resultado da Assembly. Mantenha a origem editável ou em alta resolução sob uma política de retenção explícita, em vez de presumir que o derivado WebP pode substituí-la.
Atribua uma versão do fluxo de trabalho a cada derivado. O registro da aplicação deve mapear o produto e a versão de origem para esse fluxo de trabalho, o Assembly ID correspondente e o contêiner e o caminho do blob resultantes no Azure. Isso permite que uma mudança posterior de qualidade crie um novo derivado sem sobrescrever a versão revisada nem perder o rastro de volta à sua origem.
Identidade de origem
O produto, o upload original, o checksum ou a versão e a função de retenção.
Identidade de processamento
A versão salva do fluxo de trabalho e a Assembly que produziu o derivado.
Identidade de armazenamento
O limite da conta do Azure, o contêiner e o caminho versionado do blob.
Crie o Template para imagens de produto armazenadas no Azure
O Template aceita um único arquivo por meio de :original, o envia para /image/resize e exporta apenas o WebP resultante por meio de /azure/store. O redimensionamento no modo fit mantém a imagem completa dentro da caixa solicitada, enquanto zoom definido como false impede que uma origem pequena seja ampliada. O caminho versionado combina um identificador de produto, fornecido somente após a autorização da aplicação, com um elemento exclusivo da Assembly.
Defina allow_steps_override como false para que um cliente de upload não possa substituir o destino, solicitar uma carga de trabalho maior nem ignorar o processamento. O objeto auth do Template limita a quantidade e o tamanho total dos uploads aceitos. Esses limites reduzem cargas de trabalho acidentais, mas a aplicação ainda precisa impor o vínculo de propriedade com o tenant, o estado permitido do produto, limites de taxa e um valor permitido de product_id.
{
"allow_steps_override": false,
"auth": {
"max_number_of_files": 1,
"max_size": 52428800
},
"steps": {
":original": {
"robot": "/upload/handle"
},
"product_webp": {
"use": ":original",
"robot": "/image/resize",
"width": 1600,
"height": 1600,
"resize_strategy": "fit",
"zoom": false,
"format": "webp",
"quality": 82,
"strip": true
},
"azure_review": {
"use": "product_webp",
"robot": "/azure/store",
"credentials": "azure-product-images",
"path": "catalog/web-v1/${fields.product_id}/${assembly.id}/${file.url_name}",
"content_type": "image/webp",
"cache_control": "private, no-store",
"metadata": {
"workflow": "catalog-web-v1",
"source_id": "${fields.product_id}"
},
"sas_expires_in": 900,
"sas_permissions": "r",
"result": true
}
}
}Defina as propriedades e os metadados do blob como parte do contrato do ativo
Um WebP versionado deve sair do fluxo de trabalho com um Content-Type explícito. O exemplo usa cache private, no-store durante a revisão para que uma resposta com SAS expirável não seja retida por um cache compartilhado. Como /azure/store grava cache_control no blob armazenado, esse valor private, no-store persiste no objeto. Para servir o mesmo blob depois com uma política de cache, é preciso redefinir o Cache-Control dele ou produzir um novo derivado, em vez de presumir que o valor do período de revisão se apaga sozinho. Armazene metadados estáveis e não sensíveis, como o nome do fluxo de trabalho e o identificador do registro de origem, quando os operadores precisarem rastrear um blob sem abrir o banco de dados da aplicação.
Não coloque segredos, informações pessoais nem um valor sem limite vindo do navegador em metadados ou caminhos do Azure. Trate product_id como um identificador validado da aplicação, com limite documentado de caracteres e de comprimento. /azure/store converte valores de metadados do tipo string, number e boolean em strings, portanto os consumidores não devem esperar que os tipos JSON originais sejam preservados.
Use uma URL SAS somente para revisão de curta duração
/azure/store retorna a URL assinada no campo sas_url do resultado; o campo url comum não é assinado. O upload cria uma SAS mesmo quando sas_expires_in é omitido, usando uma duração padrão do servidor. Omitir sas_permissions resulta em um padrão com permissão de escrita, não em acesso somente leitura. Este exemplo define explicitamente sas_permissions como r e sas_expires_in como 900 segundos. Defina ambos os valores em vez de depender dos padrões para o acesso de revisão.
O Robot não configura acesso anônimo. Mantenha o contêiner de destino privado e verifique a configuração AllowBlobPublicAccess da conta de armazenamento; desativar o acesso anônimo no nível da conta prevalece sobre as configurações do contêiner. Qualquer pessoa que obtenha a URL SAS pode usar o acesso delegado dela durante o período de validade, portanto não a registre em logs, não a inclua em ferramentas de análise, não a envie a clientes não relacionados nem a armazene como a URL permanente do ativo no catálogo.
Persista o contêiner e o caminho do blob como identidade durável. Quando um revisor precisar de acesso mais tarde, a aplicação deve autorizar essa solicitação e emitir ou obter o acesso de acordo com o design de entrega atual dela. Uma leitura bem-sucedida pela SAS prova que o objeto pode ser lido com esse token; ela não aprova o ativo, não concede a publicação no catálogo nem substitui a autorização no nível do produto.
Verifique o comportamento das imagens antes da virada do catálogo
O Step de redimensionamento define strip como true, o que remove do derivado todos os metadados incorporados, incluindo o perfil de cor ICC. Teste a orientação EXIF, imagens largas e altas, entradas transparentes, o comportamento do perfil de cor, origens muito pequenas, dimensões muito grandes, animação e dados malformados. Compare a saída renderizada, além do tipo MIME, das dimensões, do tamanho em bytes e dos metadados de armazenamento. A remoção do perfil e a conversão para WebP podem, cada uma, afetar a cor renderizada ou outro comportamento exigido.
Verifique se as configurações da conta e do contêiner do Azure impedem leituras anônimas do blob de revisão. Reconcilie a exportação bem-sucedida com a operação de produto esperada e, em seguida, avance o registro do catálogo por meio de uma transição autorizada separada. Libere primeiro para uma pequena parcela do tráfego, observe o comportamento de entrega e de cache e mantenha o derivado anterior até o fim da janela de reversão.
Recupere o fluxo de trabalho sem publicar duplicatas
Um tempo limite esgotado ou um webhook não recebido é um resultado incerto, não uma prova de que o blob não foi gravado. Armazene a operação antes de criar a Assembly e processe as notificações de conclusão assinadas de forma idempotente. Se o chamador perder a resposta, inspecione a Assembly existente e o registro da aplicação antes de iniciar outra execução.
Classifique as falhas por recebimento, processamento de imagem, autenticação no Azure, contêiner ausente e exportação. Exponha ações de recuperação estáveis aos operadores, mantendo protegidos os detalhes brutos do provedor. Uma nova execução do fluxo de trabalho deve criar um novo objeto versionado e atualizar o catálogo somente após a revisão; a exclusão do blob antigo cabe a uma rotina de retenção posterior.
Detalhes técnicos que vale a pena conhecer
- /upload/handle deve se chamar :original, não deve definir use e só pode aparecer uma vez em um conjunto de Assembly Instructions.
- /image/resize com resize_strategy definido como fit preserva a proporção e mantém cada lado dentro dos limites solicitados. Definir zoom como false impede a ampliação de entradas menores.
- /azure/store aplica content_type, content_encoding, content_language, cache_control e metadados ao blob armazenado. Ele aceita content_disposition, mas atualmente não o aplica ao blob.
- /azure/store retorna acesso assinado para revisão em sas_url; o campo url comum não é assinado. sas_expires_in controla o tempo de vida, com um padrão do servidor quando omitido. Se sas_permissions for omitido, é usado um padrão com permissão de escrita; valores explícitos aceitam r (leitura), w (escrita) e d (exclusão). Este fluxo de trabalho concede apenas r para revisão.
- /azure/store não tem parâmetro de nível de acesso. O acesso anônimo depende tanto da configuração AllowBlobPublicAccess da conta de armazenamento quanto do nível de acesso anônimo do contêiner. Desativar o acesso anônimo no nível da conta prevalece sobre a configuração do contêiner.
- Uma URL SAS concede suas permissões delegadas a qualquer pessoa que a possua durante o período de validade da assinatura.
- Os valores de metadados do Azure fornecidos a /azure/store podem ser strings, números ou booleanos; o Robot os converte em strings.
Uma abordagem prática
- 1
Defina os tipos de imagem aceitos, o número máximo de bytes, as dimensões de destino, a qualidade e a política de retenção da origem.
- 2
Crie Credenciais de Template do Azure com escopo restrito e salve o Template bloqueado de upload, redimensionamento e armazenamento.
- 3
Teste o contêiner real com arquivos de teste de orientação, transparência e perfil de cor, além de arquivos de teste incomumente pequenos e grandes.
- 4
Reconcilie o caminho do blob, revise pela SAS de curta duração e depois publique por meio de uma transição separada no catálogo.
Quando a Transloadit é útil
Use /upload/handle para o recebimento controlado de imagens de produtos, /image/resize para um derivado WebP com limites definidos e /azure/store para um blob versionado em um contêiner de acesso privado. Deixe que o Step de armazenamento retorne uma URL SAS somente leitura e de curta duração para revisão, mas persista o contêiner e o caminho do blob como identidade durável.
Limite da arquitetura
A Transloadit recebe a imagem do produto, cria um derivado WebP e o grava em um contêiner do Azure Blob Storage que o administrador do Azure ou a aplicação configurou para acesso privado. A aplicação continua responsável pela autorização de produtos, pela retenção da origem, pelo estado do catálogo, pela política de entrega e por toda decisão de expor ou substituir o derivado.
Perguntas frequentes
O catálogo deve armazenar a URL SAS?
Não. Uma URL SAS é um acesso temporário do tipo bearer. Armazene o contêiner do Azure e o caminho do blob como identidade durável e autorize a entrega posterior de forma independente.
O redimensionamento com fit cria um quadrado exato?
Não. Ele preserva a proporção e mantém ambos os lados dentro dos limites solicitados. Use uma política explícita de corte ou preenchimento quando forem necessárias dimensões exatas.
Por que usar um caminho de blob versionado?
Ele permite que políticas de qualidade coexistam, torna o comportamento do cache previsível e oferece suporte a revisão e reversão sem sobrescrever um ativo conhecido.
O navegador pode escolher o contêiner do Azure?
Não. Mantenha a conta, o contêiner e a chave na credencial de Template bloqueada. Uma aplicação confiável pode fornecer um identificador de produto limitado somente após a autorização.
Uma exportação bem-sucedida publica a imagem do produto?
Não. Ela prova que o derivado chegou ao Azure. A publicação no catálogo continua sendo uma transição de estado separada da aplicação.