Uploads compostos paralelos

Uma estratégia para fazer o upload de arquivos grandes é chamada de uploads compostos paralelos. Nesse upload, um arquivo é dividido em até 32 partes, os blocos são enviados em paralelo aos objetos temporários, o objeto final é recriado usando os objetos temporários e o objetos temporários são excluídos.

Os uploads compostos paralelos podem ser significativamente mais rápidos quando a velocidade do disco e da rede não estão limitando os fatores. No entanto, o objeto final armazenado no seu bucket é um objeto composto, que tem apenas um hash crc32c, não um hash MD5. Como resultado, você precisa usar o crcmod para executar verificações de integridade ao fazer o download do objeto com aplicativos Python. Só faça uploads compostos paralelos se o seguinte for aplicável:

  • Os objetos enviados não precisam ter um hash MD5.

  • Qualquer usuário do Python, incluindo gsutil usuários, que precisa fazer o download dos seus objetos tem o google-crc32c ou o crcmod instalado.

    Por exemplo, se você usar o Python para fazer upload de recursos de vídeo que são veiculados apenas por um aplicativo Java, os uploads compostos paralelos são uma boa escolha, porque há implementações CRC32C eficientes disponíveis em Java.

Funções exigidas

Para receber as permissões necessárias para fazer uploads compostos paralelos, peça ao administrador para conceder a você o papel do IAM de Usuário de objetos do Storage (roles/storage.objectUser) no bucket.

O papel de Administrador do Storage (roles/storage.admin) contém as permissões necessárias para fazer upload, ler e excluir partes de objetos. Ele também contém a permissão necessária para que a CLI gcloud execute uma verificação de compatibilidade no nível do bucket com uploads compostos paralelos. Se você não conseguir o papel de Administrador do Storage (roles/storage.admin), ainda poderá fazer uploads compostos paralelos usando a CLI gcloud. Para isso, receba o papel de Usuário de objetos do Storage (roles/storage.objectUser) e desative a propriedade storage/parallel_composite_upload_compatibility_check. Para mais informações, consulte a guia Linha de comando na seção Como as ferramentas e as APIs usam uploads compostos paralelos.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Para instruções sobre como conceder papéis nos buckets, consulte Definir e gerenciar políticas do IAM em buckets.

Como as ferramentas e as APIs usam uploads compostos paralelos

Dependendo de como você interage com o Cloud Storage, os uploads compostos paralelos podem ser gerenciados automaticamente em seu nome. Nesta seção, descrevemos o comportamento do upload composto paralelo para diferentes ferramentas e damos informações sobre como modificar o comportamento.

Console

O Google Cloud console não faz uploads compostos paralelos.

Linha de comando

As propriedades a seguir funcionam juntas para determinar como e quando a CLI gcloud faz uploads compostos paralelos:

  • storage/parallel_composite_upload_enabled: propriedade para ativar uploads compostos paralelos. Se False, desativa os uploads compostos paralelos e ignora as verificações de compatibilidade no nível do bucket. Se True ou None, ativa uploads compostos paralelos para objetos que atendem aos critérios definidos nas outras propriedades e ativa as verificações de compatibilidade. A configuração padrão é None.

  • storage/parallel_composite_upload_compatibility_check: propriedade para alternar as verificações de compatibilidade e segurança no nível do bucket com uploads compostos paralelos. Se True, a CLI gcloud envia uma solicitação GET para os metadados do bucket de destino antes de tentar um upload composto paralelo, o que exige que o principal tenha a permissão storage.buckets.get. A CLI gcloud só faz uploads compostos paralelos quando todas as condições a seguir são atendidas:

    A configuração padrão é True. Se False, a CLI gcloud não executa a verificação de compatibilidade.

    Definir storage/parallel_composite_upload_compatibility_check como False não desativa uploads compostos paralelos. Quando storage/parallel_composite_upload_compatibility_check está definido como False e storage/parallel_composite_upload_enabled é None ou True, a CLI gcloud ignora a verificação do bucket e prossegue diretamente com um upload composto paralelo.

    Para ignorar essa verificação, desative a propriedade storage/parallel_composite_upload_compatibility_check:

    gcloud config set storage/parallel_composite_upload_compatibility_check False

  • storage/parallel_composite_upload_threshold: o tamanho total mínimo do arquivo para fazer um upload composto paralelo. A configuração padrão é 150 MiB.

  • storage/parallel_composite_upload_component_size: o tamanho máximo de cada objeto temporário. A property será ignorada se o tamanho total do arquivo for tão grande que exija mais de 32 partes desse tamanho.

  • storage/parallel_composite_upload_component_prefix: o prefixo usado ao nomear objetos temporários. Essa property pode ser definida como um caminho absoluto ou como um caminho relativo para o objeto final. Veja a descrição da property para mais informações. O prefixo padrão é o caminho absoluto /gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details.

É possível modificar essas properties criando uma configuração nomeada e aplicando a configuração por comando usando a --configuration flag em todo o projeto ou para todos os comandos da CLI gcloud usando o gcloud config set comando.

Não é preciso mais espaço em disco local ao usar a CLI gcloud para fazer uploads compostos paralelos. Se um upload composto paralelo falhar antes da composição, execute o comando da CLI gcloud novamente para aproveitar os uploads retomáveis para os objetos temporários que falharam. Os objetos temporários que foram transferidos antes da falha não serão transferidos de novo quando você retomar o upload.

Objetos temporários serão nomeados da seguinte maneira:

TEMPORARY_PREFIX/RANDOM_VALUE_HEX_DIGEST_COMPONENT_ID

Em que:

  • O TEMPORARY_PREFIX é controlado pela propriedade storage/parallel_composite_upload_component_prefix.
  • RANDOM_VALUE é um valor numérico aleatório.
  • HEX_DIGEST é um hash derivado do nome do recurso de origem.
  • COMPONENT_ID é o número sequencial do componente.

Geralmente, os objetos temporários são excluídos no final de um upload composto paralelo, mas, para evitar que os objetos temporários sejam mantidos, você precisa verificar o status de saída do comando da CLI gcloud e excluir manualmente qualquer objeto temporário que foi transferido por algum upload cancelado.

Bibliotecas de cliente

Java

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

É possível executar uploads compostos paralelos definindo AllowParallelCompositeUpload como true. Por exemplo:

import com.google.cloud.storage.transfermanager.ParallelUploadConfig;
import com.google.cloud.storage.transfermanager.TransferManager;
import com.google.cloud.storage.transfermanager.TransferManagerConfig;
import com.google.cloud.storage.transfermanager.UploadResult;
import java.io.IOException;
import java.nio.file.Path;
import java.util.List;

class AllowParallelCompositeUpload {

  public static void parallelCompositeUploadAllowed(String bucketName, List<Path> files)
      throws IOException {
    TransferManager transferManager =
        TransferManagerConfig.newBuilder()
            .setAllowParallelCompositeUpload(true)
            .build()
            .getService();
    ParallelUploadConfig parallelUploadConfig =
        ParallelUploadConfig.newBuilder().setBucketName(bucketName).build();
    List<UploadResult> results =
        transferManager.uploadFiles(files, parallelUploadConfig).getUploadResults();
    for (UploadResult result : results) {
      System.out.println(
          "Upload for "
              + result.getInput().getName()
              + " completed with status "
              + result.getStatus());
    }
  }
}

Node.js

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

A biblioteca de cliente do Node.js não é compatível com uploads compostos paralelos. Em vez disso, use uploads de várias partes da API XML.

Python

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em Configurar a autenticação para bibliotecas de cliente.

A biblioteca de cliente do Python não é compatível com uploads compostos paralelos. Em vez disso, use uploads de várias partes da API XML.

APIs REST

API JSON

A API JSON permite fazer upload de partes de objetos em paralelo e recombiná-las em um único objeto usando a compose operação.

Informações importantes ao desenvolver o código para uploads compostos paralelos:

  • Ao usar a operação compose, é possível excluir os objetos de origem de forma irreversível como parte do processo de composição. Use essa opção para minimizar o faturamento de objetos temporários que não precisam ser protegidos pela exclusão reversível ou pelo controle de versões de objetos.

  • Para prevenir alterações em objetos de origem entre as solicitações de upload e de composição, os usuários precisam fornecer um número de geração esperado para cada origem.

API XML

A API XML permite fazer upload de partes de objetos em paralelo e recombiná-las em um único objeto usando a compose operação.

Informações importantes ao desenvolver o código para uploads compostos paralelos:

  • Ao usar a operação compose, os objetos de origem não são afetados pelo processo de composição.

    Isso significa que, se eles forem temporários, você precisará excluí-los logo depois de concluir a composição ou então os objetos de origem permanecerão no bucket e serão cobrados de acordo.

  • Para prevenir alterações em objetos de origem entre as solicitações de upload e de composição, os usuários precisam fornecer um número de geração esperado para cada origem.

Solução de problemas

Esta seção contém informações sobre como solucionar problemas de erros da CLI gcloud que podem ocorrer com uploads compostos paralelos.

Não é possível verificar se o bucket de destino é compatível com uploads compostos paralelos

Problema: ao fazer upload de um arquivo de 150 MiB ou maior usando gcloud storage cp ou gcloud storage mv, o comando registra a seguinte mensagem uma vez, mas o upload é concluído com o código de saída 0:

ERROR: Cannot check if the destination bucket is compatible for running
parallel composite uploads as the user does not permission to perform GET
operation on the bucket. The operation will be performed without parallel
composite upload feature and hence might perform relatively slower.

Solução: a CLI gcloud está tentando executar a verificação de compatibilidade de upload composto paralelo. O principal não tem a permissão storage.buckets.get no bucket de destino, então a solicitação de metadados do bucket é negada. A CLI gcloud processa o erro internamente e não mostra um código de status HTTP. Em vez disso, ele registra a mensagem e volta para um upload normal.

Se você quiser uploads compostos paralelos, verifique se o principal tem as permissões storage.buckets.get, storage.objects.get e storage.objects.delete no bucket de destino. Essas permissões podem ser concedidas pelo papel de Administrador do Storage (roles/storage.admin). Como alternativa, se o principal já tiver as permissões storage.objects.get e storage.objects.delete por um papel como Usuário de objetos do Storage (roles/storage.objectUser), ele poderá definir a propriedade storage/parallel_composite_upload_compatibility_check como False para desativar a verificação de compatibilidade.

403: não tem acesso storage.objects.get

Problema: os uploads de arquivos menores que 150 MiB são bem-sucedidos, mas os uploads de arquivos de 150 MiB ou maiores falham com o código de saída 1 e um erro semelhante ao seguinte:

HTTPError 403: PRINCIPAL does not have storage.objects.get access to
the Google Cloud Storage object.

Solução: storage/parallel_composite_upload_compatibility_check está definido como False e storage/parallel_composite_upload_enabled está definido como None ou True. Nessa configuração, a CLI gcloud ignora a verificação de compatibilidade do bucket e prossegue diretamente com um upload composto paralelo.

Os objetos temporários são enviados por upload com sucesso porque o principal tem a permissão storage.objects.create. No entanto, a composição dos objetos temporários no objeto final requer a permissão storage.objects.get, e a exclusão dos objetos temporários depois requer a permissão storage.objects.delete.

Para resolver esse problema, escolha uma das seguintes opções:

  • Se você não precisar de uploads compostos paralelos, desative-os:

    gcloud config set storage/parallel_composite_upload_enabled False

    Todos os arquivos são enviados como uploads normais, e o principal precisa apenas das permissões incluídas no papel de Criador de objetos do Storage (roles/storage.objectCreator). Você pode deixar storage/parallel_composite_upload_compatibility_check em qualquer valor.

  • Se você precisar de uploads compostos paralelos, conceda ao principal as permissões storage.objects.get e storage.objects.delete no bucket de destino. Essas permissões podem ser concedidas pelo papel de Usuário de objetos do Storage (roles/storage.objectUser).

Se o upload com falha deixou objetos temporários no bucket, exclua-os. Por padrão, os objetos temporários usam o prefixo gcloud/tmp/parallel_composite_uploads/see_gcloud_storage_cp_help_for_details. Para excluir objetos temporários resultantes de um upload com falha, você precisa da permissão storage.objects.delete.

Observe que o comando gcloud storage rsync se comporta de maneira diferente de gcloud storage cp e gcloud storage mv. Quando o destino é uma raiz de bucket, como gs://my-bucket, gcloud storage rsync sempre exige a permissão storage.buckets.get para sincronizar com o bucket, independentemente das configurações de upload composto paralelo. Quando o destino é um subdiretório de bucket, como gs://my-bucket/dir/, gcloud storage rsync não exige a permissão storage.buckets.get, desde que a verificação de compatibilidade esteja desativada nas configurações de upload composto paralelo. Nesse cenário, gcloud storage rsync exige a permissão storage.objects.get em vez de storage.buckets.get.