Object Storage Service:OSS SDK for Node.js

Prepare o ambiente

Baixe e instale o ambiente de execução do Node.js. Para garantir melhor compatibilidade e desempenho, recomendamos o uso do Node.js 8,0 ou superior.

• Execute o comando node -v para verificar a versão do Node.js.

• Execute o comando npm -v para verificar a versão do npm.

Instale o SDK

Selecione a versão do SDK de acordo com a sua versão do Node.js.

• Node.js 8,0 ou superior: utilize a versão mais recente do SDK 6.x.

• Versões anteriores ao Node.js 8,0: utilize a versão 4.x do SDK.

npm install ali-oss@^6.x --save

npm install ali-oss@^4.x --save

Após concluir a instalação, execute o comando npm list ali-oss para verificá-la. Se a instalação for bem-sucedida, a versão do SDK será exibida.

Configure as credenciais de acesso

Configure as credenciais de acesso utilizando um par de AccessKey de um usuário RAM.

1. No RAM console, crie um usuário RAM com um Permanent AccessKey Pair. Salve o par de AccessKey e conceda a permissão AliyunOSSFullAccess ao usuário.

2. Utilize o par de AccessKey do usuário RAM para configurar as variáveis de ambiente.

   Linux

   1. Execute os comandos abaixo na interface de linha de comando para adicionar as definições das 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

   2. Execute o comando a seguir para aplicar as alterações.

      source ~/.bashrc

   3. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Execute o comando abaixo no terminal para visualizar o tipo de shell padrão.

      echo $SHELL

   2. Realize as operações a seguir conforme o tipo de shell padrão.

      Zsh

      1. Execute os comandos abaixo para adicionar as definições das 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 abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Execute os comandos abaixo para adicionar as definições das 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 abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Execute os comandos abaixo no CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Execute os comandos abaixo no PowerShell.

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

Inicialize o cliente

O código de exemplo a seguir demonstra como inicializar um cliente usando o endpoint público da região China (Hangzhou) e validar a configuração do SDK listando os buckets da sua conta. Para obter a lista completa de regiões e endpoints, consulte Regions and endpoints.

// Sample code for initializing an OSS client using the OSS SDK for Node.js

const OSS = require('ali-oss');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
        region: 'oss-cn-hangzhou',
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Enable Signature V4.
        authorizationV4: true,
    });

    try {
        // List all buckets.
        const result = await client.listBuckets();
        
        // Print the list of buckets.
        console.log(`Found ${result.buckets.length} buckets:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Failed to list buckets. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Use um endpoint interno

O acesso ao OSS pela rede interna evita custos de transferência de dados, além de proporcionar maior velocidade e segurança. Para acessar o OSS internamente, defina o endpoint como um endpoint interno durante a inicialização do cliente.

const client = new OSS({
    // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
    region: 'oss-cn-hangzhou',
    // Obtain access credentials from environment variables.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Enable Signature V4.
    authorizationV4: true,
    // Use an internal endpoint. This example uses the internal endpoint of the China (Hangzhou) region.
    endpoint: 'https://oss-cn-hangzhou-internal.aliyuncs.com',
});

Use um nome de domínio personalizado

Para acessar o OSS com um nome de domínio personalizado, defina o endpoint como esse domínio e ative a opção CNAME configurando o parâmetro cname: true na inicialização do cliente.

Antes de utilizar um nome de domínio personalizado, certifique-se de que ele esteja mapeado para um bucket. Para mais informações, consulte Access OSS using a custom domain name .

// Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
const client = new OSS({
    // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
    region: 'oss-cn-hangzhou',
    // Obtain access credentials from environment variables.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Enable Signature V4.
    authorizationV4: true,
    // Use a custom domain name.
    endpoint: 'http://example.com',
    // Specify the bucket name. The bucket name must be mapped to the custom domain name.
    bucket: 'example-bucket',
    // Enable the CNAME option.
    cname: true,
});

Use um endpoint de aceleração

Para acelerar o acesso, defina o endpoint como um endpoint de aceleração ao inicializar o cliente OSS.

// Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
const client = new OSS({
    // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
    region: 'oss-cn-hangzhou',
    // Obtain access credentials from environment variables.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Enable Signature V4.
    authorizationV4: true,
    // Use an acceleration endpoint.
    endpoint: 'https://oss-accelerate.aliyuncs.com',
    // Specify the bucket name. Transfer acceleration must be enabled for the bucket.
    bucket: 'example-bucket',
});

Versão da assinatura

O código de exemplo a seguir mostra como inicializar um cliente usando a Assinatura V1. Para ver um exemplo de inicialização com a Assinatura V4, consulte Initialize the client.

// Sample code for initializing an OSS client using the OSS SDK for Node.js

const OSS = require('ali-oss');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    });

    try {
        // List all buckets.
        const result = await client.listBuckets();
        
        // Print the list of buckets.
        console.log(`Found ${result.buckets.length} buckets:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Failed to list buckets. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Faça upload de um arquivo

Este exemplo mostra como enviar um arquivo local para um bucket do OSS. Ele também ilustra como definir propriedades do arquivo usando cabeçalhos de solicitação personalizados, permitindo controle granular sobre classes de armazenamento, permissões de acesso e tags.

// Sample code for uploading a file using the OSS SDK for Node.js

const OSS = require('ali-oss');
const path = require('path');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
        region: 'oss-cn-hangzhou',
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Enable Signature V4.
        authorizationV4: true,
        // Specify the bucket name.
        bucket: 'example-bucket',
    });

    // Custom request headers.
    const headers = {
        // Specify the storage class of the object.
        'x-oss-storage-class': 'Standard',
        // Specify the access control list (ACL) of the object.
        'x-oss-object-acl': 'private',
        // Specify that the file is downloaded as an attachment when accessed through a URL.
        'Content-Disposition': 'attachment',
        // Set tags for the object. You can set multiple tags.
        'x-oss-tagging': 'Tag1=1&Tag2=2',
        // Specify whether to overwrite an object that has the same name. In this example, this parameter is set to true, which indicates that an object with the same name is not overwritten.
        'x-oss-forbid-overwrite': 'true',
    };

    try {
        // Configure file information.
        const key = 'dest.jpg';                    // The path of the file in OSS.
        const localFilePath = path.normalize('dest.jpg'); // The full path of the local file.
        
        // Upload the local file to the specified path in OSS.
        const result = await client.put(key, localFilePath, { headers });
        
        console.log(`File uploaded: ${localFilePath} -> ${key}`);
        console.log('Upload result:', result);
        
    } catch (err) {
        console.log('Upload failed. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Baixe um arquivo

O exemplo a seguir demonstra como baixar um arquivo de um bucket do OSS para um caminho local específico.

// Sample code for downloading a file using the OSS SDK for Node.js

const OSS = require('ali-oss');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
        region: 'oss-cn-hangzhou',
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Enable Signature V4.
        authorizationV4: true,
        // Specify the bucket name.
        bucket: 'example-bucket',
    });

    try {
        // Configure file information.
        const key = 'dest.jpg';       // The path of the file in OSS.
        const filePath = 'dest.jpg';  // The local path to save the file.
        
        // Download the file from OSS to the specified local path.
        const result = await client.get(key, filePath);
        
        console.log(`File downloaded: ${key} -> ${filePath}`);
        
    } catch (err) {
        console.log('Download failed. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Exclua um arquivo

Este exemplo ilustra como excluir um arquivo específico de um bucket do OSS.

// Sample code for deleting a file using the OSS SDK for Node.js

const OSS = require('ali-oss');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
        region: 'oss-cn-hangzhou',
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Enable Signature V4.
        authorizationV4: true,
        // Specify the bucket name.
        bucket: 'example-bucket',
    });

    try {
        // Configure file information.
        const key = 'dest.jpg';  // The path of the file to delete in OSS.
        
        // Delete the specified file from OSS.
        const result = await client.delete(key);
        
        console.log(`File deleted: ${key}`);
        console.log('Delete result:', result);
        
    } catch (err) {
        console.log('Delete failed. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Liste arquivos

O exemplo abaixo mostra como listar os arquivos em um bucket do OSS. Por padrão, são retornados detalhes de até 100 arquivos.

// Sample code for listing files using the OSS SDK for Node.js

const OSS = require('ali-oss');

async function main() {
    
    // Obtain access credentials from environment variables. You must set the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables.
    const client = new OSS({
        // Set the region to oss-cn-hangzhou, which is the China (Hangzhou) region.
        region: 'oss-cn-hangzhou',
        // Obtain access credentials from environment variables.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Enable Signature V4.
        authorizationV4: true,
        // Specify the bucket name.
        bucket: 'example-bucket',
    });

    try {
        // By default, a maximum of 100 files are returned if no parameters are specified.
        const result = await client.list();
        
        console.log(`Found ${result.objects ? result.objects.length : 0} files:`);
        
        // Print the list of files.
        if (result.objects && result.objects.length > 0) {
            for (const object of result.objects) {
                console.log(`File name: ${object.name}, Size: ${object.size} bytes, Last modified: ${object.lastModified}`);
            }
        } else {
            console.log('No files found in the bucket.');
        }
        
    } catch (err) {
        console.log('Failed to list files. Details:');
        console.error(err);
        return;
    }
}

// Execute the main function.
main().catch(console.error);

Error [NoSuchKeyError]: Object not exists {
  status: 404,
  code: 'NoSuchKey',
  requestId: '6904202CA7BABC37395E28AB'
}

Utilize o par de AccessKey de um usuário RAM

Este método é indicado para aplicações em ambientes seguros e estáveis que demandam acesso prolongado ao OSS e não exigem rotação frequente de credenciais. A inicialização do provedor de credenciais é feita com o par de AccessKey (AccessKey ID e AccessKey secret) de uma conta Alibaba Cloud ou de um usuário RAM. Como essa abordagem requer manutenção manual do par de AccessKey, ela pode aumentar a complexidade operacional e apresentar riscos de segurança.

1. Utilize o par de AccessKey do usuário RAM para configurar as variáveis de ambiente.

   Linux

   1. Execute os comandos abaixo na interface de linha de comando para adicionar as definições das 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

   2. Execute o comando a seguir para aplicar as alterações.

      source ~/.bashrc

   3. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Execute o comando abaixo no terminal para visualizar o tipo de shell padrão.

      echo $SHELL

   2. Realize as operações a seguir conforme o tipo de shell padrão.

      Zsh

      1. Execute os comandos abaixo para adicionar as definições das 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 abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Execute os comandos abaixo para adicionar as definições das 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 abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Execute os comandos abaixo no CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Execute os comandos abaixo no PowerShell.

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

   2. Execute os comandos abaixo para verificar se as variáveis de ambiente foram configuradas corretamente.

      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

2. Após modificar as variáveis de ambiente do sistema, reinicie ou atualize o ambiente de compilação e execução — como IDE, interface de linha de comando, outros aplicativos desktop e services de backend — para garantir que as novas variáveis sejam carregadas corretamente.

3. Transmita as informações de credenciais por meio das variáveis de ambiente.

   const OSS = require("ali-oss");
   
   // Initialize OSS.
   const client = new OSS({
     // Obtain the value of AccessKey ID from an environment variable.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Obtain the value of AccessKey secret from an environment variable.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Utilize um token STS

Esta abordagem é ideal para aplicações que precisam de acesso temporário ao OSS. Inicialize o provedor de credenciais usando as credenciais de identidade temporárias (AccessKey ID, AccessKey secret e token de segurança) obtidas via STS. Esse método exige manutenção manual do token STS, o que pode elevar a complexidade de gerenciamento e introduzir riscos de segurança. Para acessar o OSS temporariamente várias vezes, renove o token STS manualmente.

1. Defina as variáveis de ambiente usando as credenciais de identidade temporárias.

   macOS, Linux e Unix

   Importante

   • Utilize as credenciais temporárias (AccessKey ID, AccessKey secret e token de segurança) obtidas pelo STS, e não o par de AccessKey de um usuário RAM.

   • O AccessKey ID fornecido pelo STS começa com "STS", por exemplo, "STS.".

   export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

   Windows

   Importante

   • Utilize as credenciais temporárias (AccessKey ID, AccessKey secret e token de segurança) obtidas pelo STS, e não o par de AccessKey (AccessKey ID e AccessKey secret) de um usuário RAM.

   • O AccessKey ID fornecido pelo STS começa com "STS", por exemplo, "STS.".

   set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

2. Transmita as informações de credenciais por meio das variáveis de ambiente.

   const OSS = require("ali-oss");
   
   // Initialize OSS.
   const client = new OSS({
     // Obtain the value of AccessKey ID from an environment variable.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Obtain the value of AccessKey secret from an environment variable.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // Obtain the value of the STS token from an environment variable.
     stsToken: process.env.OSS_SESSION_TOKEN
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Utilize um ARN de função RAM

Este método é recomendado para aplicações que exigem acesso autorizado ao OSS, como em cenários de acesso entre contas. Inicialize o provedor de credenciais especificando o Alibaba Cloud Resource Name (ARN) de uma função RAM. Baseado em tokens STS, esse processo faz com que a ferramenta de credenciais obtenha um token do STS e chame a operação AssumeRole para solicitar um novo token antes que o atual expire. Além disso, é possível atribuir um valor ao parâmetro policy para restringir ainda mais as permissões da função RAM.

1. Adicione a dependência de credenciais.

   npm install @alicloud/credentials

2. Configure o par de AccessKey e o ARN da função RAM como credenciais de acesso.

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // Initialize the Credentials client using a RAM role ARN.
   const credentialsConfig = new Credential.Config({
     // The credential type.
     type: "ram_role_arn",
     // Obtain the value of AccessKey ID from an environment variable.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Obtain the value of AccessKey secret from an environment variable.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // The ARN of the RAM role to assume. Example: acs:ram::123456789012****:role/adminrole. You can set roleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
     roleArn: '<RoleArn>',
     // The name of the role session. You can set RoleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
     roleSessionName: '<RoleSessionName>',
     // A more restrictive access policy. This parameter is optional. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: '<Policy>',
     roleSessionExpiration: 3600
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // Initialize OSS.
   const client = new OSS({
     accessKeyId:credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // The credential provider controls the update of accessKeyId, accessKeySecret, and stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log( buckets);

Utilize uma função RAM do ECS

Esta opção é adequada para aplicações executadas em instâncias ECS, instâncias ECI ou nós de trabalho do Container Service for Kubernetes. Recomendamos inicializar o provedor de credenciais usando uma função RAM do ECS. Baseado em tokens STS, esse recurso permite anexar uma função a uma instância ECS, ECI ou nó de trabalho do Container Service for Kubernetes, renovando automaticamente o token STS dentro da própria instância. Assim, elimina-se a necessidade de fornecer manualmente um par de AccessKey ou token STS, reduzindo os riscos associados à manutenção manual. Para saber como obter uma função RAM do ECS, consulte Create a RAM role for a trusted Alibaba Cloud account. Para aprender a anexar uma função a uma instância ECS, veja Attach an instance RAM role.

1. Adicione a dependência de credenciais.

   npm install @alicloud/credentials

2. Configure a função RAM do ECS como credencial de acesso.

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // Initialize the Credentials client using a RAM role ARN.
   const credentialsConfig = new Credential.Config({
     // The credential type.
     type: "ecs_ram_role",
     // Optional. The name of the ECS role. If you do not specify this parameter, the role name is automatically obtained. We recommend that you specify this parameter to reduce the number of requests. You can set roleName using the ALIBABA_CLOUD_ECS_METADATA environment variable.
     roleName: '<RoleName>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   
   const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
   // Initialize the OSS client.
   const client = new OSS({
     accessKeyId,
     accessKeySecret,
     stsToken: securityToken,
     refreshSTSTokenInterval: 0, // The credential provider controls the update of accessKeyId, accessKeySecret, and stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Utilize um ARN de função OIDC

Após configurar uma função RAM para os nós de trabalho no Container Service for Kubernetes, as aplicações nos pods desses nós podem obter o token STS da função anexada por meio do service global de metadados. Esse processo é semelhante ao modo como aplicações em ECS obtêm credenciais. No entanto, se houver aplicações não confiáveis no cluster de contêineres — como softwares de clientes com código fechado —, talvez você não queira que elas acessem o token STS da função RAM da instância vinculada aos nós de trabalho. Para proteger seus recursos na nuvem e permitir que essas aplicações obtenham tokens STS de forma segura, alcançando a minimização de permissões no nível da aplicação, utilize o recurso RAM Roles for Service Accounts (RRSA). Baseado em tokens STS, esse mecanismo faz com que o cluster de contêineres da Alibaba Cloud crie e monte o arquivo de token OIDC da conta de service correspondente para cada pod, injetando as configurações relevantes nas variáveis de ambiente. A ferramenta de credenciais lê essas informações e chama a operação AssumeRoleWithOIDC do STS para trocar pelo token STS da função vinculada. Dessa forma, não é preciso fornecer pares de AccessKey ou tokens STS manualmente, o que reduz os riscos de manutenção. Para mais detalhes, consulte Configure the RAM permissions of a ServiceAccount using RRSA to achieve pod-level permission isolation.

1. Adicione a dependência de credenciais.

   npm install @alicloud/credentials

2. Configure a função RAM OIDC como credencial de acesso.

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   const credentialsConfig = new Credential.Config({
     // The credential type.
     type: "oidc_role_arn",
     // The ARN of the RAM role. You can set roleArn using the ALIBABA_CLOUD_ROLE_ARN environment variable.
     roleArn: '<RoleArn>',
     // The ARN of the OIDC provider. You can set oidcProviderArn using the ALIBABA_CLOUD_OIDC_PROVIDER_ARN environment variable.
     oidcProviderArn: '<OidcProviderArn>',
     // The path of the OIDC token file. You can set oidcTokenFilePath using the ALIBABA_CLOUD_OIDC_TOKEN_FILE environment variable.
     oidcTokenFilePath: '<OidcTokenFilePath>',
     // The name of the role session. You can set roleSessionName using the ALIBABA_CLOUD_ROLE_SESSION_NAME environment variable.
     roleSessionName: '<RoleSessionName>',
     // A more restrictive access policy. This parameter is optional. Example: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: "<Policy>",
     // Set the session expiration time.
     roleSessionExpiration: 3600
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   const client = new OSS({
     accessKeyId,
     accessKeySecret,
     stsToken: securityToken,
     refreshSTSTokenInterval: 0, // The credential provider controls the update of accessKeyId, accessKeySecret, and stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   const buckets = await client.listBuckets();
   
   console.log(buckets);

Utilize uma URI de credenciais

Este método é apropriado para aplicações que precisam obter credenciais da Alibaba Cloud de um sistema externo, possibilitando gestão flexível de credenciais e acesso sem chaves. Inicialize o provedor de credenciais usando uma URI de credenciais. Baseado em tokens STS, esse processo faz com que a ferramenta de credenciais obtenha um token STS a partir da URI fornecida para inicializar o cliente de credenciais. Assim, elimina-se a necessidade de fornecer manualmente um par de AccessKey ou token STS, reduzindo os riscos associados à manutenção manual.

1. Para que a ferramenta de credenciais interprete e utilize corretamente o token STS, a URI deve seguir o protocolo de resposta abaixo:

   • Código de status da resposta: 200

   • Estrutura do corpo da resposta:

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. Adicione a dependência de credenciais.

   npm install @alicloud/credentials

3. Configure a URI de credenciais como credencial de acesso.

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   // Initialize the Credentials client using a credentials URI.
   const credentialsConfig = new Credential.Config({
     // The credential type.
     type: "credentials_uri",
     // The URI from which to obtain the credentials. The format is http://local_or_remote_uri/. You can set credentialsUri using the ALIBABA_CLOUD_CREDENTIALS_URI environment variable.
     credentialsURI: '<CredentialsUri>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // Initialize OSS.
   const client = new OSS({
     accessKeyId: credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // The credential provider controls the update of accessKeyId, accessKeySecret, and stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);