Initialiser le SDK Node.js pour se connecter à OSS - - Centre de documentation Alibaba Cloud

L'objet Client est le point d'entrée principal du SDK OSS pour Node.js. Il permet de gérer les ressources OSS, telles que les buckets et les objets. Pour envoyer des requêtes à OSS, vous devez d'abord initialiser une instance Client et personnaliser sa configuration par défaut si nécessaire.

Remarques sur l'utilisation

Vous devez configurer les identifiants d'accès avant d'initialiser une instance OSSClient. Cette rubrique fournit un exemple utilisant des variables d'environnement. Pour plus d'informations, consultez la page Configurer les identifiants d'accès (SDK Node.js).
Pour obtenir la liste des régions OSS et leurs endpoints correspondants, consultez la page Régions et endpoints.
Pour savoir comment créer une paire AccessKey pour un utilisateur RAM (Resource Access Management), consultez la page Créer une paire AccessKey.

Prérequis

Important

Avant de configurer le client, vous devez définir les variables d'environnement à l'aide de la clé AccessKey d'un utilisateur RAM.

Créez une paire AccessKey pour un utilisateur Resource Access Management (RAM) disposant des autorisations d'accès complètes à OSS.

Créer une paire AccessKey à l'aide de ROS

Vous pouvez rapidement créer une paire AccessKey pour un utilisateur RAM disposant des autorisations d'accès complètes à OSS en utilisant un script Resource Orchestration Service (ROS). Pour ce faire, accédez à l'assistant de création de pile basée sur un modèle, sélectionnez I confirm that Alibaba Cloud ROS may create RAM resources dans la section Security Confirmation, puis cliquez sur Create.

Une fois la paire AccessKey créée, copiez-la depuis l'onglet Outputs.

Configurez les variables d'environnement pour la paire AccessKey.

Linux

Exécutez les commandes suivantes dans l'interface CLI pour ajouter les configurations des variables d'environnement au fichier ~/.bashrc :
```
echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc
```
1. Appliquez les modifications.
```
source ~/.bashrc
```
2. Vérifiez si les variables d'environnement sont prises en compte :
```
echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET
```

macOS

Exécutez la commande suivante dans le terminal pour afficher le type de shell par défaut :
```
echo $SHELL
```
1. Configurez les variables d'environnement en fonction du type de shell par défaut.
  Zsh
  1. Exécutez les commandes suivantes pour ajouter les configurations des variables d'environnement au fichier ~/.zshrc :
    
    echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc
  2. Appliquez les modifications.
    
    source ~/.zshrc
  3. Vérifiez si les variables d'environnement sont prises en compte :
    
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET
  Bash
  1. Exécutez les commandes suivantes pour ajouter les configurations des variables d'environnement au fichier ~/.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. Appliquez les modifications.
    
    source ~/.bash_profile
  3. Vérifiez si les variables d'environnement sont prises en compte :
    
    echo $OSS_ACCESS_KEY_ID echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

Exécutez les commandes suivantes dans CMD :

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

Vérifiez si les variables d'environnement sont prises en compte :
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

Exécutez les commandes suivantes dans 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)

Vérifiez si la variable d'environnement est prise en compte :

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

Après avoir défini les variables d'environnement, redémarrez toutes les sessions de terminal ou les IDE ouverts pour que les modifications soient prises en compte.

Exemples de configuration par défaut

Les exemples de code suivants montrent comment configurer une instance OSSClient à l'aide des algorithmes Signature V4 et Signature V1.

Signature V4 (recommandé)

Important

Lorsque vous initialisez une instance OSSClient avec l'algorithme Signature V4, spécifiez l'ID de région spécifique à OSS. Cet ID identifie la région vers laquelle la requête est envoyée. Par exemple, pour la région Chine (Hangzhou), définissez la région sur oss-cn-hangzhou. Pour connaître les autres ID de région, consultez la page Régions et endpoints.
Dans votre code, vous devez déclarer explicitement l'utilisation de l'algorithme Signature V4. Par exemple : authorizationV4: true.

Le code suivant illustre la configuration d'une instance OSSClient à l'aide d'un nom de domaine OSS et de la signature V4.

L'exemple ci-dessous montre comment initialiser le client en utilisant des variables d'environnement pour les identifiants et un endpoint public.

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 (non recommandé)

Important

Le code suivant configure une instance OSSClient à l'aide d'un nom de domaine OSS. Pour obtenir la liste des noms de domaine OSS selon les régions, consultez la page Régions et endpoints.

Créer une instance Client à l'aide d'un nom de domaine OSS

Le code suivant montre comment initialiser une instance à l'aide d'un nom de domaine 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',
});

Créer une instance Client à l'aide d'un nom de domaine personnalisé

Le code suivant montre comment créer une instance Client à l'aide d'un nom de domaine personnalisé. Pour plus d'informations sur l'accès à OSS via un nom de domaine personnalisé, consultez la page Accéder à OSS à l'aide d'un nom de domaine personnalisé.

Important

Vous ne pouvez pas utiliser la méthode client.listBuckets() si vous utilisez un nom de domaine personnalisé.

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',
});

Exemples de configuration pour les cas d'utilisation courants

Les exemples de code suivants montrent comment configurer d'autres noms de domaine. Par défaut, ces exemples utilisent la signature V4 et les informations AccessKey d'un utilisateur RAM.

Exemple de configuration de nom de domaine interne

Si votre application est déployée sur une instance ECS Alibaba Cloud et doit accéder fréquemment aux ressources OSS situées dans la même région, utilisez un nom de domaine interne pour réduire les coûts de trafic et améliorer la vitesse d'accès.

Le code suivant illustre la configuration d'une instance OSSClient à l'aide d'un nom de domaine interne 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',
});

Exemple de configuration de nom de domaine personnalisé

Le code suivant illustre la configuration d'une instance OSSClient à l'aide d'un nom de domaine personnalisé.

Avertissement

Vous devez d'abord lier le nom de domaine personnalisé au nom de domaine par défaut du bucket. Sinon, une erreur se produit. Pour plus d'informations sur la liaison d'un nom de domaine personnalisé, consultez la page Accéder à OSS à l'aide d'un nom de domaine personnalisé.

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

Exemple de configuration d'endpoint d'accélération

Le code suivant illustre la configuration d'une instance OSSClient à l'aide d'un endpoint d'accélération.

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',
});

Références

Pour plus d'informations sur les options de configuration d'OSSClient, consultez les exemples sur GitHub.

Remarques sur l'utilisation

Prérequis

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

Exemples de configuration par défaut

Signature V4 (recommandé)

Signature V1 (non recommandé)

Créer une instance Client à l'aide d'un nom de domaine OSS

Créer une instance Client à l'aide d'un nom de domaine personnalisé

Exemples de configuration pour les cas d'utilisation courants

Exemple de configuration de nom de domaine interne

Exemple de configuration de nom de domaine personnalisé

Exemple de configuration d'endpoint d'accélération

Références