Uploads compostos paralelos

Os uploads compostos paralelos podem ajudar você a fazer upload de arquivos grandes de forma significativamente mais rápida quando a velocidade da rede e do disco não são fatores limitantes. Em um upload composto paralelo, um arquivo é dividido em até 32 partes, que são enviadas em paralelo para objetos temporários. O objeto final é recriado usando os objetos temporários, que são excluídos.

Se você interage com o Cloud Storage usando a API XML, use os uploads de várias partes da API XML. Os uploads de várias partes da API XML são compatíveis com um número maior de partes do que as operações de composição, têm menos potencial para taxas de exclusão antecipada e não exigem solicitações Delete para remover as partes de origem depois que o objeto final é montado.

Considerações

O objeto final que um upload composto paralelo armazena no 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 usuários do gsutil, que precisa fazer o download dos 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 realizar 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 blocos de objetos. Ele também contém a permissão necessária para que a CLI gcloud realize uma verificação de compatibilidade no nível do bucket com uploads compostos paralelos. Se não for possível receber o papel de Administrador do Storage (roles/storage.admin), ainda será possível realizar 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 receber as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Para instruções sobre como conceder papéis em 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 console do Google Cloud não faz uploads compostos paralelos.

Linha de comando

As propriedades a seguir funcionam juntas para determinar como e quando a CLI gcloud realiza 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 for True ou None, ativa os 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 no nível do bucket para compatibilidade e segurança com uploads compostos paralelos. Se for True, a CLI gcloud vai enviar 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ó realiza uploads compostos paralelos quando todas as seguintes condições são atendidas:

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

    Definir storage/parallel_composite_upload_compatibility_check como False não desativa os uploads compostos paralelos. Quando storage/parallel_composite_upload_compatibility_check é 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 pular 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 propriedades criando uma configuração nomeada e aplicando a configuração por comando usando a flag --configuration em todo o projeto ou para todos os comandos da CLI gcloud usando o comando gcloud config set.

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 operação compose.

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

  • Ao usar a operação compose, é possível excluir permanentemente os objetos de origem 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 operação compose.

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

Nesta seção, você encontra informações sobre como solucionar 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: quando você faz upload de um arquivo de 150 MiB ou mais 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 exibe 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 meio de 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 com 150 MiB ou mais 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 pula a verificação de compatibilidade do bucket e prossegue diretamente com um upload composto paralelo.

O upload dos objetos temporários é concluído 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 requer a permissão storage.objects.delete.

Para resolver esse problema, escolha uma destas 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 com 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. Essa permissão pode ser concedida pelo papel de Usuário de objetos do Storage (roles/storage.objectUser).

Se o upload com falha tiver deixado 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.

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, o gcloud storage rsync sempre requer 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 requer a permissão storage.objects.get em vez de storage.buckets.get.