Como sincronizar arquivos locais com o OSS - Object Storage Service: Central de Documentação do Alibaba Cloud

Use o comando sync para sincronizar arquivos ou pastas locais com o OSS. O comando sync compara a data da última modificação dos arquivos ou usa informações de snapshot para identificar e enviar apenas os arquivos alterados de forma incremental. Esse processo mantém a consistência entre o conteúdo da origem e do destino com eficiência.

Como funciona

Quantidade de arquivos

Ao executar o comando sync sem a opção --delete, não há limite para a quantidade de arquivos sincronizados por vez. Se você incluir a opção --delete, poderá sincronizar até 1 milhão de arquivos simultaneamente. Caso a quantidade exceda 1 milhão, o sistema retornará o erro over max sync numbers 1000000..
Diferenças entre os comandos sync e cp
- O comando sync percorre recursivamente todos os arquivos e subdiretórios em uma pasta especificada. Já o comando cp executa uma operação recursiva somente se você adicionar a opção -r.
- Ao usar o comando sync para sincronizar dados com o OSS, adicione a opção --delete para excluir arquivos presentes no destino, mas ausentes na origem. Essa opção garante que o diretório de destino contenha apenas os arquivos da sincronização atual. O comando cp não oferece suporte à opção --delete.
- O comando sync não aceita a opção --version-id. Portanto, não é possível usá-lo para sincronizar versões anteriores de arquivos em um bucket com versionamento ativado. O comando cp aceita a opção --version-id.
Exceto por essas diferenças, os comandos sync e cp têm uso semelhante. Para obter mais informações sobre o uso e exemplos do comando cp, consulte cp (enviar arquivos).

Observação de uso

A partir da versão 1.6.16 do ossutil, use o binário ossutil diretamente, sem precisar renomeá-lo para o seu sistema operacional. Em versões anteriores à 1.6.16, renomeie o arquivo binário. Para mais detalhes, consulte Referência de comandos do ossutil.

Permissões

Por padrão, apenas uma conta Alibaba Cloud tem permissão para executar todas as operações de API. Para executar este comando, conceda as permissões necessárias a um usuário RAM ou a uma função RAM por meio de uma Política do RAM ou de uma Política de Bucket. A concessão deve ser feita por uma conta Alibaba Cloud ou por um administrador.

Ação da API	Descrição
OSS:ListObjects	Lista objetos no bucket de destino para comparação com os arquivos locais.
OSS:PutObject	Envia arquivos para o OSS.
OSS:DeleteObject	[Opcional] Necessária ao usar a opção --delete para remover arquivos excedentes do bucket de destino.
OSS:PutObjectTagging	[Opcional] Necessária ao usar a opção --tagging para adicionar tags a um objeto.

Sintaxe do comando

ossutil sync file_url cloud_url [options]

A tabela a seguir descreve os parâmetros e as opções.

Parâmetro	Descrição
file_url	Caminho da pasta local a sincronizar. Exemplo: `/localfolder/` para Linux ou `D:\localfolder\` para Windows.
cloud_url	Caminho da pasta de destino no OSS. Formato: `oss://bucketname/path/`. Exemplo: `oss://examplebucket/exampledir/`. Se o `cloud_url` informado não terminar com barra (/), o ossutil adicionará uma automaticamente ao final.
-f --force	Força a operação sem solicitar confirmação.
-u, --update	Sincroniza um arquivo apenas se ele não existir no destino ou se a data da última modificação na origem for posterior à do destino.
--delete	Exclui outros arquivos no caminho de destino e mantém apenas os da sincronização atual. Aviso Antes de usar a opção --delete, ative o versionamento para evitar exclusão acidental de dados.
--enable-symlink-dir	Sincroniza subdiretórios vinculados.
--disable-all-symlink	Ignora todos os arquivos e subdiretórios vinculados durante a sincronização da pasta.
--disable-ignore-error	Não ignora erros durante operações em lote.
--only-current-dir	Sincroniza apenas os arquivos no diretório atual. Ignora subdiretórios e seus respectivos arquivos.
--output-dir	Especifique o diretório para armazenar arquivos de saída. Esses arquivos são relatórios gerados quando ocorrem erros durante a sincronização em lote. Por padrão, o sistema salva esses relatórios no diretório ossutil_output dentro do diretório atual.
-bigfile-threshold	Limiar de tamanho de arquivo para upload retomável. Unidade: bytes. Valor padrão: 100 MB Valores válidos: 0 a 9223372036854775807
--part-size	Tamanho da parte. Unidade: bytes. Por padrão, o ossutil calcula um tamanho adequado com base no tamanho do arquivo. Valores válidos: 1 a 9223372036854775807
--checkpoint-dir	Define o diretório para armazenar informações de checkpoint para uploads retomáveis. Quando um upload retomável falha, o ossutil cria automaticamente um diretório chamado `.ossutil_checkpoint` para registrar as informações de checkpoint. Esse diretório é excluído após o sucesso do upload. Se você especificar um diretório para esta opção, certifique-se de que ele possa ser excluído.
--encoding-type	Formato de codificação dos nomes de arquivo. Defina o valor como url. Se você não especificar esta opção, os nomes dos arquivos não serão codificados.
--snapshot-path	Indica o diretório para salvar informações de snapshot da sincronização. Na próxima tarefa de sincronização, o ossutil lê as informações de snapshot deste diretório para executar uma sincronização incremental.
--include	Inclui todos os arquivos que atendem à condição especificada. Para mais informações, consulte opções include e exclude.
--exclude	Exclui todos os arquivos que atendem à condição especificada. Para mais informações, consulte include e --exclude.
--meta	Define os metadados dos arquivos. Formato: `header:value#header:value`. Exemplo: `Cache-Control:no-cache#Content-Encoding:gzip`. Para mais detalhes, veja set-meta (Gerenciar metadados de arquivo).
--acl	Lista de controle de acesso (ACL) dos arquivos. Valores válidos: default: A ACL dos arquivos é herdada do bucket. private (padrão): Apenas o proprietário do bucket tem permissões de leitura e gravação nos arquivos. Outros usuários não podem acessá-los. public-read: Somente o proprietário do bucket tem permissão de gravação nos arquivos. Outros usuários, incluindo anônimos, têm apenas permissão de leitura. Isso pode expor seus dados e aumentar suas taxas. Se usuários mal-intencionados gravarem informações ilegais em seu bucket, seus direitos e interesses legais poderão ser violados. Recomendamos não configurar essa permissão, exceto em cenários específicos. public-read-write: Todos os usuários, inclusive anônimos, têm permissões de leitura e gravação nos arquivos. Tal configuração pode expor seus dados e elevar custos. Use esta permissão com cautela.
--maxupspeed	Velocidade máxima de upload. Unidade: KB/s. O valor padrão é 0, o que indica ausência de limite de velocidade de upload.
--disable-crc64	Desativa a validação de dados CRC-64.
--payer	Método de pagamento da solicitação. Caso deseje que o solicitante pague pelas taxas, como tráfego e requisições geradas ao acessar os recursos no caminho especificado, defina esta opção como requester.
-j，--job	Número de tarefas simultâneas para operações com múltiplos arquivos. Valor padrão: 3. Valores válidos: 1 a 10000.
--parallel	Quantidade de tarefas concorrentes para uma operação de arquivo único. Valores válidos: 1 a 10000. Se você não especificar esta opção, o ossutil determinará o valor com base no tipo de operação e no tamanho do arquivo.
--retry-times	Número de tentativas em caso de erro. Valor padrão: 10. Valores válidos: 1 a 500.
--tagging	Informações de tag dos arquivos. Formato: `TagkeyA=TagvalueA&TagkeyB=TagvalueB....`.

Para obter mais informações sobre outras opções comuns deste comando, consulte Opções comuns.

Exemplos

Os exemplos abaixo usam um sistema Linux. Adapte os parâmetros conforme o seu sistema operacional e ambiente. Os exemplos consideram o seguinte cenário:

Dois arquivos, d.txt e e.png, estão no diretório local localfolder. O diretório destfolder em um bucket chamado examplebucket contém dois arquivos, a.txt e b.txt, além de um subdiretório chamado C. O conteúdo inicial é o seguinte:

Local root directory                  examplebucket
    └── localfolder         └── destfolder/
            ├── d.txt               ├── a.txt
            └── e.png               ├── b.txt
                                    └── C/

Sincronizar uma pasta local com o OSS

Sincronize todos os arquivos do diretório local localfolder/ para o diretório de destino destfolder/. Esta operação envia apenas novos arquivos. Arquivos existentes, como a.txt e b.txt, e o subdiretório C/ no bucket de destino são mantidos.

ossutil sync localfolder/ oss://examplebucket/destfolder/

Após a sincronização bem-sucedida, a saída inclui a quantidade de arquivos sincronizados, o tamanho total dos arquivos e o tempo gasto na operação:

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

Após a sincronização, a estrutura do diretório destfolder/ fica assim:

destfolder/
├── a.txt
├── b.txt
├── d.txt 
├── e.png 
└── C/

Excluir arquivos excedentes no diretório de destino durante a sincronização

Ao sincronizar o diretório local localfolder/, use a opção --delete para remover arquivos e diretórios do destfolder/ que não existam na origem, como a.txt, b.txt e C/.

ossutil sync localfolder/ oss://examplebucket/destfolder/ --delete

Após a sincronização, a estrutura de diretórios de destfolder/ torna-se idêntica à de localfolder/:

destfolder/
├── d.txt
└── e.png

Filtrar e sincronizar arquivos específicos

Use as opções --include e --exclude para filtrar os arquivos a sincronizar.

Por exemplo, o comando abaixo sincroniza apenas arquivos .txt.
```
ossutil sync localfolder/  oss://examplebucket/destfolder/ --include "*.txt"
```
Após a execução do comando, apenas d.txt é enviado e e.png é ignorado. Os arquivos existentes no bucket de destino não são afetados.
```
destfolder/
├── a.txt
├── b.txt
├── d.txt 
└── C/
```
O comando a seguir sincroniza apenas arquivos que não sejam .txt.
```
ossutil sync localfolder/  oss://examplebucket/destfolder/ --exclude "*.txt"
```
Após a execução do comando, apenas e.png é enviado e d.txt é ignorado. Os arquivos existentes no bucket de destino permanecem inalterados.
```
destfolder/
├── a.txt
├── b.txt
├── e.png 
└── C/
```

Sobrescrever forçadamente arquivos com o mesmo nome no diretório de destino

Por padrão, se existir um arquivo com o mesmo nome no diretório de destino, o ossutil solicitará confirmação para sobrescrita. Se tiver certeza de que deseja substituir todos os arquivos de destino com nomes iguais, use a opção -f ou --force para ignorar o prompt de confirmação e forçar a substituição.

ossutil sync localfolder/ oss://examplebucket/destfolder/ -f

Após a execução bem-sucedida do comando, a saída exibe informações como a quantidade de arquivos sincronizados, o tamanho total e a velocidade média. Veja um exemplo de saída:

Succeed: Total num: 2, size: 750,081. OK num: 2(upload 2 files).

average speed 1641000(byte/s)

Sincronização entre contas

Use as opções -e, -i e -k para sincronizar arquivos do diretório local srcfolder para o diretório testfolder no bucket examplebucket. Este bucket está na região China (Shanghai) e pertence a outra conta Alibaba Cloud.

Nota

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

ossutil sync srcfolder/ oss://examplebucket/testfolder/ -e oss-cn-shanghai.aliyuncs.com -i LTAI4Fw2NbDUCV8zYUzA**** -k 67DLVBkH7EamOjy2W5RVAHUY9H****

Dica de segurança : Incluir uma AccessKey em um comando representa um risco de segurança. Para tarefas automatizadas ou de longa duração, recomendamos criar uma função RAM para a conta de origem e conceder permissões à conta de destino. Esse método oferece um acesso entre contas mais seguro.