Transloadit

Exportar arquivos para o Amazon S3

🤖/s3/store exporta resultados de codificação para o Amazon S3.

Robot /s3/store

Se você está começando a usar o Amazon S3, consulte nosso tutorial sobre como usar seu próprio bucket S3.

A URL do arquivo resultante no seu bucket S3 será retornada no Assembly Status JSON. Uma URL retornada não torna público um objeto privado nem concede acesso de leitura. Se o versionamento estiver habilitado no seu bucket S3, o ID da versão do arquivo será retornado em meta.version_id.

Limitar o acesso

Use uma identidade AWS dedicada, com acesso limitado ao bucket e ao prefixo de objeto de destino. Não use chaves de acesso do usuário root da AWS. Armazene o ID da chave de acesso, a chave de acesso secreta, o nome do bucket e a região dessa identidade como key, secret, bucket e bucket_region em Credenciais de Template e, em seguida, faça referência ao nome delas com credentials. Integrações de backend confiáveis podem, em vez disso, fornecer esses parâmetros diretamente; não exponha segredos da AWS em instruções enviadas pelo navegador.

O exemplo a seguir é uma política IAM baseada em identidade, anexada a essa identidade dedicada, e não uma política de bucket. Ela intencionalmente não tem Principal. Substitua {BUCKET_NAME} e use no Robot um path que comece com uploads/, ou adapte em conjunto o prefixo da política e o caminho.

Este exemplo cobre uploads e a limpeza de uploads multipart com falha, com bucket_region explícito, acl: "bucket-default", sem cabeçalhos de ACL/concessão, sem tags e com criptografia gerenciada pelo S3 (SSE-S3). Políticas de bucket existentes, controles da organização ou políticas de endpoint ainda podem negar o acesso.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "UploadAndAbortWithinPrefix",
      "Effect": "Allow",
      "Action": ["s3:PutObject", "s3:AbortMultipartUpload"],
      "Resource": "arn:aws:s3:::{BUCKET_NAME}/uploads/*"
    }
  ]
}

O processo de upload usa PutObject ou então CreateMultipartUpload, UploadPart e CompleteMultipartUpload; uploads multipart com falha podem acionar AbortMultipartUpload. A AWS associa as operações de upload bem-sucedidas a s3:PutObject. O acesso de gravação pode sobrescrever uma chave de objeto existente; ele não se limita a adicionar objetos. Escolha caminhos de objeto exclusivos e considere o versionamento para recuperação.

Adicione permissões apenas para os recursos que você usa, seguindo a referência de permissões por operação da AWS:

  • Sem um bucket_region explícito, a descoberta da região pode exigir s3:GetBucketLocation e, como alternativa, s3:ListBucket no ARN do bucket, arn:aws:s3:::{BUCKET_NAME}, sem sufixo de objeto. Informar a região correta evita essas solicitações de descoberta.
  • Cabeçalhos de ACL ou de concessão exigem s3:PutObjectAcl; tags exigem s3:PutObjectTagging no prefixo de objeto permitido. bucket-default não remove os cabeçalhos de ACL/concessão que você fornece em headers.
  • Baixar resultados privados exige uma autorização de leitura separada. Mesmo uma URL gerada com sign_urls_for exige que a identidade que a assina tenha as permissões de leitura adequadas.

O S3 aplica a configuração de criptografia do bucket quando nenhuma substituição de criptografia é enviada. Você pode solicitar SSE-KMS por meio de headers, usando x-amz-server-side-encryption: aws:kms e x-amz-server-side-encryption-aws-kms-key-id. Quando a criptografia padrão do bucket ou os cabeçalhos da solicitação selecionam SSE-KMS, a identidade que faz o upload precisa de kms:GenerateDataKey na chave relevante, além de kms:Decrypt para uploads multipart. Para uma chave gerenciada pelo cliente, conceda essas permissões com uma política de chave KMS compatível; a política base do S3 acima não as inclui. Não adicione concessões genéricas de kms:* ou sts:*.

Credenciais temporárias da AWS formam um conjunto correspondente de key, secret e session_token. Faça com que um backend confiável obtenha e renove os três valores e, em seguida, os forneça juntos quando ele criar a Assembly. Ele pode passá-los diretamente nas instruções do Robot ou salvá-los e atualizá-los em conjunto por meio da API de Credenciais de Template. Mantenha os três fora das instruções enviadas pelo navegador; substituir apenas o token de sessão não renova chaves de acesso expiradas. Este Robot repassa ao S3 as credenciais fornecidas; ele não assume uma função (role) nem renova credenciais expiradas. Mantenha as credenciais temporárias válidas durante o upload.

Exemplo de uso

Exporte arquivos carregados por upload para my_target_folder em um bucket do S3:

{
  "steps": {
    "exported": {
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "my_target_folder/${unique_prefix}/${file.url_name}",
      "robot": "/s3/store",
      "use": ":original"
    }
  }
}

Parâmetros

  • interpolate

    boolean | Record<string, boolean>

    Controla se as Assembly Variables são interpoladas em campos individuais de instruções.

    Por padrão, a maioria dos campos de instruções dos Robots interpola Assembly Variables. Defina isso como false para tratar todos os campos de instruções como texto literal, ou defina o caminho de um campo individual como false para tratar apenas esse campo como texto literal. Para campos específicos de um Robot que são literais por padrão, defina isso como true ou defina o caminho desse campo como true para voltar a usar a interpolação.

    Use nomes de campos como path ou caminhos com pontos como ffmpeg.vf para objetos aninhados.

  • output_meta

    Record<string, boolean> | boolean | Array<string>

    Permite especificar um conjunto de metadados cujo cálculo é mais custoso para a CPU e que, por isso, vem desativado por padrão para manter o processamento das suas Assemblies rápido.

    Para imagens, você pode adicionar "has_transparency": true neste objeto para extrair se a imagem contém partes transparentes e "dominant_colors": true para extrair um array de códigos de cores hexadecimais da imagem.

    Para imagens, você também pode adicionar "blurhash": true para extrair uma string BlurHash, uma representação compacta de um placeholder da imagem, útil para exibir uma prévia desfocada enquanto a imagem completa carrega.

    Para imagens, "thumbhash": true em vez disso extrai um ThumbHash codificado em base64 em meta.thumbhash, junto com meta.has_alpha (se existe um canal alfa, mesmo quando totalmente opaco). Ele descreve pixels orientados por EXIF e usa o primeiro quadro de imagens animadas. A extração é feita em regime de melhor esforço: imagens acima de 40 megapixels, formatos não suportados ou uma decodificação com falha/limitada não geram placeholder. Uma extração bem-sucedida adiciona uma cobrança de metadados equivalente a 20% dos bytes desse arquivo. Nenhuma sobretaxa de ThumbHash se aplica quando desativado ou quando nenhum hash é gerado.

    Defina essa opção no Step que produz a imagem, como /upload/handle para originais enviados por upload ou /image/resize para saídas processadas. Defini-la apenas em /transloadit/store não solicita a extração: o armazenamento preserva os metadados do produtor. O Transloadit Storage persiste um hash gerado com sua versão imutável e o retorna em resultados armazenados e em leituras nativas de ativos. Uploads diretos para o S3 não geram placeholders. Um placeholder contém informações da imagem, portanto proteja-o com os mesmos controles de acesso da imagem completa.

    Para vídeos, você pode adicionar o parâmetro "colorspace": true para extrair o espaço de cores do vídeo de saída.

    Para vídeos, você também pode adicionar "interlaced": true para detectar se o vídeo é entrelaçado. Isso combina a flag barata do ffprobe field_order com uma passagem de amostragem idet limitada sobre os primeiros quadros da origem, expondo interlaced, field_order e um objeto de diagnóstico interlace_detection em file.meta. Isso é computacionalmente caro e cobrado de acordo.

    Para áudio, você pode adicionar "mean_volume": true para obter um único valor que representa o volume médio do arquivo de áudio.

    Você também pode definir isso como false para pular a extração de metadados e acelerar a transcodificação.

  • user_meta

    Record<string, any>(padrão: {})

    Adiciona metadados JSON personalizados a cada arquivo emitido sem modificar seu conteúdo. Objetos e arrays aninhados são suportados.

    A herança depende do Robot. Os valores são mesclados com o user_meta existente no arquivo de saída; o Step atual substitui as chaves de nível superior com o mesmo nome. Atribua explicitamente as chaves necessárias quando um Robot criar novas saídas.

    Nos Steps de processamento, ${file.*} se refere à primeira entrada e ${result.*} ao arquivo emitido. Os valores são avaliados para cada saída após a execução do Robot, antes da extração subsequente de metadados e do armazenamento temporário. Em :original, os valores são avaliados para cada upload antes da extração de metadados.

    Os Steps subsequentes leem ${file.user_meta.key}. Consulte Metadados personalizados para ver um exemplo completo e as regras de herança.

  • result

    boolean(padrão: false)

    Se os resultados deste Step devem estar presentes no Assembly Status JSON

  • queue

    batch

    Definir a fila como “batch” rebaixa manualmente a prioridade dos Jobs deste Step, para evitar o consumo de vagas prioritárias de Jobs em Jobs que não precisam de tempo zero de espera na fila

  • force_accept

    boolean(padrão: false)

    Forçar um Robot a aceitar um tipo de arquivo que ele teria ignorado.

    Por padrão, os Robots ignoram arquivos que não conhecem. O 🤖/video/encode, por exemplo, ignora tranquilamente imagens de entrada.

    Com o parâmetro force_accept definido como true, você pode forçar os Robots a aceitar todos os arquivos enviados a eles. Isso normalmente leva a erros e só deve ser usado para depuração ou para lidar com casos extremos.

  • ignore_errors

    boolean | Array<meta | execute>(padrão: [])

    Ignorar erros durante fases específicas do processamento.

    Definir isso como ["meta"] fará com que o Robot ignore erros durante a extração de metadados.

    Definir isso como ["execute"] fará com que o Robot ignore erros durante a fase principal de execução.

    Definir isso como true equivale a ["meta", "execute"] e fará com que erros sejam ignorados nas duas fases.

  • use

    string | Array<string> | Array<object> | object

    Especifica quais Steps usar como entrada.

    • Você pode escolher qualquer nome para os Steps, exceto ":original" (reservado para uploads de usuários tratados pela Transloadit)
    • Você pode fornecer vários Steps como entrada usando arrays: 
      {
  "use": [
    ":original",
    "encoded",
    "resized"
  ]
}
    • Você também pode marcar os Steps de entrada com as para transmitir intenção semântica aos Robots: 
      {
  "use": [
    {
      "name": ":original",
      "as": "image"
    },
    {
      "name": ":original",
      "as": "mask"
    }
  ]
}

  • credentials

    string

    Crie as credenciais de Template correspondentes na sua conta da Transloadit e use o nome das suas credenciais de Template como valor deste parâmetro. Elas conterão os valores de bucket, key, secret e bucket_region do seu S3.

    Embora recomendemos sempre usar credenciais de Template, alguns casos de uso exigem credenciais dinâmicas, para os quais o uso de credenciais de Template é pouco prático devido à sua natureza estática. Se você tiver essa necessidade, pode usar os seguintes parâmetros no lugar delas: "bucket", "bucket_region" (por exemplo: "us-east-1" ou "eu-west-2"), "key", "secret".

  • path

    string(padrão: "${unique_prefix}/${file.url_name}")

    O caminho no qual o arquivo será armazenado. Ele pode incluir quaisquer Assembly Variables disponíveis. O caminho não deve ser um diretório.

  • url_prefix

    string(padrão: "http://{bucket}.s3.amazonaws.com/")

    O prefixo de URL usado para a URL retornada, como "http://my.cdn.com/some/path/".

  • acl

    authenticated-read | aws-exec-read | bucket-default | bucket-owner-full-control | bucket-owner-read | private | public | (padrão: "public-read")

    A ACL usada para este arquivo. É compatível com as ACLs predefinidas para objetos da AWS. Outros provedores compatíveis com S3 podem oferecer suporte a ACLs diferentes. O padrão continua sendo "public-read", o que pode entrar em conflito com o S3 Block Public Access e com ACLs desabilitadas. Para buckets privados modernos, defina explicitamente "bucket-default" para omitir o cabeçalho de ACL gerado e não forneça cabeçalhos de ACL/concessão em headers. "private" ainda envia uma ACL.

  • check_integrity

    boolean(padrão: false)

    Calcule e envie a soma de verificação do arquivo para que o S3 verifique sua integridade após o upload, o que pode ajudar com problemas ocasionais de corrupção de arquivos.

    Habilitar esta opção aumenta o tempo total de execução, pois a verificação de integridade pode exigir uso intensivo de CPU, especialmente para arquivos maiores.

  • headers

    Record<string, string>(padrão: {"Content-Type":"${file.mime}"})

    Um objeto contendo uma lista de cabeçalhos a serem definidos para este arquivo no S3, como { FileURL: "${file.url_name}" }. Isso também pode incluir quaisquer Assembly Variables disponíveis. Você pode encontrar uma lista de cabeçalhos disponíveis aqui.

    Os metadados do objeto podem ser especificados usando cabeçalhos x-amz-meta-*. Observe que esses cabeçalhos não aceitam valores de metadados com caracteres fora de ASCII.

  • tags

    Record<string, string>(padrão: {})

    A marcação de objetos com tags permite categorizar o armazenamento. Você pode associar até 10 tags a um objeto. As tags associadas a um objeto devem ter chaves de tag exclusivas.

  • host

    string(padrão: "s3.amazonaws.com")

    O host do serviço de armazenamento usado. Só é necessário definir este parâmetro quando o serviço de armazenamento usado não é o Amazon S3, mas tem uma API compatível (como hosteurope.de). O protocolo padrão usado é HTTP; para qualquer outro, o protocolo precisa ser especificado explicitamente. Por exemplo, adicione o prefixo https:// ou s3:// ao host para usar o protocolo correspondente.

  • no_vhost

    boolean(padrão: false)

    Defina como true se você usar um host personalizado e encontrar erros de acesso negado.

  • sign_urls_for

    string | number

    Este parâmetro fornece URLs assinadas no JSON de resultado (nas propriedades signed_url e signed_ssl_url). O número definido neste parâmetro é o prazo de expiração da URL em segundos. Se este parâmetro não for usado, nenhuma assinatura de URL será realizada.

  • session_token

    string

    O token de sessão que pertence ao ID da chave de acesso e à chave de acesso secreta temporários da AWS fornecidos para este upload. O Robot não assume uma função (role) nem renova essas credenciais; elas precisam permanecer válidas durante o upload.

Demonstrações

Publicações relacionadas no blog