Como gerenciar dados do OSS pela linha de comando no Windows, Linux e macOS - Object Storage Service: Central de Documentação do Alibaba Cloud

A ferramenta de linha de comando ossutil 2.0 permite gerenciar recursos do Alibaba Cloud oss com eficiência em diversos sistemas operacionais. Com ela, você faz upload, baixe, sincronização e gerenciamento de arquivos de forma ágil. É a solução ideal para desenvolvedores, engenheiros de O&M e empresas que lidam com migração de dados em grande escala e operações diárias de O&M.

Sistema operacional	Arquitetura	Link para baixe	Checksum SHA256
Linux	x86_32	ossutil-2.3.0-linux-386.zip	29cbd49b6c401c740c2f036cdf9d44ee8da340b16bdb3be71a33bcbebbe35ec5
	x86_64	ossutil-2.3.0-linux-amd64.zip	3ae4d9fc85a7a6e9f5654d1599766f1a3a42a3692870887b5ae9338d582ef65a
	arm32	ossutil-2.3.0-linux-arm.zip	8aff883c676961a11c89ac98b807fafa54fb424851d0557b1691b9d320324b9e
	arm64	ossutil-2.3.0-linux-arm64.zip	f6c95ba0c2d2ef30290af686ce4d706c701f4734ce8090bee4288a77e3f1d764
macOS	x86_64	ossutil-2.3.0-mac-amd64.zip	8437fdd3ef1a3eb12310f61fcf1c00a5bff5cdab47b4fea815527472e7cf896c
macOS	arm64	ossutil-2.3.0-mac-arm64.zip	058fd048f321f8c80def8b748030531646eefe3a82837bf16b581ba7d9c84ac7
Windows	x86_32	ossutil-2.3.0-windows-386.zip	ae5f20b0bfe2aadf61c87931cbb342f743e266bb56b49dace16f59942305c1ea
	x86_64	ossutil-2.3.0-windows-amd64.zip	98209156987667b39fd12a0c7b940342900daef61a9306ea7f34acf17f287da2
	x86_64	ossutil-2.3.0-windows-amd64-go1.20.zip	0b9249d1c1437a9f052a9bf5eeaf1d4358b515e08efa82a3b7048950ce7efdea

Início rápido

Para usar a interface de linha de comando do ossutil 2.0, siga estas etapas:

Instale o ossutil

Linux

Instale a ferramenta unzip.

Alibaba Cloud Linux

sudo yum install -y unzip

CentOS

sudo yum install -y unzip

Ubuntu

sudo apt install -y unzip

Escolha o pacote de instalação correspondente ao seu sistema operacional e arquitetura (Linux x86 32 bits, Linux x86 64 bits, Linux ARM 32 bits ou Linux ARM 64 bits) ou use o curl para baixá-lo. O exemplo abaixo demonstra o uso do comando curl em um sistema Linux x86_64:
```
curl -o ossutil-2.3.0-linux-amd64.zip https://gosspublic.alicdn.com/ossutil/v2/2.3.0/ossutil-2.3.0-linux-amd64.zip
```
No diretório de baixe, descompacte o pacote:
```
unzip ossutil-2.3.0-linux-amd64.zip
```
Acesse o diretório ossutil-2.3.0-linux-amd64.
```
cd ossutil-2.3.0-linux-amd64
```
Conceda permissões de execução ao arquivo ossutil:
```
chmod 755 ossutil
```

Execute o comando a seguir para tornar o ossutil disponível globalmente.

sudo mv ossutil /usr/local/bin/ && sudo ln -s /usr/local/bin/ossutil /usr/bin/ossutil

Para verifique se a instalação foi concluída com êxito, execute o comando ossutil.
```
ossutil
```
A instalação terá sido bem-sucedida se o ossutil exibir suas informações de ajuda.

Windows

Instale o ossutil.
1. Selecione o pacote de instalação adequado ao seu sistema operacional e arquitetura (Windows x86 32 bits, Windows x86 64 bits ou Windows 7, Windows 8, Windows Server 2008R2).
2. Descompacte o pacote .zip baixado em uma pasta de destino e acesse o diretório extraído.
3. Copie o caminho da pasta extraída do ossutil. Você adicionará esse caminho a uma variável de ambiente do sistema.
  1. Clique em na barra de endereços do diretório atual e copie o caminho da pasta exibido.
  2. Abra a caixa de diálogo Environment Variables. Na seção System variables, localize e clique em duas vezes na variável Path. Clique em New e cole o caminho copiado da pasta ossutil no novo campo de entrada.
4. Verifique a instalação:
```
ossutil
```
  A instalação terá sido bem-sucedida se o ossutil exibir suas informações de ajuda.

macOS

Escolha o pacote de instalação para o seu sistema operacional e arquitetura (macOS x86 64 bits ou macOS ARM 64 bits) ou utilize o curl para baixar o pacote. O exemplo a seguir mostra como usar o comando curl em um sistema macOS ARM64:
```
curl -o ossutil-2.3.0-mac-arm64.zip  https://gosspublic.alicdn.com/ossutil/v2/2.3.0/ossutil-2.3.0-mac-arm64.zip
```
No diretório de baixe, descompacte o pacote:
```
unzip ossutil-2.3.0-mac-arm64.zip
```
Acesse o diretório ossutil-2.3.0-mac-arm64.
```
cd ossutil-2.3.0-mac-arm64
```
Conceda permissões de execução ao arquivo ossutil:
```
chmod 755 ossutil
```

Execute o comando a seguir para tornar o ossutil disponível globalmente.

sudo mv ossutil /usr/local/bin/ && sudo ln -s /usr/local/bin/ossutil /usr/bin/ossutil

Verifique a instalação:
```
ossutil
```
A instalação terá sido bem-sucedida se o ossutil exibir suas informações de ajuda.

Configure o ossutil

Para evitar erros causados por configurações ausentes, recomendamos o uso do assistente de configuração do ossutil para defina rapidamente seu AccessKey id, AccessKey Secret e id da região. Para opções avançadas, consulte o Guia de configuração para configure credenciais de acesso manualmente.

Este exemplo demonstra como usar o assistente de configuração para defina rapidamente o par de AccessKeys de um usuário ram como suas credenciais de acesso.

Linux

Insira o comando de configuração.
```
ossutil config
```

Quando solicitado, defina o caminho para o arquivo de configuração. Pressione Enter para utilizar o caminho padrão.

Please enter the config file name,the file name can include path(default /root/.ossutilconfig, carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

Por padrão, o ossutil utiliza /root/.ossutilconfig como arquivo de configuração.

Siga as instruções na tela para defina o AccessKey id, o AccessKey Secret e o id da região.

Insira seu AccessKey id.

Please enter Access Key ID [****************id]:yourAccessKeyID

Insira seu AccessKey Secret.

Please enter Access Key Secret [****************sk]:yourAccessKeySecret

Informe a região do data center do oss. Se deixar em branco, o valor padrão será cn-hangzhou.
```
Please enter Region [ap-southeast-1]:ap-southeast-1
```
Informe o endpoint do data center do oss. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após defina a região, o ossutil utiliza o endpoint público correspondente por padrão. Por exemplo, se você defina o region-id como ap-southeast-1, o endpoint público padrão será https://oss-ap-southeast-1.aliyuncs.com.

Se precisar de um endpoint personalizado para a região onde seu data center do oss está localizado, informe o endpoint. Por exemplo, para acessar o oss a partir de outros serviços do Alibaba Cloud na mesma região, utilize um endpoint interno, como https://oss-ap-southeast-1-internal.aliyuncs.com.
```
Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
```

A tabela a seguir descreve os parâmetros.

Parâmetro	Obrigatório	Descrição
accessKeyID	Sim	O par de AccessKeys da sua conta. Para saber como obter um par de AccessKeys, consulte Crie um par de AccessKeys. Para crie rapidamente um usuário ram com permissões de gerenciamento do oss e um par de AccessKeys, utilize um script do Resource Orchestration Service (ROS): Na página Create Stack do console do Resource Orchestration Service (ROS), marque a caixa de seleção de confirmação em Security Confirmation e clique em Create. Após a criação da stack, copie o par de AccessKeys na aba Outputs.
accessKeySecret	Sim
Region	Sim	O id da região onde o bucket está localizado. Este tópico utiliza a região Singapura como exemplo. Defina este parâmetro como `ap-southeast-1`. Para mais informações sobre os IDs de outras regiões, consulte Regiões e endpoints.
endpoint	Não	O endpoint da região onde o bucket está localizado. Se você não defina um endpoint manualmente, um endpoint público será gerado automaticamente com base na região. É necessário especifique explicitamente um endpoint interno. Por exemplo, este tópico usa o endpoint público para a região Singapura. Defina este parâmetro como `https://oss-ap-southeast-1.aliyuncs.com`. Para acessar o oss a partir de outros serviços do Alibaba Cloud na mesma região, utilize um endpoint interno. Defina este parâmetro como `https://oss-ap-southeast-1-internal.aliyuncs.com`. Para mais informações sobre os endpoints de diferentes regiões, consulte Regiões e endpoints. Importante Devido a uma alteração de política visando melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do oss devem usar um nome de domínio personalizado (CNAME) para execute operações de API de dados em buckets do oss localizados em regiões da China continental. Os endpoints públicos padrão estão restritos para essas operações. Consulte o comunicado oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via https, deverá vincular um Certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao Console do oss, pois o console impõe o uso de https.

Windows

Insira o comando de configuração.
```
ossutil config
```

Quando solicitado, defina o caminho para o arquivo de configuração. Pressione Enter para utilizar o caminho padrão.

Please enter the config file name,the file name can include path(default "C:\Users\issuser\.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

Por padrão, o ossutil utiliza C:\Users\issuser\.ossutilconfig como arquivo de configuração.

Siga as instruções na tela para defina o AccessKey id, o AccessKey Secret e o id da região.

Insira seu AccessKey id.

Please enter Access Key ID [****************id]:yourAccessKeyID

Insira seu AccessKey Secret.

Please enter Access Key Secret [****************sk]:yourAccessKeySecret

Informe a região do data center do oss. Se deixar em branco, o valor padrão será cn-hangzhou.
```
Please enter Region [ap-southeast-1]:ap-southeast-1
```
Informe o endpoint do data center do oss. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após defina a região, o ossutil utiliza o endpoint público correspondente por padrão. Por exemplo, se você defina o region-id como ap-southeast-1, o endpoint público padrão será https://oss-ap-southeast-1.aliyuncs.com.

Se precisar de um endpoint personalizado para a região onde seu data center do oss está localizado, informe o endpoint. Por exemplo, para acessar o oss a partir de outros serviços do Alibaba Cloud na mesma região, utilize um endpoint interno, como https://oss-ap-southeast-1-internal.aliyuncs.com.
```
Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
```

A tabela a seguir descreve os parâmetros.

Parâmetro	Obrigatório	Descrição
accessKeyID	Sim	O par de AccessKeys da sua conta. Para saber como obter um par de AccessKeys, consulte Crie um par de AccessKeys. Para crie rapidamente um usuário ram com permissões de gerenciamento do oss e um par de AccessKeys, utilize um script do Resource Orchestration Service (ROS): Na página Create Stack do console do Resource Orchestration Service (ROS), marque a caixa de seleção de confirmação em Security Confirmation e clique em Create. Após a criação da stack, copie o par de AccessKeys na aba Outputs.
accessKeySecret	Sim
Region	Sim	O id da região onde o bucket está localizado. Este tópico utiliza a região Singapura como exemplo. Defina este parâmetro como `ap-southeast-1`. Para mais informações sobre os IDs de outras regiões, consulte Regiões e endpoints.
endpoint	Não	O endpoint da região onde o bucket está localizado. Se você não defina um endpoint manualmente, um endpoint público será gerado automaticamente com base na região. É necessário especifique explicitamente um endpoint interno. Por exemplo, este tópico usa o endpoint público para a região Singapura. Defina este parâmetro como `https://oss-ap-southeast-1.aliyuncs.com`. Para acessar o oss a partir de outros serviços do Alibaba Cloud na mesma região, utilize um endpoint interno. Defina este parâmetro como `https://oss-ap-southeast-1-internal.aliyuncs.com`. Para mais informações sobre os endpoints de diferentes regiões, consulte Regiões e endpoints. Importante Devido a uma alteração de política visando melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do oss devem usar um nome de domínio personalizado (CNAME) para execute operações de API de dados em buckets do oss localizados em regiões da China continental. Os endpoints públicos padrão estão restritos para essas operações. Consulte o comunicado oficial para obter a lista completa das operações afetadas. Se você acessar seus dados via https, deverá vincular um Certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso ao Console do oss, pois o console impõe o uso de https.

macOS

Insira o comando de configuração.
```
ossutil config
```

Quando solicitado, defina o caminho para o arquivo de configuração. Pressione Enter para utilizar o caminho padrão.

Please enter the config file name,the file name can include path(default "/Users/user/.ossutilconfig", carriage return will use the default file. If you specified this option to other file, you should specify --config-file option to the file when you use other commands):

Por padrão, o ossutil utiliza /Users/user/.ossutilconfig como arquivo de configuração.

Siga as instruções na tela para defina o AccessKey id, o AccessKey Secret e o id da região.

Insira seu AccessKey id.

Please enter Access Key ID [****************id]:yourAccessKeyID

Insira seu AccessKey Secret.

Please enter Access Key Secret [****************sk]:yourAccessKeySecret

Informe a região do data center do oss. Se deixar em branco, o valor padrão será cn-hangzhou.
```
Please enter Region [ap-southeast-1]:ap-southeast-1
```
Informe o endpoint do data center do oss. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após defina a região, o ossutil utiliza o endpoint público correspondente por padrão. Por exemplo, se você defina o region-id como ap-southeast-1, o endpoint público padrão será https://oss-ap-southeast-1.aliyuncs.com.

Caso precise de um endpoint personalizado para a região onde seu data center do oss está localizado, insira o endpoint desejado. Por exemplo, para acessar o oss a partir de outros serviços da Alibaba Cloud na mesma região, utilize um endpoint interno, como https://oss-ap-southeast-1-internal.aliyuncs.com.
```
Please enter Endpoint (optional, use public endpoint by default) [None]: https://oss-ap-southeast-1-internal.aliyuncs.com
```

A tabela a seguir descreve os parâmetros.

Parâmetro	Obrigatório	Descrição
accessKeyID	Sim	O par de AccessKey da sua conta. Para saber como obter um par de AccessKey, consulte Crie um par de AccessKey. Para crie rapidamente um usuário ram com permissões de gerenciamento do oss e um par de AccessKey, utilize um script do Resource Orchestration Service (ROS): Na página Create Stack do console do Resource Orchestration Service (ROS), selecione a caixa de confirmação em Security Confirmation e clique em Create. Após a criação da stack, copie o par de AccessKey na aba Outputs.
accessKeySecret	Sim
Region	Sim	O id da região onde o bucket está localizado. Este tópico utiliza a região Singapore como exemplo. Defina este parâmetro como `ap-southeast-1`. Para mais informações sobre os IDs de outras regiões, consulte Regiões e endpoints.
endpoint	Não	O endpoint da região onde o bucket está localizado. Se você não defina manualmente um endpoint, um endpoint público será gerado automaticamente com base na região. É necessário especifique explicitamente um endpoint interno. Por exemplo, este tópico usa o endpoint público para a região Singapore. Defina este parâmetro como `https://oss-ap-southeast-1.aliyuncs.com`. Para acessar o oss a partir de outros serviços da Alibaba Cloud na mesma região, utilize um endpoint interno. Defina este parâmetro como `https://oss-ap-southeast-1-internal.aliyuncs.com`. Para mais informações sobre os endpoints de diferentes regiões, consulte Regiões e endpoints. Importante Devido a uma alteração de política visando melhorar a conformidade e a segurança, a partir de 20 de março de 2025, novos usuários do oss devem utilizar um nome de domínio personalizado (CNAME) para execute operações de API de dados em buckets do oss localizados em regiões da China continental. Os endpoints públicos padrão têm acesso restrito para essas operações. Consulte o anúncio oficial para obter a lista completa das operações afetadas. Se você acessa seus dados via https, é obrigatório vincular um certificado SSL válido ao seu domínio personalizado. Isso é obrigatório para acesso pelo Console do oss, pois o console impõe o uso de https.

Execute comandos

Crie um bucket.
```
ossutil mb oss://examplebucket
```
A saída a seguir indica que o bucket examplebucket foi criado.
```
0.668238(s) elapsed
```
Faça upload de um arquivo para o bucket.
1. Crie um arquivo local chamado uploadFile.txt.
```
echo 'Hello, OSS!' > uploadFile.txt
```
2. Envie o arquivo para o bucket examplebucket.
```
ossutil cp uploadFile.txt oss://examplebucket
```
  A saída abaixo confirma que o arquivo foi enviado com sucesso para examplebucket.
```
Success: Total 1 file, size 12 B, Upload done:(1 objects, 12 B), avg 44 B/s

0.271779(s) elapsed
```
Baixe um arquivo.

Transfira o arquivo uploadFile.txt do bucket examplebucket para o diretório localfolder.
```
ossutil cp oss://examplebucket/uploadFile.txt localfolder/
```
O resultado a seguir mostra que o baixe do arquivo para o diretório localfolder ocorreu com êxito.
```
Success: Total 1 object, size 12 B, Download done:(1 files, 12 B), avg 74 B/s

0.162447(s) elapsed
```

Liste os arquivos no bucket examplebucket.

ossutil ls oss://examplebucket

Esta saída indica que os arquivos do bucket examplebucket foram listados corretamente.

LastModifiedTime                   Size(B)  StorageClass   ETAG                                  ObjectName
2024-11-26 14:35:29 +0800 CST           12      Standard   1103F650EB2C292D179A032D2A97B0F5      oss://examplebucket/uploadFile.txt
Object Number is: 1

0.124679(s) elapsed

Exclua o arquivo uploadFile.txt do bucket examplebucket.
```
ossutil rm oss://examplebucket/uploadFile.txt
```
A mensagem seguinte confirma a exclusão bem-sucedida do arquivo uploadFile.txt no bucket examplebucket.
```
0.295530(s) elapsed
```
Remova o bucket examplebucket.
```
ossutil rb oss://examplebucket
```
O retorno abaixo sinaliza que o bucket examplebucket foi exclua com sucesso.
```
0.478659(s) elapsed
```

Configuração

O ossutil oferece alta flexibilidade e permite configuração por meio de arquivo de configuração, variáveis de ambiente ou opções de linha de comando.

Precedência de configuração

O ossutil lê as configurações seguindo esta ordem de prioridade:

opções de linha de comando (como -i, -k e -e) > variáveis de ambiente (como OSS_ACCESS_KEY_ID) > arquivo de configuração (~/.ossutilconfig)

Nota

A partir da versão 2.2.0, é possível usar a opção de linha de comando --ignore-env-var para ignorar variáveis de ambiente com o prefixo OSS_.
Desde a versão 2.3.0, as opções --job, --parallel, --bigfile-threshold, --part-size e --write-buffer-size podem ser definidas no arquivo de configuração. Adicione-as no formato chave=valor, como job=10, à seção de perfil correspondente no arquivo de configuração, ou utilize o comando ossutil config set para gravá-las. As opções de linha de comando possuem prioridade superior às do arquivo de configuração.

Arquivo de configuração

É possível configure o ossutil utilizando um arquivo de configuração. O caminho padrão é ~/.ossutilconfig, mas você pode especifique um caminho personalizado usando a flag -c. Ao adotar o arquivo de configuração padrão, execute comandos do ossutil diretamente sem informar o caminho do arquivo. Exemplo:

ossutil ls oss://examplebucket

Se optar por um caminho de arquivo de configuração personalizado, como /path/yourconfig, será necessário usar a opção -c para indicar o caminho. Veja o exemplo:

ossutil -c /path/yourconfig ls oss://examplebucket

Formato do arquivo de configuração

O arquivo de configuração adota o formato INI, organizando as definições em seções compostas por pares chave-valor. Utilize a opção --profile para escolher uma seção específica. Por padrão, o ossutil aplica as configurações da seção [default]. Caso precise de um conjunto diferente de parâmetros, crie e referencie outras seções.

Seções e pares chave-valor

Cada seção do arquivo de configuração é identificada por um nome entre colchetes [ ], e as configurações dentro dela seguem o formato chave=valor. Por exemplo:

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

As definições dentro da seção obedecem ao formato chave=valor.
Nomes de seções e chaves não diferenciam maiúsculas de minúsculas.
As chaves dos parâmetros de configuração aceitam diversos formatos, incluindo tudo em minúsculas, camelCase, kebab-case (separado por hífen) e snake_case (separado por sublinhado). Assim, accesskeyid, accessKeyId, access-key-id e access_key_id são interpretados como o mesmo nome de parâmetro.
Linhas iniciadas com o caractere cerquilha (#) são consideradas comentários.

Tipos de seção suportados

Nome da seção	Descrição	Observações
[default]	Armazena as configurações padrão. Esta seção é utilizada quando a opção `--profile` não está definida.	Forma simplificada de `[profile default]`.
[profile name]	Configure parâmetros referenciados por meio de `--profile name`.	Permite referenciar outras configurações usando `source_profile`.
[buckets name]	Defina endpoints para buckets específicos, incluindo `region`, `endpoint` e `addressing style`.	Suporta notação inline.

Nota

Use o comando config para visualize e defina configurações. Para mais informações, consulte config.

Profile

Esta seção configure credenciais de acesso e parâmetros globais. Os seguintes parâmetros são suportados:

Parâmetros de credencial de acesso

Parâmetro	Alias	Descrição
mode	/	Especifica o modo de autenticação. Valores válidos: `AK`, `StsToken`, `RamRoleArn`, `EcsRamRole` e `Anonymous`.
access-key-id	accessKeyId access_key_id	O AccessKey id usado para acessar o oss.
access-key-secret	accessKeySecret access_key_secret	O AccessKey Secret usado para acessar o oss.
sts-token	stsToken sts_token	O token de segurança usado para acessar o oss.
role-arn	roleArn role_arn	O ARN da função ram. Este parâmetro é usado principalmente no modo `RamRoleArn`.
role-session-name	roleSessionName role_session_name	O nome da sessão. Este parâmetro é usado principalmente no modo `RamRoleArn`.
ecs-role-name	ecsRoleName ecs_role_name	O nome da função. Este parâmetro é usado principalmente no modo `EcsRamRole`.
credential-process	credentialProcess credential_process	Especifica um comando externo.
credential-uri	credentialUri credential_uri	Especifica uma URI para obter credenciais de acesso.
oidc-provider-arn	oidcProviderArn oidc_provider_arn	Especifica o ARN do provedor OIDC no formato `acs:ram::account-id:oidc-provider/provider-name`.
oidc-token-file-path	oidcTokenFilePath oidc_token_file_path	Especifica o caminho do arquivo onde o token OIDC está armazenado.
credential-process-timeout	credentialProcessTimeout credential_process_timeout	Defina o tempo limite para uma solicitação de credencial externa, em segundos. O valor padrão é 15 segundos e o máximo é 600 segundos (10 minutos). Por exemplo, `credential-process-timeout = 60` defina um tempo limite de 60 segundos. Este recurso é suportado na versão 2.0.3 e posteriores.

Parâmetros globais

Parâmetro	Alias	Descrição
region	/	O id da região. Este parâmetro é obrigatório.
loglevel	/	O nível de log. Valores válidos: `off` (padrão) `info` `debug`
read-timeout	readTimeout read_timeout	O tempo limite para solicitações de leitura e gravação do cliente, em segundos. Valor padrão: 20.
connect-timeout	connectTimeout connect_timeout	O tempo limite para conexões do cliente, em segundos. Valor padrão: 10.
retry-times	retryTimes retry_times	O número de tentativas para repetir uma solicitação com falha. Valor padrão: 10.
skip-verify-cert	skipVerifyCert skip_verify_cert	Ignora a verificação do certificado digital no lado do servidor.
sign-version	signVersion sign_version	A versão do algoritmo de assinatura usada nas solicitações. Valores válidos: `v1` `v4` (padrão)
output-format	outputFormat output_format	O formato de saída. Valores válidos: `raw` (padrão) `json` `xml` `yaml`
addressing-style	addressingStyle addressing_style	O formato do endereço da solicitação. Valores válidos: `virtual` (padrão) `path` `cname`
language	/	O idioma de exibição.
endpoint	/	O endpoint do serviço. Este parâmetro é opcional.

Outros parâmetros

Parâmetro	Alias	Descrição
source-profile	sourceProfile source_profile	Referencia parâmetros de um perfil especificado. Exemplo: `[profile cred] access-key-id=ak access-key-secret=sk [profile dev] region=cn-hangzhou source-profile=cred`
buckets	/	Referencia parâmetros de uma seção `buckets` especificada. `[profile dev] region=cn-hangzhou access-key-id=ak access-key-secret=sk buckets=dev-bucket [buckets dev-bucket] bucket-name-hz = endpoint=oss-cn-hangzhou-internal.aliyuncs.com bucket-name-bj = region=cn-beijing`
endpoint-suffix-list-path-style	/	Especifica a lista de sufixos de endpoint que usam automaticamente o modo de solicitação path-style. Múltiplos sufixos são separados por vírgula (`,`). Suportado a partir da versão 2.2.0. Exemplo 1: `endpoint-suffix-list-path-style=DEFAULT` Exemplo 2: `endpoint-suffix-list-path-style=DEFAULT,.path-style.com` `DEFAULT` indica a lista padrão integrada, que atualmente é .privatelink.aliyuncs.com.

Buckets

Esta seção configure mapeamentos entre buckets e endpoints. Ela suporta uma estrutura aninhada onde subseções para buckets individuais são definidas usando bucket-name =. O formato é o seguinte:

[buckets name]
bucket-name = 
  key=value

Neste formato, name é o nome da seção buckets, bucket-name é o nome de um bucket específico e key=value representa um parâmetro de configuração. Os seguintes parâmetros são suportados:

Parâmetro	Alias	Descrição
region	/	A região onde o data center está localizado. Se não for definido, o valor de `region` do perfil que referencia este parâmetro será usado.
endpoint	/	O endpoint do serviço. Este parâmetro é opcional.
addressing-style	addressingStyle addressing_style	O formato do endereço da solicitação. Valores válidos: `virtual` (padrão): Usa o formato de endereço de solicitação virtual-hosted-style. `path`: Usa o formato de endereço de solicitação path-style. `cname`: Usa o formato de endereço de solicitação CNAME.

Veja abaixo um exemplo de seção buckets:

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

Configure variáveis de ambiente

Linux

Execute os comandos a seguir para adicionar as definições de variáveis de ambiente ao arquivo ~/.bashrc:

echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.bashrc

Execute o comando a seguir para aplicar as alterações:
```
source  ~/.bashrc
```
Execute os comandos a seguir para verifique se as variáveis de ambiente entraram em vigor:
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

No terminal, execute o comando a seguir para visualize o tipo de shell padrão:
```
echo $SHELL
```
Zsh
1. Execute os comandos a seguir para adicionar as definições de variáveis de ambiente ao arquivo ~/.zshrc:
  echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.zshrc
2. Execute o comando a seguir para aplicar as alterações:
  source ~/.zshrc
3. Execute os comandos a seguir para verifique se as variáveis de ambiente entraram em vigor:
  echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
Bash
1. Execute os comandos a seguir para adicionar as definições de variáveis de ambiente ao arquivo ~/.bash_profile:
  echo "export OSS_ACCESS_KEY_ID='your-access-key-id'" >> ~/.bash_profile echo "export OSS_ACCESS_KEY_SECRET='your-access-key-secret'" >> ~/.bash_profile
2. Execute o comando a seguir para aplicar as alterações:
  source ~/.bash_profile
3. Execute os comandos a seguir para verifique se as variáveis de ambiente entraram em vigor:
  echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET

Windows

Execute os comandos a seguir no Prompt de Comando (CMD):

setx OSS_ACCESS_KEY_ID "your-access-key-id"
setx OSS_ACCESS_KEY_SECRET "your-access-key-secret"

Abra uma nova janela do CMD.
Na nova janela do CMD, execute os comandos a seguir para verifique se as variáveis de ambiente entraram em vigor:
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

As seguintes variáveis de ambiente são suportadas:

Variável de ambiente	Parâmetro
OSS_ACCESS_KEY_ID	access-key-id
OSS_ACCESS_KEY_SECRET	access-key-secret
OSS_SESSION_TOKEN	sts-token
OSS_ROLE_ARN	role-arn
OSS_ROLE_SESSION_NAME	role-session-name
OSS_REGION	region
OSS_ENDPOINT	endpoint
OSSUTIL_CONFIG_FILE	config-file
OSSUTIL_PROFILE	profile

Opções de linha de comando

O ossutil oferece diversas opções de linha de comando, incluindo opções globais de linha de comando. As opções de linha de comando têm a maior precedência e substituem parâmetros definidos no arquivo de configuração ou em variáveis de ambiente.

Importante

Passar chaves de acesso por meio de opções de linha de comando pode expô-las em sistemas de log, criando um risco de segurança. Use este método com cautela.

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret" --region cn-hangzhou

Credenciais de acesso

Par de AccessKey de usuário ram

Se sua aplicação executa em um ambiente seguro, requer acesso de longo prazo ao oss e não pode rotacionar credenciais frequentemente, inicialize o provedor de credenciais com o par AccessKey (AccessKey id e AccessKey Secret) de uma conta Alibaba Cloud ou de um usuário ram. Este método exige manutenção manual de um par AccessKey, o que aumenta tanto os riscos de segurança quanto a sobrecarga de manutenção.

Arquivo de configuração

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Variáveis de ambiente

export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket

Opções de linha de comando

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret

Credencial de segurança temporária

Caso sua aplicação necessite de acesso temporário ao oss, inicialize o provedor de credenciais com uma credencial de segurança temporária (AccessKey id, AccessKey Secret e token de segurança) obtida do Security Token Service (STS). Este método requer manutenção manual do token de segurança, aumentando os riscos de segurança e a complexidade. Além disso, você deve atualize o token manualmente para acessos temporários repetidos.

Arquivo de configuração

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig.

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Variáveis de ambiente

export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

Opções de linha de comando

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken --region cn-hangzhou

ARN de função ram

Se sua aplicação precisa de acesso autorizado ao oss, por exemplo, para acessar o oss entre contas Alibaba Cloud, use RAMRoleARN para inicializar o provedor de credenciais. Este método utiliza tokens STS internamente. Ao especifique o ARN (Alibaba Cloud Resource Name) de uma função ram, a ferramenta de credenciais obtém um token STS do serviço STS e chama a API AssumeRole para solicitar um novo token STS antes que a sessão expire. Adicionalmente, atribua um valor a policy para restringir a função ram a um conjunto menor de permissões.

Importante

Uma conta Alibaba Cloud possui permissões totais sobre seus recursos. Se o par AccessKey de uma conta Alibaba Cloud vazar, isso representa um risco significativo de segurança para o seu sistema. Recomendamos usar o par AccessKey de um usuário ram com as permissões mínimas necessárias.
Para crie um par AccessKey para um usuário ram, consulte Crie um par AccessKey. O AccessKey id e o AccessKey Secret de um usuário ram são exibidos apenas no momento da criação. Salve-os imediatamente. Se esquecer o par AccessKey, crie um novo para rotacionar suas credenciais.
Para obter um ARN de função ram, consulte Crie uma função.

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig. Esta configuração não pode ser definida usando variáveis de ambiente ou opções de linha de comando.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1

Para consultar objetos no bucket examplebucket, execute o comando a seguir:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Função ram de instância ecs

Se sua aplicação executa em uma instância ecs, uma instância ECI ou um nó worker do Container Service for Kubernetes, recomendamos usar ECSRAMRole para inicializar o provedor de credenciais. Este método usa tokens STS em sua implementação subjacente. Um ECSRAMRole permite associar uma função a uma instância ecs, uma instância ECI ou um nó worker do Container Service for Kubernetes para atualize automaticamente o token STS dentro da instância. Este método elimina a necessidade de fornecer um AccessKey (AK) ou um token STS e remove os riscos associados à manutenção manual. Para mais informações sobre como obter um ECSRAMRole, consulte Crie uma função.

Nota

Este método não pode ser configurado usando variáveis de ambiente.

Modo EcsRamRole

Arquivo de configuração

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig.

[default]
mode = EcsRamRole
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

CLI

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket --mode EcsRamRole

Modo EcsRamRole IMDSv2****

Nota

O modo EcsRamRole IMDSv2 é suportado no ossutil 2.2.0 e versões posteriores.

Arquivo de configuração

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig.

[default]
mode = Ali-EcsRamRole
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

CLI

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket --mode Ali-EcsRamRole

ARN de função OIDC

Após configure uma função ram de nó worker no Container Service for Kubernetes, aplicações em Pods nesse nó podem obter o token STS para a função associada através do serviço de metadados, assim como aplicações implantadas em instâncias ecs. No entanto, se aplicações não confiáveis, como aplicações enviadas por clientes com código fechado, forem implantadas no cluster de contêineres, talvez você não queira que elas obtenham o token STS da função ram associada à instância do nó worker através do serviço de metadados. Para evitar comprometer a segurança dos seus recursos de nuvem e, ao mesmo tempo, permitir que essas aplicações não confiáveis obtenham com segurança os tokens STS necessários e implementem privilégio mínimo no nível da aplicação, use o recurso RRSA (ram Roles for Service Account). Este método baseia-se em tokens STS. O cluster de contêineres Alibaba Cloud cria e monta um arquivo de token OIDC de conta de serviço correspondente para cada Pod de aplicação e injeta as informações de configuração relacionadas em variáveis de ambiente. Uma ferramenta de credenciais então recupera as informações de configuração das variáveis de ambiente e chama a API AssumeRoleWithOIDC do serviço STS para trocar o token OIDC por um token STS associado à função. Este método não exige que você forneça um Access Key (AK) ou um token STS, eliminando os riscos associados à manutenção manual de AKs ou tokens STS. Para mais informações, consulte Configure permissões ram para um ServiceAccount usando RRSA para implementar isolamento de permissões no nível de pod.

Crie o seguinte arquivo de configuração e salve-o como ~/.ossutilconfig. Você não pode especifique esta configuração usando variáveis de ambiente ou opções de linha de comando.

[default]
mode = oidcRoleArn
# Specifies the ARN (Aliyun Resource Name) of the OIDC provider. The format is acs:ram::account-id:oidc-provider/provider-name.
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Specifies the file path where the OIDC token is stored.
OIDCTokenFilePath=OIDCTokenFilePath
# The ARN of the role to assume. The format is acs:ram::account-id:role/role-name.
roleArn=acs:ram::113511544585****:role/testoidc
# A custom role session name to distinguish different tokens.
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Credenciais de processo externo

O ossutil pode execute um comando externo para obter credenciais. O processo externo retorna as credenciais ao ossutil através da saída padrão (stdout).

Nota

Para evitar riscos de segurança, o comando que gera credenciais não deve ser acessível a usuários ou processos não autorizados.
O comando que gera credenciais não deve gravar nenhuma informação confidencial em stderr ou stdout, pois essas informações podem ser capturadas em logs e expostas a usuários não autorizados.

O comando externo pode retornar uma credencial de longo prazo ou uma credencial temporária nos seguintes formatos.

Credencial de longo prazo

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk"
}

Credencial temporária

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token"
}

Crie o seguinte arquivo de configuração e salve-o em ~/.ossutilconfig. Estas configurações não podem ser definidas usando variáveis de ambiente ou opções de linha de comando.

[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1

Execute o comando a seguir para consultar objetos no bucket examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Acesso anônimo

Se você precisar apenas acessar recursos oss com a permissão public-read, use o acesso anônimo sem fornecer credenciais.

ossutil cat oss://bucket/public-object --mode Anonymous

Referência de comandos

O ossutil fornece três tipos de comandos: comandos de alto nível, comandos de nível de API e comandos auxiliares.

Estrutura de comandos

A sintaxe básica para comandos ossutil é a seguinte:

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

argument: Um argumento de string.
flags: Opções com formato de nome curto (-o[=value]/ -o [ value]) e formato de nome longo (--options[=value]/--options[ value]). Se você especifique uma flag exclusiva mais de uma vez, apenas o último valor será usado.

Veja a seguir exemplos de comandos:

Comando: ossutil cat oss://bucket/object
Comando com subcomando: ossutil api get-bucket-cors --bucket bucketexample
Tópico de ajuda: ossutil filter

Lista de comandos

Comandos de alto nível

Estes comandos servem para gerencie buckets e objetos. Utilize-os para crie e exclua buckets, copiar dados e modifique propriedades de objetos.

Nome do comando	Significado
mb	Crie um bucket
rb	Exclua um bucket
du	Obtém o tamanho de armazenamento de um bucket ou de um prefixo especificado
stat	Exibe a descrição de um bucket ou objeto
mkdir	Crie um objeto cujo nome termina com o caractere de sufixo `/`
append	Adiciona conteúdo a um objeto anexável
cat	Concatena o conteúdo do objeto na saída padrão
ls	Lista buckets ou objetos
cp	Faz upload, baixe ou cópia de objetos
rm	Exclua objetos em um bucket
set-props	Defina as propriedades de um objeto
presign	Gera uma URL assinada para um objeto
restore	Restaura um objeto do estado congelado para um estado legível
revert (restore version)	Reverte um objeto para uma versão especificada
sync	Sincroniza um diretório local ou objetos de uma source para um destino
hash	Calcula o valor de hash de um arquivo ou objeto

Comandos de nível de API: Estes comandos fornecem acesso direto às operações da API e seus argumentos de configuração.

Nota

Apenas alguns comandos estão listados. Execute ossutil api -h para visualize todos os comandos.

Nome do comando	Descrição
put-bucket-acl	Defina ou modifique as permissões de acesso de um bucket.
get-bucket-acl	Obtém as permissões de acesso de um bucket.
....
put-bucket-cors	Defina as regras de compartilhamento de recursos de source cruzada (CORS) para um bucket.
get-bucket-cors	Obtém as regras CORS de um bucket.
delete-bucket-cors	Exclua as regras CORS de um bucket.

Comandos auxiliares: Utilize estes comandos para gerencie arquivos de configuração e acessar tópicos de ajuda adicionais.

Nome do comando	Descrição
help	Obtém informações de ajuda.
config	Crie um arquivo de configuração para armazenar itens de configuração e credenciais de acesso.
update	Atualize a versão.
version	Exibe informações sobre a versão.
probe	Executa uma sondagem.

Tipos de opções de comando

Tipo de opção	Sinalizador	Descrição
String	`--option string`	Um argumento de string pode conter caracteres alfanuméricos, símbolos e espaços do conjunto de caracteres ASCII. Coloque valores que contenham espaços entre aspas. Por exemplo: `--acl private`.
Booleano	`--option`	Ativa ou desativa um sinalizador. Por exemplo: `--dry-run`.
Inteiro	`--option Int`	Um inteiro sem sinal. Por exemplo: `--read-timeout 10`.
Timestamp	`--option Time`	Um timestamp no formato ISO 8601 (DateTime ou Date). Por exemplo: `--max-mtime 2006-01-02T15:04:05`.
Sufixo de unidade de byte	`--option SizeSuffix`	A unidade padrão é o byte (B). Também é possível usar sufixos. Os sufixos suportados são: K (KiB) = 1024 bytes, M (MiB), G (GiB), T (TiB), P (PiB) e E (EiB). Por exemplo, para um tamanho mínimo de 1024 bytes: `--min-size 1024` `--min-size 1K`
Sufixo de unidade de tempo	`--option Duration`	Uma duração de tempo. A unidade padrão é segundos. Os sufixos suportados são: ms (milissegundos), s (segundos), m (minutos), h (horas), d (dias), w (semanas), M (meses) e y (anos). Valores decimais são suportados. Por exemplo: 1,5 dias. `--min-age 1.5d`
Lista de strings	`--option strings`	Permite especifique o sinalizador várias vezes. Um único sinalizador também pode aceitar múltiplos valores separados por vírgula (`,`). Suporta múltiplas instâncias de um único valor. Por exemplo: `--metadata user=jack,email=ja**@test.com --metadata address=china`
Array de strings	`--option stringArray`	Permite especifique o sinalizador várias vezes. Cada instância aceita apenas um único valor. Por exemplo: `--include .jpg --include .txt`.

Carregar dados de outras fontes

Embora os argumentos sejam normalmente fornecidos na linha de comando, valores complexos podem ser carregados de um arquivo. Também é possível canalizar dados da entrada padrão, o que é útil para encadear comandos.

Iniciar com file:// indica que o conteúdo será carregado de um caminho de arquivo.
Um valor de parâmetro igual a - indica que os dados serão carregados da entrada padrão.

Por exemplo, para defina as configurações de compartilhamento de recursos de source cruzada (CORS) de um bucket, carregue a configuração de um arquivo JSON. O arquivo cors-configuration.json tem o seguinte conteúdo:

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

Alternativamente, forneça a configuração CORS diretamente como valor da opção. A string JSON compacta é a seguinte:

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

O exemplo a seguir mostra como carregar argumentos da entrada padrão:

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

Controlar a saída do comando

Formato de saída

Para os subcomandos do comando api e para os comandos du e stat, ajuste o formato de saída usando o parâmetro --output-format. Os formatos suportados são:

Nome do formato	Descrição
raw	A saída corresponde aos dados brutos retornados pelo servidor.
json	A saída é formatada como uma string JSON.
yaml	A saída é formatada como uma string YAML.
xml	A saída é formatada como uma string XML.

Por exemplo, o conteúdo original para get-bucket-cors é o seguinte:

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

A saída JSON é a seguinte:

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

Filtrar saída

O ossutil oferece um recurso integrado de filtragem no lado do cliente baseado em JSON por meio do sinalizador --output-query value.

Nota

Esta opção é suportada apenas para subcomandos de ossutil api.

Este recurso baseia-se na sintaxe JMESPath. Ao utilizá-lo, a saída é convertida para JSON, filtrada com JMESPath e exibida no formato de saída especificado. Para mais informações sobre a sintaxe JMESPath, consulte Especificação JMESPath.

Por exemplo, para exibir apenas o conteúdo de AllowedMethod do comando get-bucket-cors, execute o seguinte comando:

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

Formato legível por humanos

Para comandos de alto nível (du, stat), a opção --human-readable está disponível para exibir dados de bytes e quantidades em um formato legível. Dados em bytes são convertidos para um formato com sufixos Ki, Mi, Gi, Ti ou Pi (base 1024), e dados de quantidade são convertidos para um formato com sufixos k, m, g, t ou p (base 1000).

Exemplo: Modo bruto

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

Modo legível por humanos

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

Códigos de retorno de comandos

Ao execute o ossutil em um script, verifique o código de retorno final para confirmar o resultado. Esse código indica se a operação foi bem-sucedida e permite tratar erros programaticamente.

Linux

Execute o comando para obter o código de retorno: echo $?.

Windows

Execute o comando para obter o código de retorno: echo %errorlevel%.

macOS

Execute o comando para obter o código de retorno: echo $?.

Código de retorno	Descrição
0	A operação do comando foi bem-sucedida. A solicitação enviada ao servidor foi executada corretamente e o servidor retornou uma resposta 200.
1	Parâmetro inválido. Este erro ocorre quando falta um subcomando ou parâmetro obrigatório, ou quando se utiliza um comando ou parâmetro desconhecido.
2	O comando foi analisado com sucesso e uma solicitação foi enviada ao serviço especificado, mas o serviço retornou um erro (uma resposta não-2xx).
3	Foi encontrado um erro não relacionado ao servidor durante a chamada do oss Go SDK.
4	Algumas solicitações falharam durante uma operação em lote, como cp ou rm.
5	Erro de interrupção. Um comando foi cancelado pressionando ctrl + c durante a execução.

Opções de linha de comando

Alguns comandos exigem parâmetros para especifique um alvo ou uma opção. Para esses comandos, forneça os valores necessários. Por exemplo:

ossutil ls --profile dev

O comando ossutil ls --profile dev especifica o perfil de configuração dev. Para opções que exigem um valor de parâmetro, separe o nome da opção do valor com um espaço ou um sinal de igual (=), como --profile dev ou --profile=dev. Coloque valores de parâmetro que contenham espaços entre aspas duplas para garantir que sejam analisados corretamente, por exemplo, --description "OSS bucket list".

Opções globais de linha de comando

Parâmetro	Tipo	Descrição
-i, --access-key-id	string	Especifica o AccessKey id para acessar o oss.
-k, --access-key-secret	string	Especifica o AccessKey Secret para acessar o oss.
--addressing-style	string	Especifica o estilo de endereçamento da solicitação. Valores válidos: virtual (padrão): Habilita o estilo de host virtual. path: Habilita o modo de caminho. cname: Habilita o modo de nome de domínio personalizado.
-c, --config-file	string	Especifica o caminho para o arquivo de configuração. O caminho padrão é `~/.ossutilconfig`.
--connect-timeout	int	Tempo limite de conexão em segundos. O valor padrão é 10.
-n, --dry-run	/	Mostra as operações que seriam realizadas sem executá-las.
-e, --endpoint	string	Especifica o endpoint do serviço ao qual se conectar.
-h, --help	/	Exibe informações de ajuda.
--language	string	Especifica o idioma de exibição.
--loglevel	string	Especifica o nível de log. Valores válidos: off (padrão) info debug
--mode	string	Especifica o modo de autenticação. Valores válidos: AK: Autentica com um par de AccessKey. StsToken: Autentica com uma credencial de segurança temporária. EcsRamRole: Autentica com uma função ram de instância ecs. Anonymous: Usa acesso anônimo.
--output-format	string	Especifica o formato de saída. O valor padrão é raw.
--output-query	string	Especifica a condição de consulta JMESPath.
--profile	string	Especifica o perfil a ser usado no arquivo de configuração.
-q, --quiet	/	Suprime toda a saída, exceto erros.
--read-timeout	int	Tempo limite em segundos para solicitações de leitura e gravação. O valor padrão é 20.
--region	string	A região de destino para a solicitação. Por exemplo, você pode defina o valor como cn-hangzhou.
--retry-times	int	Especifica o número de tentativas para uma solicitação com falha. O valor padrão é 10.
--sign-version	string	Especifica a versão do algoritmo de assinatura para solicitações. Valores válidos: v1 v4 (padrão)
--skip-verify-cert	/	Desativa a verificação de certificado SSL no lado do servidor.
-t, --sts-token	string	Especifica o token STS para acessar o oss.
--proxy	string	Especifica o servidor proxy a ser usado. Esta opção está disponível na versão 2.0.1 e posteriores. Valores válidos: Configuração direta: Especifique diretamente os detalhes do servidor proxy. Exemplos: `http://proxy.example.com:8080` `https://proxy.example.com:8443` `env`: Use as configurações de proxy das variáveis de ambiente `HTTP_PROXY` e `HTTPS_PROXY`. Configure essas variáveis de ambiente no seu sistema operacional. Exemplos: `HTTP_PROXY=http://proxy.example.com:8080` `HTTPS_PROXY=https://proxy.example.com:8443` Após configure essas variáveis de ambiente, defina o valor da opção de servidor proxy como `env` para aplicar automaticamente as configurações de proxy dessas variáveis.
--log-file	string	Especifica o arquivo de saída de log. Esta opção está disponível na versão 2.0.1 e posteriores. O valor pode ser: `-`: Grava logs na saída padrão (stdout). `Caminho do arquivo`: Grava logs no caminho de arquivo especificado. Se esta opção não for especificada, os logs serão gravados no arquivo de log padrão.
--cloudbox-id	string	Especifica o id do CloudBox. Esta opção é usada em cenários de CloudBox e está disponível na versão 2.1.0 e posteriores.
--ignore-env-var	/	Ignora todas as variáveis de ambiente com o prefixo `OSS_`. Esta opção está disponível na versão 2.2.0 e posteriores.
--bind-address	string	Especifica o endereço IP local (IPv4 ou IPv6) para vincular conexões de saída. Esta opção está disponível na versão 2.2.0 e posteriores.
--account-id	string	Especifica o id da conta. Isso é usado para verificação de identidade e propriedade de recursos em cenários de bucket vetorial. Esta opção está disponível na versão 2.2.0 e posteriores.
--user-agent	string	Anexa o valor especificado à string User-Agent padrão. Esta opção está disponível na versão 2.2.2 e posteriores.

Opções comuns de linha de comando

Escopo do comando	Opções suportadas
Todos os comandos de alto nível	--encoding-type string: Especifica o tipo de codificação para nomes de objetos ou arquivos de entrada. O valor válido é url. --request-payer string: Especifica quem paga pela solicitação. Para usar o modo de pagamento pelo solicitante, defina este valor como requester.
Comandos que suportam operações em lote	--start-after/--end-with (, ] : Defina o intervalo de chaves para uma consulta. O intervalo exclui o valor inicial e inclui o valor final. Opções de filtro: Permitem defina condições de filtro com base em nomes de objetos ou arquivos, diretórios, tamanhos, timestamps e metadados de objetos. Para regras detalhadas de filtragem, consulte Opções de filtro. --limited-num: Limita o número de resultados retornados pela API de consulta. --recursive/-r: Processa recursivamente todos os arquivos ou objetos em um diretório, incluindo seus subdiretórios. --dirs/-d: Acesse apenas arquivos ou objetos no diretório raiz, excluindo subdiretórios. Nota Para objetos, isso é simulado usando um delimitador. Isso requer a varredura de todos os objetos com o prefixo especificado, o que pode consumir tempo se houver muitos objetos. --force/-f: Força a operação sem solicitar confirmação. --list-objects: Lista objetos usando a operação de API ListObjects.
Comandos que suportam regras de filtragem de destino	--update: Copia apenas quando o arquivo de source tem um horário de modificação mais recente ou idêntico ao do arquivo de destino. --size-only: Compara apenas tamanhos de arquivos e sincroniza somente arquivos com tamanhos diferentes. --checksum: Compara checksums CRC-64. Esta opção compara primeiro os tamanhos dos arquivos. Se os tamanhos forem iguais, ela compara os checksums CRC-64. Se faltar um checksum CRC-64 em qualquer um dos lados, os arquivos são considerados diferentes. Esta opção é válida apenas para cópias de objeto para objeto. --ignore-existing: Ignora arquivos que já existem no destino. Esta opção está disponível na versão 2.0.3 e posteriores.
Comandos que suportam objetos únicos	--version-id string: Especifica o id da versão do objeto.
Comandos que suportam modo de lista	--list-format: Especifica o formato do arquivo de lista. Valores válidos: plain, inventory. --list-manifest-from: Lê a descrição do formato do arquivo de lista a partir de um arquivo. Este parâmetro é obrigatório quando --list-format está definido como inventory.

Perguntas frequentes

Erro do Ossutil: region must be set in sign version 4

Causa: Você não especificou o id da região ao configure o ossutil 2.0.

Solução: Para evitar erros, configure os seguintes itens obrigatórios: AccessKey id, AccessKey Secret e id da região. O id da região é necessário porque a versão da assinatura foi atualize para V4. Para mais informações sobre como obter um id de região, consulte Regiões e endpoints.

Início rápido

Instale o ossutil

Linux

Alibaba Cloud Linux

CentOS

Ubuntu

Windows

macOS

Configure o ossutil

Linux

Windows

macOS

Execute comandos

Configuração

Precedência de configuração

Arquivo de configuração

Formato do arquivo de configuração

Seções e pares chave-valor

Tipos de seção suportados

Profile

Buckets

Configure variáveis de ambiente

Linux

macOS

Zsh

Bash

Windows

Opções de linha de comando

Credenciais de acesso

Par de AccessKey de usuário ram

Arquivo de configuração

Variáveis de ambiente

Opções de linha de comando

Credencial de segurança temporária

Arquivo de configuração

Variáveis de ambiente

Opções de linha de comando

ARN de função ram

Função ram de instância ecs

Modo EcsRamRole

Arquivo de configuração

CLI

Modo EcsRamRole IMDSv2****

Arquivo de configuração

CLI

ARN de função OIDC

Credenciais de processo externo

Credencial de longo prazo

Credencial temporária

Acesso anônimo

Referência de comandos

Estrutura de comandos

Lista de comandos

Tipos de opções de comando

Carregar dados de outras fontes

Controlar a saída do comando

Formato de saída

Filtrar saída

Formato legível por humanos

Códigos de retorno de comandos

Linux

Windows

macOS

Opções de linha de comando

Opções globais de linha de comando

Opções comuns de linha de comando

Perguntas frequentes

Erro do Ossutil: region must be set in sign version 4