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 de forma eficiente em vários sistemas operacionais. Com ela, você faz upload, download, sincronização e gerenciamento de arquivos com agilidade. É 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 download	Checksum SHA256
Linux	x86_32	ossutil-2.4.0-linux-386.zip	b6350a6c0c277961f138106e454e912189402dc45be364e83785a3292ce0a4e6
	x86_64	ossutil-2.4.0-linux-amd64.zip	85edf66b2fb7238f5c7e25cab820cf29312319fe4935b7c86a6b8485eb434f3c
	arm32	ossutil-2.4.0-linux-arm.zip	b377a9e4f4b79464176e2e122d7f8c9d3a3d1eae9703f71451c8cd5ef2b4b4fb
	arm64	ossutil-2.4.0-linux-arm64.zip	7767240e9667d1f26fbe4e04f90b796b4356889e77d0076cc8a543c8ce081987
macOS	x86_64	ossutil-2.4.0-mac-amd64.zip	86685f129c76dbf94d7f9298152e24bb895289d866cb1a6115aa141c1a1b455b
macOS	arm64	ossutil-2.4.0-mac-arm64.zip	26e51080c6d6c9848fe3aea8a6b0cbd88453e65cd41c5a27573c59335a78a41d
Windows	x86_32	ossutil-2.4.0-windows-386.zip	4efe875059fe501ab66d88af68fa54d111279f8d25d657cb422a96e4da348137
	x86_64	ossutil-2.4.0-windows-amd64.zip	dd68cffb62d88e59ff3d7fde6055ac7b8e2197e2adce7e540bcd6c706a2c4a49
	x86_64	ossutil-2.4.0-windows-amd64-go1.20.zip	f74f2afa637a7f59caae6ba54e7b6c3aa57c8fce007c77cc10f4338321ab632c

Início rápido

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

Instalar 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 utilize o curl para baixá-lo. O exemplo abaixo demonstra o uso do comando curl em um sistema Linux x86_64:
```
curl -o ossutil-2.4.0-linux-amd64.zip https://gosspublic.alicdn.com/ossutil/v2/2.4.0/ossutil-2.4.0-linux-amd64.zip
```
No diretório de download, descompacte o pacote:
```
unzip ossutil-2.4.0-linux-amd64.zip
```
Acesse o diretório ossutil-2.4.0-linux-amd64.
```
cd ossutil-2.4.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 verificar se a instalação do ossutil foi bem-sucedida, execute o comando ossutil.
```
ossutil
```
A instalação terá sido concluída com êxito caso o ossutil exiba 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 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 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 concluída com êxito caso o ossutil exiba suas informações de ajuda.

macOS

Escolha o pacote de instalação correspondente ao seu sistema operacional e arquitetura (macOS x86 64 bits ou macOS ARM 64 bits) ou utilize o curl para baixar o pacote. O exemplo abaixo demonstra o uso do comando curl em um sistema macOS ARM64:
```
curl -o ossutil-2.4.0-mac-arm64.zip  https://gosspublic.alicdn.com/ossutil/v2/2.4.0/ossutil-2.4.0-mac-arm64.zip
```
No diretório de download, descompacte o pacote:
```
unzip ossutil-2.4.0-mac-arm64.zip
```
Acesse o diretório ossutil-2.4.0-mac-arm64.
```
cd ossutil-2.4.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 concluída com êxito caso o ossutil exiba suas informações de ajuda.

Configurar o ossutil

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

Este exemplo mostra como usar o assistente de configuração para definir 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 usar 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 para definir 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

Insira 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
```
Insira o endpoint do data center do OSS. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após definir a região, o ossutil usa o endpoint público correspondente por padrão. Por exemplo, se você definir 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 está localizado seu data center do OSS, 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 AccessKeys da sua conta. Para saber como obter um par de AccessKeys, consulte Criar um par de AccessKeys. Para criar 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 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 definir um endpoint manualmente, um endpoint público será gerado automaticamente com base na região. É necessário especificar explicitamente um endpoint interno. Por exemplo, este tópico usa o endpoint público da 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 usar um nome de domínio personalizado (CNAME) para executar 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 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 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 usar 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 para definir 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

Insira 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
```
Insira o endpoint do data center do OSS. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após definir a região, o ossutil usa o endpoint público correspondente por padrão. Por exemplo, se você definir 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 está localizado seu data center do OSS, 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 AccessKeys da sua conta. Para saber como obter um par de AccessKeys, consulte Criar um par de AccessKeys. Para criar 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 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 definir um endpoint manualmente, um endpoint público será gerado automaticamente com base na região. É necessário especificar explicitamente um endpoint interno. Por exemplo, este tópico usa o endpoint público da 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 usar um nome de domínio personalizado (CNAME) para executar 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 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 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 usar 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 para definir 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

Insira 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
```
Insira o endpoint do data center do OSS. Caso não precise de um endpoint personalizado, pressione Enter para ignorar este parâmetro.
Após definir a região, o ossutil utiliza o endpoint público correspondente por padrão. Por exemplo, se você definir 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. Se quiser 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 Criar um par de AccessKey. Para criar 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), 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 AccessKey na aba Outputs.
accessKeySecret	Sim
Region	Sim	O ID da região onde o bucket está localizado. Este tópico usa 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 definir manualmente um endpoint, um endpoint público será gerado automaticamente com base na região. É necessário especificar explicitamente um endpoint interno. Por exemplo, este tópico utiliza 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 para 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 executar 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 anúncio 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.

Executar 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 download 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 do bucket examplebucket.
```
0.295530(s) elapsed
```
Remova o bucket examplebucket.
```
ossutil rb oss://examplebucket
```
O retorno abaixo sinaliza que o bucket examplebucket foi excluído com sucesso.
```
0.478659(s) elapsed
```

Configuração

O ossutil oferece grande 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 têm prioridade maior que o arquivo de configuração.

Arquivo de configuração

Configure o ossutil utilizando um arquivo de configuração. O caminho padrão é ~/.ossutilconfig, mas você pode especificar um caminho personalizado com 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á obrigató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, que organiza 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 necessite 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 definições dentro da seção seguem o formato chave=valor. Por exemplo:

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

As definições da seção utilizam o 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 múltiplos 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 tratados 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]

Configura parâmetros referenciados por meio de --profile name.

Permite referenciar outras configurações usando source_profile.

[buckets name]

Define endpoints para buckets específicos, incluindo region, endpoint e addressing style.

Suporta notação inline.

Nota

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

Profile

Esta seção configura 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

Define 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 define 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. Por 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 desde a 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 configura 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 estiver 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

Configurar 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 verificar 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 visualizar 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 verificar 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 verificar 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 verificar 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 os parâmetros definidos no arquivo de configuração ou nas 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 de 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 de AccessKey, o que aumenta tanto os riscos de segurança quanto a sobrecarga de manutenção.

Configuration file

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

Environment variables

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

Command-line options

Execute o comando a seguir para consultar objetos no examplebucket:

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

Credencial de segurança temporária

Se sua aplicação requer 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 exige manutenção manual do token de segurança, aumentando os riscos de segurança e a complexidade. Além disso, você deve atualizar o token manualmente para acessos temporários repetidos.

Configuration file

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

Environment variables

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

Command-line options

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 o RAMRoleARN para inicializar o provedor de credenciais. Este método utiliza tokens STS internamente. Ao especificar 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. Além disso, atribua um valor a policy para restringir a função RAM a um conjunto menor de permissões.

Importante

Uma conta Alibaba Cloud tem permissões totais sobre seus recursos. Se o par de AccessKey de uma conta Alibaba Cloud for vazado, isso representa um risco significativo de segurança para o seu sistema. Recomendamos usar o par de AccessKey de um usuário RAM com as permissões mínimas necessárias.
Para criar um par de AccessKey para um usuário RAM, consulte Criar um par de 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 de AccessKey, crie um novo para rotacionar suas credenciais.
Para obter um ARN de função RAM, consulte Criar 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 um 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 atualizar 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 Criar uma função.

Nota

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

Modo EcsRamRole

Configuration file

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.

Configuration file

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 configurar uma função RAM de nó worker no Container Service for Kubernetes, as aplicações nos Pods desse nó podem obter o token STS para a função associada por meio do serviço de metadados, assim como as 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 por meio do serviço de metadados. Para evitar comprometer a segurança dos seus recursos de cloud 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 Configurar 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 especificar 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 executar um comando externo para obter credenciais. O processo externo retorna as credenciais ao ossutil por meio da saída padrão (stdout).

Nota

Para evitar riscos de segurança, o comando que gera credenciais não deve estar acessível a usuários ou processos não autorizados.
O comando que gera credenciais não deve gravar nenhuma informação secreta 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.

Long-term credential

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

Temporary credential

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

Crie o seguinte arquivo de configuração e salve-o em ~/.ossutilconfig. Essas 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 do 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 oferece três categorias de comandos: comandos de alto nível, comandos no nível da API e comandos auxiliares.

Estrutura dos comandos

A sintaxe básica dos comandos do ossutil é a seguinte:

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

argument: Um argumento do tipo string.
flags: Opções disponíveis em formato curto (-o[=value]/ -o [ value]) e longo (--options[=value]/--options[ value]). Caso você especifique uma flag exclusiva mais de uma vez, apenas o último valor será utilizado.

Confira abaixo alguns 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 gerenciar buckets e objetos. Utilize-os para criar e excluir buckets, copiar dados e modificar propriedades de objetos.

Nome do comando

Descrição

Cria um bucket

Exclui um bucket

Obtém o tamanho de armazenamento de um bucket ou de um prefixo específico

stat

Exibe a descrição de um bucket ou objeto

mkdir

Cria um objeto cujo nome termina com o caractere sufixo /

append

Adiciona conteúdo a um objeto anexável

cat

Concatena o conteúdo do objeto na saída padrão

Lista buckets ou objetos

Faz upload, download ou cópia de objetos

Exclui objetos de um bucket

set-props

Define 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 origem para um destino

hash

Calcula o valor de hash de um arquivo ou objeto

Comandos no nível da 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 visualizar todos os comandos.

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

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

Nome do comando

Descrição

help

Obtém informações de ajuda.

config

Cria um arquivo de configuração para armazenar itens de configuração e credenciais de acesso.

update

Atualiza 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	Flag	Descrição
String	`--option string`	Um argumento 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`.
Boolean	`--option`	Ativa ou desativa uma flag. Por exemplo: `--dry-run`.
Integer	`--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 especificar a flag várias vezes. Uma única flag 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 especificar a flag 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. Você também pode canalizar dados da entrada padrão, o que é útil para encadear comandos.

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

Por exemplo, para definir as configurações de compartilhamento de recursos de origem cruzada (CORS) de um bucket, você pode carregar 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 utilizando o parâmetro --output-format. Os formatos suportados são:

Nome do formato

Descrição

raw

A saída contém os 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 em JSON fica assim:

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 da flag --output-query value.

Nota

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

Esse recurso baseia-se na sintaxe JMESPath. Ao utilizá-lo, a saída é convertida para JSON, filtrada com JMESPath e então exibida no formato de saída especificado. Para mais detalhes 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 mais fácil de ler. Dados em bytes são convertidos para um formato com sufixos Ki, Mi, Gi, Ti ou Pi (base 1024), enquanto dados de quantidade são convertidos para um formato com sufixos k, m, g, t ou p (base 1000).

Exemplo: Modo raw

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 executar 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

A operação do comando foi bem-sucedida. A solicitação enviada ao servidor foi executada corretamente e o servidor retornou uma resposta 200.

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.

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).

Um erro não relacionado ao servidor foi encontrado ao chamar o OSS Go SDK.

Algumas solicitações falharam durante uma operação em lote, como cp ou rm.

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 especificar 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 em --profile dev ou --profile=dev. Coloque valores de parâmetros 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): Ativa o estilo de host virtual. path: Ativa o modo de caminho. cname: Ativa 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: Autenticar com um par de AccessKey. StsToken: Autenticar com uma credencial de segurança temporária. EcsRamRole: Autenticar com uma função RAM de instância ECS. Anonymous: Usar 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 definir o valor como cn-hangzhou.
--retry-times	int	Especifica o número de tentativas para repetir 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`. Você deve configurar 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 configurar 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 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: Define quem paga pela requisição. Para usar o modo de pagamento pelo solicitante, defina este valor como requester.
Comandos com suporte a operações em lote	--start-after/--end-with (, ] : Define o intervalo de chaves para uma consulta. O intervalo exclui o valor inicial e inclui o valor final. Opções de filtro: Permitem definir condições de filtragem com base em nomes de objetos ou arquivos, diretórios, tamanhos, carimbos de data/hora e metadados do objeto. Para obter regras detalhadas de filtragem, consulte Opções de filtro. --limited-num: Limita a quantidade 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: Acessa apenas arquivos ou objetos no diretório raiz, excluindo subdiretórios. Nota Para objetos, isso é simulado por meio de um delimitador. Esse processo exige a varredura de todos os objetos com o prefixo especificado, o que pode ser demorado se houver muitos objetos. --force/-f: Força a execução da operação sem solicitar confirmação. --list-objects: Lista objetos utilizando a operação da API ListObjects.
Comandos com suporte a regras de filtragem de destino	--update: Copia somente quando o arquivo de origem tem uma hora de modificação mais recente ou idêntica à do arquivo de destino. --size-only: Compara apenas os tamanhos dos arquivos e sincroniza somente aqueles com tamanhos diferentes. --checksum: Compara somas de verificação CRC-64. Esta opção compara primeiro os tamanhos dos arquivos. Se os tamanhos forem iguais, ela compara as somas de verificação CRC-64. Caso falte uma soma de verificação CRC-64 em qualquer um dos lados, os arquivos são considerados diferentes. Esta opção é válida apenas para cópias entre objetos. --ignore-existing: Ignora arquivos que já existem no destino. Esta opção está disponível na versão 2.0.3 e posteriores.
Comandos com suporte a objetos únicos	--version-id string: Especifica o ID de versão do objeto.
Comandos com suporte ao 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 configurar 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 atualizada para V4. Para mais informações sobre como obter um ID de região, consulte Regiões e endpoints.

Início rápido

Instalar o ossutil

Linux

Alibaba Cloud Linux

CentOS

Ubuntu

Windows

macOS

Configurar o ossutil

Linux

Windows

macOS

Executar 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

Configurar 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

Configuration file

Environment variables

Command-line options

Credencial de segurança temporária

Configuration file

Environment variables

Command-line options

ARN de função RAM

Função RAM de instância ECS

Modo EcsRamRole

Configuration file

CLI

Modo EcsRamRole IMDSv2****

Configuration file

CLI

ARN de função OIDC

Credenciais de processo externo

Long-term credential

Temporary credential

Acesso anônimo

Referência de comandos

Estrutura dos 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