Initialize the Node.js SDK to connect to OSS - - Centro de documentación de Alibaba Cloud

El Client es el punto de entrada principal del SDK de OSS para Node.js. Se utiliza para gestionar recursos de OSS, como buckets y objetos. Para enviar solicitudes a OSS, primero debe inicializar una instancia de Client y, de manera opcional, personalizar su configuración predeterminada.

Notas de uso

Debe configurar las credenciales de acceso antes de inicializar una instancia de OSSClient. Este tema proporciona un ejemplo con variables de entorno. Para obtener más información, consulte Configure access credentials (Node.js SDK).
Para consultar la información sobre las regiones de OSS y sus endpoints correspondientes, consulte Regions and endpoints.
Para conocer cómo crear un par de AccessKey para un usuario de Resource Access Management (RAM), consulte Create an AccessKey pair.

Requisitos previos

Importante

Antes de configurar el cliente, debe establecer las variables de entorno mediante el AccessKey de un usuario de RAM.

Create an AccessKey pair for a Resource Access Management (RAM) user that has full OSS access permissions.

Create an AccessKey pair by using ROS

Puede crear rápidamente un par de AccessKey para un usuario de RAM con permisos de acceso total a OSS mediante un script de Resource Orchestration Service (ROS). Para ello, vaya al asistente para la creación de pilas basadas en plantillas, seleccione I confirm that Alibaba Cloud ROS may create RAM resources en la sección Security Confirmation y haga clic en Create.

Una vez creado el par de AccessKey, cópielo desde la pestaña Outputs.

Configure las variables de entorno para el par de AccessKey.

Linux

Ejecute los siguientes comandos en el CLI 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

Aplique los cambios.
```
source ~/.bashrc
```
Compruebe si las variables de entorno surtieron efecto:
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

Ejecute el siguiente comando en la terminal para consultar el tipo de shell predeterminado:
```
echo $SHELL
```
1. Configure las variables de entorno 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. Aplique los cambios.
    
    source ~/.zshrc
  3. Compruebe si las variables de entorno surtieron efecto:
    
    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. Aplique los cambios.
    
    source ~/.bash_profile
  3. Compruebe si las variables de entorno surtieron efecto:
    
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

Ejecute los siguientes comandos en CMD:

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Compruebe si las variables de entorno surten efecto:

echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%

PowerShell

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)

Compruebe si la variable de entorno surte efecto:

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

Después de establecer las variables de entorno, reinicie todas las sesiones de terminal o los IDE abiertos para que los cambios surtan efecto.

Ejemplos de configuración predeterminada

A continuación se muestran ejemplos de código que indican cómo configurar una instancia de OSSClient con Signature V4 y Signature V1.

Signature V4 (recommended)

Importante

Cuando inicialice una instancia de OSSClient con el algoritmo Signature V4, especifique el identificador de región específico de OSS. Este identificador determina la región a la que se envía la solicitud. Por ejemplo, para la región China (Hangzhou), establezca Region en oss-cn-hangzhou. Para consultar otros identificadores de región, consulte Regions and endpoints.
En el código, debe declarar explícitamente el uso del algoritmo Signature V4. Por ejemplo: authorizationV4: true.

El siguiente código muestra un ejemplo de cómo configurar una instancia de OSSClient mediante un nombre de dominio de OSS y Signature V4.

Este ejemplo ilustra cómo inicializar el cliente con variables de entorno para las credenciales y un endpoint público.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the public endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

Signature V1 (not recommended)

Importante

A partir del 1 de marzo de 2025, Alibaba Cloud Object Storage Service (OSS) ya no ofrece la firma V1 a usuarios nuevos (es decir, UID nuevos). Desde el 1 de septiembre de 2025, OSS dejará de actualizar y mantener la firma V1, y ya no la ofrecerá para los buckets de object storage nuevos. Cambie a la firma V4 lo antes posible para evitar interrupciones en el servicio. Para obtener más información, consulte Anuncio.

El siguiente código configura una instancia de OSSClient mediante un nombre de dominio de OSS. Para consultar los nombres de dominio de OSS correspondientes a cada región, consulte Regions and endpoints.

Crear una instancia de Client mediante un nombre de dominio de OSS

El siguiente código muestra cómo inicializar una instancia con un nombre de dominio de OSS.

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

const client = new OSS({
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'yourRegion',
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
});

Crear una instancia de Client mediante un nombre de dominio personalizado

El siguiente código muestra cómo crear una instancia de Client con un nombre de dominio personalizado. Para obtener más información sobre el acceso a OSS mediante un nombre de dominio personalizado, consulte Access OSS using a custom domain name.

Importante

No puede usar el método client.listBuckets() si utiliza un nombre de dominio personalizado.

const OSS = require('ali-oss')

const client = new OSS({  
 // Use a custom domain name as the endpoint.
 endpoint: 'http://img.example.com', 
 // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Set bucket to the name of your bucket.
 bucket: 'yourBucketName',
});

Ejemplos de configuración para casos de uso comunes

Los siguientes ejemplos de código muestran cómo configurar otros nombres de dominio. De forma predeterminada, estos ejemplos utilizan Signature V4 y la información de AccessKey de un usuario de RAM.

Ejemplo de configuración de un nombre de dominio interno

Si su aplicación está desplegada en una instancia de ECS de Alibaba Cloud y necesita acceder con frecuencia a recursos de OSS en la misma región, utilice un nombre de dominio interno. Esto reduce los costos de tráfico y mejora la velocidad de acceso.

El siguiente código muestra un ejemplo de cómo configurar una instancia de OSSClient mediante un nombre de dominio interno de OSS.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to the internal endpoint of the region where the bucket is located. For example, for China (Hangzhou), set endpoint to https://oss-cn-hangzhou-internal.aliyuncs.com.
  endpoint: 'yourEndpoint',
});

Ejemplo de configuración de un nombre de dominio personalizado

El siguiente código muestra un ejemplo de cómo configurar una instancia de OSSClient mediante un nombre de dominio personalizado.

Aviso

Primero debe vincular el nombre de dominio personalizado al nombre de dominio predeterminado del bucket. De lo contrario, se genera un error. Para obtener más información sobre cómo vincular un nombre de dominio personalizado, consulte Access OSS using a custom domain name.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Use the Signature V4 algorithm.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to your custom domain name. For example, https://static.example.com.
  endpoint: 'yourEndpoint',
  // Set cname to true to enable the CNAME option.
  cname: true,
});

Ejemplo de configuración de un endpoint de aceleración

El siguiente código muestra un ejemplo de cómo configurar una instancia de OSSClient mediante un endpoint de aceleración.

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

const client = new OSS({
  // Obtain access credentials from environment variables. Before you run this code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Set region to the region where the bucket is located. For example, for China (Hangzhou), set region to oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Use Signature V4.
  authorizationV4: true,
  // Set bucket to the name of your bucket.
  bucket: 'yourBucketName',
  // Set endpoint to an acceleration endpoint. For example, oss-accelerate.aliyuncs.com.
  endpoint: 'oss-accelerate.aliyuncs.com',
});

Referencias

Para obtener más información sobre las opciones de configuración de OSSClient, consulte los ejemplos en GitHub.

Notas de uso

Requisitos previos

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Ejemplos de configuración predeterminada

Signature V4 (recommended)

Signature V1 (not recommended)

Crear una instancia de Client mediante un nombre de dominio de OSS

Crear una instancia de Client mediante un nombre de dominio personalizado

Ejemplos de configuración para casos de uso comunes

Ejemplo de configuración de un nombre de dominio interno

Ejemplo de configuración de un nombre de dominio personalizado

Ejemplo de configuración de un endpoint de aceleración

Referencias