ossutil cp - Upload files and directories to OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

Envie arquivos ou diretórios locais para um bucket do OSS com o comando cp. Este comando oferece suporte a upload simples, retomável, em lote e incremental, com opções para metadados do objeto, classe de armazenamento e ACL.

Como funciona

O comando cp seleciona o método de upload conforme o tamanho do arquivo:

Upload simples: Aplicado quando o arquivo é menor que o limiar de upload retomável (padrão: 100 MB, configurável com --bigfile-threshold).
Upload retomável: Aplicado quando o arquivo atinge ou excede o limiar. Uploads interrompidos deixam partes no bucket. Limpe essas partes periodicamente para evitar custos de armazenamento. Você pode excluir partes manualmente ou configurar regras de ciclo de vida para exclusão automática.

Nota

A partir da versão v1.6.16 do ossutil, use ossutil como nome do binário em todos os sistemas operacionais compatíveis. Em versões anteriores, use o nome do binário específico para o seu sistema operacional. Para mais informações, consulte Guia de início rápido da ferramenta de linha de comando ossutil.

Permissões

Uma conta Alibaba Cloud tem permissões totais por padrão. Usuários RAM e funções RAM não têm permissões padrão e exigem autorização por meio de uma política RAM ou de uma política de bucket.

Ação da API	Descrição
`oss:PutObject`	Envia um objeto.
`oss:PutObjectTagging`	Necessário apenas ao definir tags de objeto durante o upload.
`kms:GenerateDataKey`	Necessário apenas ao usar criptografia do lado do servidor com o Key Management Service (KMS).
`kms:Decrypt`

Sintaxe do comando

ossutil cp file_url cloud_url [options]

Parâmetros e opções:

Parâmetro	Descrição
file_url	Caminho do arquivo local. Se a origem for um diretório, o caminho deve terminar com um separador (`/` ou `\`). Exemplo: `/localfolder/examplefile.txt` em sistemas Linux ou `D:\localfolder\examplefile.txt` em sistemas Windows.
cloud_url	Caminho do objeto, no formato `oss://bucket[/prefix]`. Exemplo: `oss://examplebucket/examplefile.txt`.
-r, --recursive	Envia recursivamente arquivos e subdiretórios. Sem esta opção, apenas o objeto especificado é processado.
-f --force	Força a execução da operação sem solicitar confirmação.
-u, --update	Envia apenas se o objeto de destino estiver ausente ou for mais antigo que o arquivo de origem.
--maxupspeed	Velocidade máxima de upload em KB/s. Padrão: 0 (ilimitado).
--enable-symlink-dir	Envia subdiretórios vinculados. Esta opção está desativada por padrão.
--disable-all-symlink	Ignora todos os links simbólicos durante o upload.
--disable-ignore-error	Não ignora erros durante operações em lote.
--only-current-dir	Envia apenas os arquivos no diretório de origem especificado, ignorando seus subdiretórios.
--bigfile-threshold	Limiar de tamanho para upload retomável. Unidade: bytes. Valor padrão: 100 MB Valores válidos: 0 a 9223372036854775807
--part-size	Tamanho da parte em bytes. Por padrão, o ossutil calcula esse valor com base no tamanho do arquivo. Intervalo: 1 a 9223372036854775807
--checkpoint-dir	Diretório para registros de upload retomável. Por padrão, o ossutil cria um diretório `.ossutil_checkpoint` e o exclui após um upload bem-sucedido. Se você especificar um diretório personalizado, certifique-se de que ele possa ser excluído.
--encoding-type	Codificação do nome do arquivo. Defina como url para codificar nomes de arquivos em URL. Não codificado por padrão.
--include	Inclui todos os arquivos que atendem às condições especificadas. Para mais informações sobre sintaxe e exemplos, consulte Upload em lote de arquivos que atendem a condições especificadas.
--exclude	Exclui todos os arquivos que atendem às condições especificadas. Para mais informações sobre sintaxe e exemplos, consulte Upload em lote de arquivos que atendem a condições especificadas.
--meta	Metadados do arquivo. Inclui cabeçalhos HTTP padrão e metadados definidos pelo usuário, que começam com `x-oss-meta-`. Os metadados devem estar no formato `header:value#header:value`. Exemplo: `Cache-Control:no-cache#Content-Encoding:gzip`. Para mais informações sobre metadados compatíveis com o OSS, consulte Gerenciar metadados de objetos.
--acl	Lista de controle de acesso (ACL) do arquivo. Valores válidos: default (padrão): A ACL do objeto é igual à ACL do bucket. private: Apenas o proprietário do bucket pode ler e gravar os objetos no bucket. Outros usuários não podem acessar os objetos. public-read: Apenas o proprietário do bucket pode gravar nos objetos do bucket. Outros usuários, incluindo anônimos, podem ler os objetos. Isso pode causar vazamento de dados e taxas inesperadamente altas. Se usuários mal-intencionados gravarem informações ilegais nos objetos, seus direitos e interesses legítimos poderão ser violados. Não configure esta permissão, exceto em cenários especiais. public-read-write: Qualquer pessoa, incluindo usuários anônimos, pode ler e gravar os objetos no bucket. Isso pode causar vazamento de dados e taxas inesperadamente altas. Tenha cuidado ao configurar esta permissão.
--snapshot-path	Diretório para snapshots de upload. Em uploads subsequentes, o ossutil lê este diretório para realizar uploads incrementais.
--disable-crc64	Desativa a validação de dados CRC-64. Ativado por padrão.
--disable-dir-object	Ignora a criação de objetos de diretório durante o upload.
--payer	Método de pagamento. Defina como requester para cobrar do solicitante as taxas de tráfego e requisição.
--tagging	Tags a serem adicionadas durante o upload. Formato: `TagkeyA=TagvalueA&TagkeyB=TagvalueB....`.
-j, --jobs	Tarefas simultâneas para operações com múltiplos arquivos. Padrão: 3. Valores válidos: 1 a 10000.
--parallel	Tarefas simultâneas para operações com arquivo único. Valores válidos: 1 a 10000. Determinado automaticamente com base no tipo de operação e no tamanho do arquivo, caso não seja definido.
--start-time	Um timestamp UNIX. Objetos cuja última atualização ocorreu antes desse horário são ignorados. Nota Apenas o ossutil 1.7.18 e versões posteriores oferecem suporte a este parâmetro. Para mais informações sobre atualização, consulte update (Atualizar ossutil).
--end-time	Um timestamp UNIX. Objetos cuja última atualização ocorreu após esse horário são ignorados. Nota Se você especificar tanto `start-time` quanto `end-time`, o comando de cópia será executado apenas para arquivos modificados pela última vez entre os horários inicial e final especificados. Apenas o ossutil 1.7.18 e versões posteriores oferecem suporte a este parâmetro. Para mais informações sobre como atualizar a versão, consulte update (Atualizar ossutil).

Para mais informações sobre outras opções comuns para este comando, consulte Opções comuns.

Ajuste -j, --jobs e --parallel para otimizar o desempenho. Por padrão, o ossutil calcula o paralelismo com base no tamanho do arquivo. Para transferências em lote de arquivos grandes, a concorrência real é jobs × parallel.

Se a máquina tiver recursos limitados (largura de banda, memória ou CPU), reduza a concorrência para 100 ou menos. Aumente-a se os recursos estiverem subutilizados.
Concorrência excessiva pode degradar o desempenho ou causar erros EOF. Ajuste -j, --jobs e --parallel com base nos recursos da sua máquina. Comece com valores baixos e aumente gradualmente até encontrar o valor ideal.

Exemplos

Estes exemplos usam Linux. Ajuste os caminhos para o seu sistema operacional. Os exemplos assumem:

Nome do bucket: examplebucket
Diretório OSS: desfolder/
Diretório local: localfolder/
Arquivo local: examplefile.txt

Upload de um único arquivo

Envie um arquivo para um diretório. Se nenhum nome de objeto for especificado, o nome original do arquivo será usado.
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/
```
Envie um único arquivo e use a opção --meta para definir os metadados do arquivo. Os metadados devem estar no formato header:value#header:value....
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/examplefile.txt --meta=Cache-Control:no-cache#Content-Encoding:gzip
```

Uploads em lote

Upload apenas dos arquivos em uma pasta
Adicione a opção -r ao comando cp para enviar apenas os arquivos de uma pasta local para um caminho especificado no OSS.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/
```
Upload de arquivos de uma pasta com especificação de timestamp

Envie arquivos de uma pasta local para um caminho especificado no OSS. Os arquivos devem ter sido modificados entre 10:09:18 (UTC+8) em 31 de outubro de 2023 e 12:55:58 (UTC+8) em 31 de outubro de 2023.
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --start-time 1698718158 --end-time 1698728158
```
Upload de uma pasta e dos arquivos nela contidos

Use a opção cp -r para enviar uma pasta local e seus arquivos. O OSS cria um objeto de 0 KB terminado com / para cada subdiretório, mas não para a pasta em si. Para criar um objeto de pasta, use o comando mkdir (criar diretórios).
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/localfolder/
```
Upload de uma pasta ignorando arquivos existentes

Para tentar novamente um upload em lote com falha, use --update (ou -u) para ignorar arquivos já enviados e realizar um upload incremental:
```
ossutil cp -r localfolder/ oss://examplebucket/desfolder/ -u
```

Upload apenas dos arquivos no diretório atual, ignorando subdiretórios

ossutil cp localfolder/ oss://examplebucket/desfolder/ --only-current-dir -r

Upload sem gerar um objeto para o diretório

No OSS, diretórios são simulados por objetos de 0 KB terminados com /. Use --disable-dir-object para ignorar a criação desses objetos. A estrutura de diretórios ainda aparece no console do OSS, mas desaparece quando todos os arquivos nela são excluídos.
```
ossutil cp localfolder/ oss://examplebucket/desfolder/ --disable-dir-object -r
```

Upload de arquivos em um subdiretório vinculado

ossutil cp localfolder/ oss://examplebucket/desfolder/ --enable-symlink-dir -r

Ignorar todos os subarquivos e subdiretórios vinculados durante um upload

ossutil cp localfolder/ oss://examplebucket/desfolder/ -r --disable-all-symlink

Upload em lote de arquivos que atendem a condições especificadas

Use --include e --exclude para filtrar arquivos durante o upload em lote.

As opções --include e --exclude aceitam os seguintes formatos:

Asterisco (*): Corresponde a qualquer número de caracteres. Por exemplo, *.txt corresponde a todos os arquivos TXT.
Ponto de interrogação (?): Corresponde a um único caractere. Por exemplo, abc?.jpg corresponde a todos os arquivos JPG cujos nomes são "abc" seguidos por um único caractere, como abc1.jpg.
[sequência]: Corresponde a qualquer caractere na sequência. Por exemplo, abc[1-5].jpg corresponde a arquivos chamados abc1.jpg a abc5.jpg.
[!sequência]: Corresponde a qualquer caractere fora da sequência. Por exemplo, abc[!0-7].jpg corresponde a arquivos cujos nomes não são abc0.jpg a abc7.jpg.

Uma regra pode conter várias condições de inclusão e exclusão. O ossutil as avalia da esquerda para a direita. Para um arquivo chamado test.txt, diferentes ordenações de regras produzem resultados diferentes.

Regra 1: --include "*test*" --exclude "*.txt" . Quando a regra corresponde a --include "*test*", o resultado é que test.txt atende à condição. Quando a regra continua a corresponder a --exclude "*.txt", test.txt é excluído porque seu nome contém .txt. O resultado final é que test.txt não atende às condições.
Regra 2: --exclude "*.txt" --include "*test*". O arquivo test.txt é excluído pela regra --exclude "*.txt". No entanto, a regra --include "*test*" inclui então test.txt porque seu nome contém "test". Como resultado, test.txt é incluído.
Regra 3: --include "*test*" --exclude "*.txt" --include "te?t.txt" . Primeiro, a regra --include "*test*" inclui test.txt. Em seguida, a regra --exclude "*.txt" exclui test.txt. Finalmente, a regra --include "te?t.txt" inclui test.txt. Portanto, test.txt é incluído.

Importante

Não é possível especificar um formato de diretório nas condições. Por exemplo, --include "/usr/test/.jpg" não é suportado.

Veja a seguir alguns exemplos:

Upload de todos os arquivos no formato TXT

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*.txt" -r

Upload de todos os arquivos cujos nomes contêm abc e não estão no formato JPG ou TXT

ossutil cp localfolder/ oss://examplebucket/desfolder/ --include "*abc*" --exclude "*.jpg" --exclude "*.txt" -r

Limitar velocidade de uploads

Use --maxupspeed para limitar a velocidade de upload em KB/s. Exemplos:

Upload de um arquivo com limite de velocidade de 1 MB/s

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --maxupspeed 1024

Upload de uma pasta com limite de velocidade de 1 MB/s

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --maxupspeed 1024

Upload e definição de tags de objeto

Use --tagging para definir tags de objeto durante o upload. Separe múltiplas tags com e comercial (&). Exemplo:

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --tagging "abc=1&bcd=2&..."

Tags de objeto.

Upload e especificação de classe de armazenamento

Use --meta para definir a classe de armazenamento durante o upload. Valores válidos:

Standard: Standard
IA: Infrequent Access
Archive: Archive Storage
ColdArchive: Cold Archive
DeepColdArchive: Deep Cold Archive

Se nenhuma classe de armazenamento for especificada, o objeto herda a classe de armazenamento do bucket. Para mais informações, consulte Classes de armazenamento.

Veja a seguir exemplos de upload de um arquivo com especificação de classe de armazenamento:

Upload de um único arquivo com classe de armazenamento definida como Infrequent Access

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:IA

Upload de uma pasta com classe de armazenamento dos arquivos definida como Standard

ossutil cp localfolder/ oss://examplebucket/desfolder/ --meta X-oss-Storage-Class:Standard -r

Upload e especificação de ACL

Use --acl para definir a ACL do arquivo enviado. Valores válidos:

default: herda a ACL do bucket (padrão)
private: private
public-read: public-read
public-read-write: Acesso público de leitura e gravação

Veja a seguir alguns exemplos:

Upload de um único arquivo com ACL definida como private

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --acl private

Upload de uma pasta com ACL dos arquivos definida como public-read

ossutil cp localfolder/ oss://examplebucket/desfolder/ --acl public-read  -r

Upload e especificação de método de criptografia

Especifique um método de criptografia do lado do servidor durante o upload. Exemplos:

Upload de um arquivo com SSE-OSS como método de criptografia e AES256 como algoritmo de criptografia
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:AES256
```

Upload de um arquivo com SSE-KMS como método de criptografia e sem especificar um CMK ID
```
ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS
```
A criptografia KMS incorre em uma pequena taxa de uso de chave. Preços do KMS.

Upload de um arquivo com SSE-KMS como método de criptografia e um CMK ID

ossutil cp examplefile.txt oss://examplebucket/desfolder/ --meta=x-oss-server-side-encryption:KMS#x-oss-server-side-encryption-key-id:7bd6e2fe-cd0e-483e-acb0-f4b9e1******

Para mais informações sobre criptografia do lado do servidor, consulte Criptografia do lado do servidor.

Upload e geração de snapshots

Com --snapshot-path, o ossutil registra o lastModifiedTime dos arquivos enviados e o utiliza para ignorar arquivos inalterados em uploads subsequentes, acelerando uploads em lote incrementais. Certifique-se de que nenhum outro usuário modifique os objetos correspondentes entre os uploads. --snapshot-path é mais adequado para uploads em lote de grande volume. Exemplo:

ossutil cp -r localfolder/ oss://examplebucket/desfolder/ --snapshot-path=path

Importante

O ossutil não exclui automaticamente snapshots na pasta snapshot-path. Remova periodicamente snapshots desnecessários da pasta snapshot-path.
A E/S de snapshot adiciona sobrecarga. Para pequenos lotes, boas condições de rede ou objetos compartilhados, use --update para uploads incrementais.
É possível usar as opções --update e --snapshot-path simultaneamente. O ossutil verifica primeiro as informações do snapshot-path para determinar se deve ignorar um arquivo. Se o arquivo não for ignorado com base no snapshot, o ossutil usa então a opção --update para determinar se deve ignorar o arquivo.

Upload e configuração de pagamento pelo solicitante

ossutil cp localfolder/examplefile.txt oss://examplebucket/ --payer=requester

Uploads entre contas ou entre regiões

Use as opções comuns -e, -i e -k para enviar um arquivo local para um bucket em uma região diferente ou sob uma conta Alibaba Cloud diferente.

Nota

Especifique o endpoint correspondente à região do bucket. Para mais informações, consulte Regiões e endpoints.

ossutil cp exampleobject.txt oss://examplebucket/desfolder/ -e oss-cn-shanghai.aliyuncs.com -i yourAccessKeyID  -k yourAccessKeySecret