Object Storage Service:OSS SDK for Node.js

Preparar el entorno

Descargue e instale el entorno de ejecución de Node.js. Para obtener la mejor compatibilidad y rendimiento, se recomienda usar Node.js 8.0 o una versión posterior.

• Ejecute el comando node -v para comprobar la versión de Node.js.

• Ejecute el comando npm -v para comprobar la versión de npm.

Instalar el SDK

Seleccione la versión del SDK según su versión de Node.js.

• Node.js 8.0 o posterior: use la versión más reciente del SDK 6.x.

• Versiones anteriores a Node.js 8.0: use la versión 4.x del SDK.

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

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

Una vez completada la instalación, ejecute el comando npm list ali-oss para comprobar que se instaló correctamente. Si la instalación fue exitosa, se mostrará la versión del SDK.

Configurar las credenciales de acceso

Configure las credenciales de acceso con el par de AccessKey de un usuario de RAM.

1. En la consola de RAM, cree un usuario de RAM con un Permanent AccessKey Pair. Guarde el par de AccessKey y otorgue el permiso AliyunOSSFullAccess al usuario.

2. Utilice el par de AccessKey del usuario de RAM para configurar las variables de entorno.

   Linux

   1. Ejecute los siguientes comandos en la interfaz de línea de comandos para agregar la configuración de las variables de entorno al archivo ~/.bashrc .

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. Ejecute el siguiente comando para aplicar los cambios.

      source ~/.bashrc

   3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Ejecute el siguiente comando en la terminal para consultar el tipo de shell predeterminado.

      echo $SHELL

   2. Realice las siguientes operaciones según el tipo de shell predeterminado.

      Zsh

      1. Ejecute los siguientes comandos para agregar la configuración de las variables de entorno al archivo ~/.zshrc.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. Ejecute el siguiente comando para aplicar los cambios.

         source ~/.zshrc

      3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Ejecute los siguientes comandos para agregar la configuración de las variables de entorno al archivo ~/.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. Ejecute el siguiente comando para aplicar los cambios.

         source ~/.bash_profile

      3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Ejecute los siguientes comandos en CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Ejecute los siguientes comandos en 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. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

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

Inicializar el cliente

A continuación se muestra un ejemplo de código para inicializar un cliente mediante el endpoint público de la región China (Hangzhou). También se comprueba la configuración del SDK al listar los buckets de su cuenta. Para consultar la lista completa de regiones y 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);

Usar un endpoint interno

Puede acceder a OSS a través de una red interna para evitar costos de transferencia de datos, además de lograr mayores velocidades de acceso y mayor seguridad. Para acceder a OSS por una red interna, establezca el endpoint en un endpoint interno durante la inicialización del 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',
});

Usar un nombre de dominio personalizado

Para acceder a OSS mediante un nombre de dominio personalizado, establezca el endpoint en dicho nombre de dominio. Además, habilite la opción CNAME al establecer el parámetro cname: true durante la inicialización del cliente.

Antes de usar un nombre de dominio personalizado, asegúrese de que esté asignado a un bucket. Para obtener más información, 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,
});

Usar un endpoint de aceleración

Para acelerar el acceso, establezca el endpoint en un endpoint de aceleración cuando inicialice el cliente de 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',
});

Versión de firma

A continuación se muestra un ejemplo de código para inicializar un cliente con Signature V1. Para ver un ejemplo de cómo inicializar un cliente con Signature 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);

Cargar un archivo

El siguiente ejemplo muestra cómo cargar un archivo local a un bucket de OSS. También explica cómo definir las propiedades del archivo mediante encabezados de solicitud personalizados, lo que permite un control detallado sobre las clases de almacenamiento, los permisos de acceso y las etiquetas.

// 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);

Descargar un archivo

El siguiente ejemplo muestra cómo descargar un archivo de un bucket de OSS a una ruta local específica.

// 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);

Eliminar un archivo

El siguiente ejemplo muestra cómo eliminar un archivo específico de un bucket de 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);

Listar archivos

El siguiente ejemplo muestra cómo listar los archivos de un bucket de OSS. De forma predeterminada, se devuelven los detalles de un máximo de 100 archivos.

// 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'
}

Usar el par de AccessKey de un usuario de RAM

Este método es adecuado para aplicaciones desplegadas en un entorno seguro y estable. Está diseñado para escenarios que requieren acceso prolongado a OSS y no necesitan rotar las credenciales con frecuencia. Puede inicializar el proveedor de credenciales con el par de AccessKey (AccessKey ID y AccessKey secret) de una cuenta de Alibaba Cloud o de un usuario de RAM. Este enfoque exige mantener manualmente el par de AccessKey, lo cual puede generar riesgos de seguridad y aumentar la complejidad del mantenimiento.

1. Utilice el par de AccessKey del usuario de RAM para configurar las variables de entorno.

   Linux

   1. Ejecute los siguientes comandos en la interfaz de línea de comandos para agregar la configuración de las variables de entorno al archivo ~/.bashrc .

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

   2. Ejecute el siguiente comando para aplicar los cambios.

      source ~/.bashrc

   3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Ejecute el siguiente comando en la terminal para consultar el tipo de shell predeterminado.

      echo $SHELL

   2. Realice las siguientes operaciones según el tipo de shell predeterminado.

      Zsh

      1. Ejecute los siguientes comandos para agregar la configuración de las variables de entorno al archivo ~/.zshrc.

         echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
         echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

      2. Ejecute el siguiente comando para aplicar los cambios.

         source ~/.zshrc

      3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Ejecute los siguientes comandos para agregar la configuración de las variables de entorno al archivo ~/.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. Ejecute el siguiente comando para aplicar los cambios.

         source ~/.bash_profile

      3. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Ejecute los siguientes comandos en CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Ejecute los siguientes comandos en 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. Ejecute los siguientes comandos para comprobar que las variables de entorno están configuradas.

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

2. Después de modificar las variables de entorno del sistema, reinicie o actualice el entorno de compilación y ejecución. Esto incluye el IDE, la interfaz de línea de comandos, otras aplicaciones de escritorio y los servicios de backend, con el fin de asegurar que se carguen las variables de entorno más recientes.

3. Transmita la información de las credenciales mediante variables de entorno.

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

Usar un token de STS

Este método es adecuado para aplicaciones que requieren acceso temporal a OSS. Puede inicializar el proveedor de credenciales con las credenciales de identidad temporales (AccessKey ID, AccessKey secret y token de seguridad) obtenidas de STS. Dicho enfoque exige mantener manualmente el token de STS, lo cual puede generar riesgos de seguridad y aumentar la complejidad del mantenimiento. Si necesita acceder temporalmente a OSS en varias ocasiones, deberá actualizar el token de STS de forma manual.

1. Utilice las credenciales de identidad temporales para establecer las variables de entorno.

   macOS, Linux y Unix

   Importante

   • Utilice las credenciales de identidad temporales (AccessKey ID, AccessKey secret y token de seguridad) obtenidas de STS, no el par de AccessKey de un usuario de RAM.

   • El AccessKey ID obtenido de STS comienza con "STS"; por ejemplo, "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

   • Utilice las credenciales de identidad temporales (AccessKey ID, AccessKey secret y token de seguridad) obtenidas de STS, no el par de AccessKey (AccessKey ID y AccessKey secret) de un usuario de RAM.

   • El AccessKey ID obtenido de STS comienza con "STS"; por ejemplo, "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 la información de las credenciales mediante variables de entorno.

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

Usar el ARN de un rol de RAM

Este método es adecuado para aplicaciones que requieren acceso autorizado a OSS, como el acceso entre cuentas. Puede inicializar el proveedor de credenciales al especificar el nombre de recurso de Alibaba Cloud (ARN) de un rol de RAM. Este enfoque se basa en tokens de STS. La herramienta de credenciales obtiene un token de STS y llama a la operación AssumeRole para solicitar uno nuevo antes de que el actual caduque. También puede asignar un valor al parámetro policy para restringir aún más los permisos del rol de RAM.

1. Agregue la dependencia de credenciales.

   npm install @alicloud/credentials

2. Configure el par de AccessKey y el ARN del rol de RAM como credenciales de acceso.

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

Usar un rol de RAM de ECS

Este método es adecuado para aplicaciones que se ejecutan en instancias de ECS, instancias de ECI o nodos worker de Container Service for Kubernetes. Se recomienda inicializar el proveedor de credenciales mediante un rol de RAM de ECS. Este método se basa en tokens de STS. Un rol de RAM de ECS permite adjuntar un rol a una instancia de ECS, una instancia de ECI o un nodo worker de Container Service for Kubernetes para actualizar automáticamente el token de STS dentro de la instancia. Así se elimina la necesidad de proporcionar un par de AccessKey o un token de STS, lo que reduce los riesgos asociados con el mantenimiento manual. Para conocer cómo obtener un rol de RAM de ECS, consulte Create a RAM role for a trusted Alibaba Cloud account. Para saber cómo adjuntar un rol a una instancia de ECS, consulte Attach an instance RAM role.

1. Agregue la dependencia de credenciales.

   npm install @alicloud/credentials

2. Configure el rol de RAM de ECS como credencial de acceso.

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

Usar un ARN de rol OIDC

Después de configurar un rol de RAM para los nodos worker en Container Service for Kubernetes, las aplicaciones en los pods de esos nodos pueden obtener el token de STS del rol adjunto mediante el servicio de metadatos global. Este proceso es similar a la forma en que las aplicaciones desplegadas en ECS obtienen sus credenciales. Sin embargo, si se despliegan aplicaciones no confiables en el clúster de contenedores, como aplicaciones de clientes con código cerrado, quizá no desee que obtengan el token de STS del rol de RAM de instancia adjunto a los nodos worker. Para garantizar la seguridad de sus recursos en la nube y permitir al mismo tiempo que estas aplicaciones no confiables obtengan de forma segura los tokens de STS necesarios con permisos mínimos por aplicación, utilice la función RAM Roles for Service Accounts (RRSA). Este método se basa en tokens de STS. El clúster de contenedores de Alibaba Cloud crea y monta el archivo de token OIDC de la cuenta de servicio correspondiente para distintos pods de aplicación, e inyecta la información de configuración relevante en las variables de entorno. La herramienta de credenciales obtiene la información de configuración de las variables de entorno y llama a la operación AssumeRoleWithOIDC de STS para intercambiarla por el token de STS del rol vinculado. De esta manera se elimina la necesidad de proporcionar un par de AccessKey o un token de STS, lo que reduce los riesgos asociados con el mantenimiento manual. Para más información, consulte Configure the RAM permissions of a ServiceAccount using RRSA to achieve pod-level permission isolation.

1. Agregue la dependencia de credenciales.

   npm install @alicloud/credentials

2. Configure el rol de RAM OIDC como credencial de acceso.

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

Usar un URI de credenciales

Este método resulta útil cuando las aplicaciones necesitan obtener credenciales de Alibaba Cloud desde un sistema externo para gestionarlas de forma flexible y acceder sin claves. Inicialice el proveedor de credenciales mediante un URI de credenciales. Este método se basa en tokens de STS. La herramienta de credenciales obtiene un token de STS del URI proporcionado para inicializar el cliente de credenciales. Con esto se elimina la necesidad de proporcionar un par de AccessKey o un token de STS, lo que reduce los riesgos asociados con el mantenimiento manual.

1. Para que la herramienta de credenciales analice sintácticamente y use correctamente el token de STS, el URI debe cumplir con el siguiente protocolo de respuesta:

   • Código de estado de la respuesta: 200

   • Estructura del cuerpo de la respuesta:

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

2. Agregue la dependencia de credenciales.

   npm install @alicloud/credentials

3. Configure el URI de credenciales como credencial de acceso.

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