Object Storage Service:Configure ossutil

Atualizar para o ossutil 2,0

Recomendamos que você atualize para o ossutil 2,0. Para instalar e usar a ferramenta rapidamente, consulte Instalar o ossutil.

A seguir estão os principais recursos do ossutil 2,0:

• Nova estrutura de comandos: O ossutil 2,0 suporta comandos multinível, incluindo comandos no nível da API, como ossutil api put-bucket-acl, e comandos de alto nível, como ossutil config.

• Gestão de configuração aprimorada: O processo inicial de configuração foi simplificado. Após a instalação, é possível concluir a configuração básica fornecendo apenas um AccessKey ID, um AccessKey secret e uma região. Além disso, o parâmetro --profile permite especificar vários arquivos de configuração para maior flexibilidade.

• Parâmetros de filtragem abrangentes: Comandos de processamento em lote, como ls, cp e rm, agora suportam múltiplas condições de filtro. A filtragem pode ser feita por caminho, tamanho do arquivo, hora de modificação ou metadados do objeto, o que aumenta a precisão e a eficiência operacional.

• Formatos de saída flexíveis: O novo parâmetro --output-format permite definir a saída como JSON, YAML ou XML, atendendo a diferentes necessidades de processamento de dados. A opção --output-query também foi introduzida para filtrar a saída e recuperar informações específicas.

• Segurança reforçada: Para melhorar a segurança, o ossutil 2,0 permite definir parâmetros sensíveis por meio de variáveis de ambiente. Essa prática evita que suas chaves fiquem expostas na linha de comando e reduz o risco de vazamentos. Adicionalmente, a nova opção --dry-run possibilita verificar o comportamento de um comando antes da execução, garantindo a correção da operação.

Configuração rápida com o comando config

Na maioria dos casos, o comando config configura o ossutil rapidamente. Esse comando gera um arquivo de configuração de forma interativa.

Os passos a seguir usam um ambiente Linux como exemplo.

1. Execute o comando de configuração.

   ossutil config

2. Defina o caminho do arquivo de configuração conforme solicitado.

   É possível definir o caminho do arquivo de configuração conforme necessário. Por padrão, o arquivo é salvo em ~/.ossutilconfig. Pressione Enter para aceitar o padrão.

   Please enter the config file name, the file name can be with a path (default is: /home/user/.ossutilconfig, press enter to use the default path. If you set it to another path, you should specify the path with --config-file option when you use other commands):

3. Defina o idioma da ferramenta conforme solicitado.

   Insira CH para chinês ou EN para inglês. Por padrão, a ferramenta utiliza o idioma do seu sistema operacional. Essa configuração entra em vigor após a conclusão do comando config.

4. Defina os parâmetros endpoint, AccessKey ID, AccessKey secret e stsToken conforme solicitado. Se você utilizar um token temporário do Security Token Service (STS) para acessar o OSS, será necessário configurar o parâmetro stsToken. Caso contrário, deixe-o em branco.

   A tabela a seguir descreve os parâmetros.

   Parâmetro	Obrigatório	Descrição
   endpoint	Sim	O endpoint da região do bucket. Por exemplo, para usar o endpoint público da região Singapura, defina o valor 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. Por exemplo, defina o valor como https://oss-ap-southeast-1-internal.aliyuncs.com. Para obter mais informações sobre regiões e endpoints, 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 têm acesso restrito para essas operações. Consulte o anúncio oficial para ver a lista completa das operações afetadas. Se você acessar seus dados via HTTPS, será 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.
   accessKeyID	Sim	O par de AccessKeys da sua conta. Para saber mais sobre como criar um par de AccessKeys, consulte Criar um par de AccessKeys. Você pode usar um script do Resource Orchestration Service (ROS) para criar rapidamente um par de AccessKeys para um usuário RAM com permissões de gerenciamento do OSS. Na página Create Stack do console ROS, marque a caixa de confirmação em Security Confirmation e clique em Create. Após a criação da Stack, acesse a aba Outputs e copie o par de AccessKeys.
   accessKeySecret	Sim
   stsToken	Não	Este parâmetro é necessário apenas se você usar um token temporário do STS para acessar o OSS. Caso contrário, deixe-o em branco. Para obter mais informações sobre como gerar um stsToken, consulte AssumeRole.

5. Se você especificou um caminho personalizado para o arquivo de configuração na etapa 2, adicione a opção -c para especificar o arquivo de configuração sempre que executar um comando.

   Por exemplo, se o arquivo de configuração estiver salvo em /home/config, use o seguinte formato ao executar o comando ls:

   ossutil -c /home/config ls oss://examplebucket

Arquivo de configuração

Para maior conveniência, salve credenciais e informações de configuração usadas frequentemente em um arquivo de configuração. Esse arquivo utiliza o formato INI e consiste em seções e pares chave-valor. Os parâmetros de configuração ficam salvos em seções específicas. A tabela abaixo descreve os parâmetros de configuração comuns.

[Credentials]
language = CH

[Credentials]
accessKeyID = your_accesskey_id

[Credentials]
accessKeySecret = your_accesskey_secret

[Credentials]
stsToken = your_sts_token

[Credentials]
mode = RamRoleArn

[Credentials]
ramRoleArn = your_ram_role_arn

[Credentials]
roleSessionName = your_ram_role_session_name

[Credentials]
tokenTimeout = your_token_timeout

[Credentials]
ecsRoleName = your_ecs_role_name

Para obter mais informações sobre os parâmetros de configuração, consulte Editar o arquivo de configuração.

Opções de linha de comando

Também é possível especificar configurações usando opções de linha de comando, as quais têm precedência sobre as definições do arquivo de configuração.

ossutil64 commandname options --loglevel debug

ossutil64 commandname options --connect-timeout 60

ossutil64 commandname options --read-timeout 60

ossutil64 commandname options --retry-times 20

ossutil64 commandname options -i your_access_key_id

ossutil64 commandname options -k your_access_key_secret

ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token

ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK

ossutil64 commandname options --ram-role-arn your_ram_role_arn

ossutil64 commandname options --role-session-name your_ram_session_name

ossutil64 commandname options --token-timeout 1800

ossutil64 commandname options --ecs-role-name your_ecs_role_name

Para obter mais informações sobre as opções de configuração, consulte Opções comuns.

Configurar credenciais de acesso

Existem várias maneiras de configurar credenciais de acesso, como por meio de um arquivo de configuração ou opções de linha de comando.

Configurar um endpoint separado para um bucket

Ao usar o ossutil para gerenciar vários buckets em diferentes regiões, configure um endpoint separado para cada bucket. Existem duas formas de fazer isso:

• Usando um arquivo de configuração

  No arquivo de configuração, adicione uma seção [Bucket-Endpoint] para configurar um endpoint separado para cada bucket especificado. O formato é o seguinte:

  [Bucket-Endpoint]
  bucket1 = endpoint1
  bucket2 = endpoint2
  ...

  O exemplo a seguir mostra como configurar endpoints para um bucket na região Singapura (example-bucket-sg) e um bucket na região Japão (Tóquio) (example-bucket-jp).

  Crie o seguinte arquivo de configuração e salve-o em ~/.myossutilconfig.

  [Credentials]
  endpoint = oss-ap-southeast-1.aliyuncs.com
  accessKeyID = yourAccessKeyID
  accessKeySecret = yourAccessKeySecret
  [Bucket-Endpoint]
  example-bucket-sg=oss-ap-southeast-1.aliyuncs.com
  example-bucket-jp=oss-ap-northeast-1.aliyuncs.com

  Execute os comandos a seguir para listar os objetos nos buckets:

  ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
  ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp

• Usando opções de linha de comando

  O exemplo a seguir mostra como configurar endpoints para um bucket na região Singapura (example-bucket-sg) e um bucket na região Japão (Tóquio) (example-bucket-jp).

  Configure as informações da conta em ~/.myossutilconfig.

  [Credentials]
  endpoint = oss-ap-southeast-1.aliyuncs.com
  accessKeyID = yourAccessKeyID
  accessKeySecret = yourAccessKeySecret

  Especifique o endpoint usando o parâmetro -e.

  ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
  ossutil64 -c ~/.myossutilconfig -e oss-ap-northeast-1.aliyuncs.com ls oss://example-bucket-jp

Configurar um nome de domínio personalizado

O ossutil permite acessar recursos do OSS usando um nome de domínio personalizado. Antes de usar esse recurso, mapeie o bucket para o nome de domínio personalizado no arquivo de configuração.

No arquivo de configuração, adicione uma seção [Bucket-Cname] para mapear um bucket a um nome de domínio personalizado. O formato é o seguinte:

[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

O exemplo a seguir mostra como acessar um bucket chamado example-bucket na região Singapura usando o nome de domínio personalizado cname.example-***.com.

Crie o seguinte arquivo de configuração e salve-o em ~/.myossutilconfig.

[Credentials]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Cname]
example-bucket=cname.example-***.com

Execute o comando a seguir para listar os objetos no bucket:

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket