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.

  • Os usuários do Python, incluindo os usuários do gsutil, que precisam fazer o download dos objetos têm 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.

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

É possível configurar como e quando o gcloud storage cp realiza uploads compostos paralelos modificando as seguintes propriedades:

  • storage/parallel_composite_upload_enabled: propriedade para ativar uploads compostos paralelos. Se False, os uploads compostos paralelos são desativados. Se True ou None, os uploads compostos paralelos são feitos para objetos que atendam aos critérios definidos nas outras properties. A configuração padrão é None.

  • storage/parallel_composite_upload_compatibility_check: propriedade para alternar verificações de segurança. Se for True, o gcloud storage só fará uploads compostos comparados quando todas as condições a seguir forem atendidas:

    Lembre-se que, para verificar essas condições, a gcloud CLI recupera os metadados do bucket de destino como parte do comando upload.

    Se False, gcloud storage não realiza nenhuma verificação. A configuração padrão é True.

  • 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 flag --configuration em todo o projeto ou para todos os comandos da gcloud CLI usando o comando gcloud config set.

Não é preciso mais espaço no disco local ao usar a gcloud CLI para fazer uploads compostos paralelos. Se um upload composto paralelo falhar antes da composição, execute o comando da gcloud CLI 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 gcloud CLI 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 autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

É possível executar uploads compostos paralelos definindo AllowParallelCompositeUpload como true. 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 autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse 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 autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse 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

Tanto a API JSON quanto a API XML permitem 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.