Object Storage Service:OSS SDK for Node.js

Persiapkan lingkungan

Unduh dan instal lingkungan runtime Node.js. Untuk kompatibilitas dan kinerja optimal, kami merekomendasikan menggunakan Node.js versi 8.0 atau lebih baru.

• Jalankan perintah node -v untuk memeriksa versi Node.js.

• Jalankan perintah npm -v untuk memeriksa versi npm.

Instal SDK

Pilih versi SDK berdasarkan versi Node.js Anda.

• Node.js versi 8.0 atau lebih baru: Gunakan SDK versi 6.x terbaru.

• Node.js versi sebelum 8.0: Gunakan SDK versi 4.x.

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

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

Setelah instalasi selesai, Anda dapat menjalankan perintah npm list ali-oss untuk memverifikasi instalasi. Jika berhasil, versi SDK akan ditampilkan.

Konfigurasikan kredensial akses

Konfigurasikan kredensial akses menggunakan Pasangan Kunci Akses (AccessKey pair) dari pengguna RAM.

1. Di Konsol RAM, buat pengguna RAM dengan Permanent AccessKey Pair. Simpan pasangan AccessKey tersebut dan berikan izin AliyunOSSFullAccess kepada pengguna.

2. Gunakan pasangan AccessKey pengguna RAM untuk mengonfigurasi variabel lingkungan.

   Linux

   1. Jalankan perintah berikut di antarmuka baris perintah untuk menambahkan pengaturan variabel lingkungan ke file ~/.bashrc.

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

   2. Jalankan perintah berikut untuk menerapkan perubahan.

      source ~/.bashrc

   3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Jalankan perintah berikut di terminal untuk melihat jenis shell default.

      echo $SHELL

   2. Lakukan operasi berikut berdasarkan jenis shell default.

      1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.zshrc.

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

      2. Jalankan perintah berikut untuk menerapkan perubahan.

         source ~/.zshrc

      3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.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. Jalankan perintah berikut untuk menerapkan perubahan.

         source ~/.bash_profile

      3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   1. Jalankan perintah berikut di CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   1. Jalankan perintah berikut di 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. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

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

Inisialisasi klien

Kode contoh berikut menunjukkan cara menginisialisasi klien menggunakan titik akhir publik wilayah China (Hangzhou) dan memverifikasi konfigurasi SDK dengan mencantumkan bucket dalam akun Anda. Untuk daftar lengkap wilayah dan titik akhir, lihat Wilayah dan titik akhir.

// Contoh kode untuk menginisialisasi klien OSS menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
        region: 'oss-cn-hangzhou',
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Aktifkan Signature V4.
        authorizationV4: true,
    });

    try {
        // Cantumkan semua bucket.
        const result = await client.listBuckets();
        
        // Cetak daftar bucket.
        console.log(`Ditemukan ${result.buckets.length} bucket:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Gagal mencantumkan bucket. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Gunakan titik akhir internal

Anda dapat mengakses OSS melalui jaringan internal untuk menghindari biaya transfer data serta mencapai kecepatan akses yang lebih tinggi dan keamanan yang lebih baik. Untuk mengakses OSS melalui jaringan internal, atur titik akhir ke titik akhir internal saat inisialisasi klien.

const client = new OSS({
    // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
    region: 'oss-cn-hangzhou',
    // Dapatkan kredensial akses dari variabel lingkungan.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Aktifkan Signature V4.
    authorizationV4: true,
    // Gunakan titik akhir internal. Contoh ini menggunakan titik akhir internal wilayah China (Hangzhou).
    endpoint: 'https://oss-cn-hangzhou-internal.aliyuncs.com',
});

Gunakan nama domain kustom

Untuk mengakses OSS menggunakan nama domain kustom, atur titik akhir ke nama domain kustom dan aktifkan opsi CNAME dengan mengatur parameter cname: true saat inisialisasi klien.

Sebelum menggunakan nama domain kustom, pastikan nama domain tersebut telah dipetakan ke bucket. Untuk informasi selengkapnya, lihat Akses OSS menggunakan nama domain kustom.

// Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
const client = new OSS({
    // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
    region: 'oss-cn-hangzhou',
    // Dapatkan kredensial akses dari variabel lingkungan.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Aktifkan Signature V4.
    authorizationV4: true,
    // Gunakan nama domain kustom.
    endpoint: 'http://example.com',
    // Tentukan nama bucket. Nama bucket harus dipetakan ke nama domain kustom.
    bucket: 'example-bucket',
    // Aktifkan opsi CNAME.
    cname: true,
});

Gunakan titik akhir percepatan

Untuk mempercepat akses, atur titik akhir ke titik akhir percepatan saat menginisialisasi klien OSS.

// Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
const client = new OSS({
    // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
    region: 'oss-cn-hangzhou',
    // Dapatkan kredensial akses dari variabel lingkungan.
    accessKeyId: process.env.OSS_ACCESS_KEY_ID,
    accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    // Aktifkan Signature V4.
    authorizationV4: true,
    // Gunakan titik akhir percepatan.
    endpoint: 'https://oss-accelerate.aliyuncs.com',
    // Tentukan nama bucket. Percepatan transfer harus diaktifkan untuk bucket tersebut.
    bucket: 'example-bucket',
});

Versi tanda tangan

Kode contoh berikut menunjukkan cara menginisialisasi klien menggunakan Signature V1. Untuk contoh cara menginisialisasi klien menggunakan Signature V4, lihat Inisialisasi klien.

// Contoh kode untuk menginisialisasi klien OSS menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
    });

    try {
        // Cantumkan semua bucket.
        const result = await client.listBuckets();
        
        // Cetak daftar bucket.
        console.log(`Ditemukan ${result.buckets.length} bucket:`);
        
        for (const bucket of result.buckets) {
            console.log(bucket.name);
        }
        
    } catch (err) {
        console.log('Gagal mencantumkan bucket. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Unggah file

Contoh berikut menunjukkan cara mengunggah file lokal ke bucket OSS. Contoh ini juga menunjukkan cara mengatur properti file menggunakan header permintaan kustom untuk kontrol detail halus atas kelas penyimpanan, izin akses, dan tag.

// Contoh kode untuk mengunggah file menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
        region: 'oss-cn-hangzhou',
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Aktifkan Signature V4.
        authorizationV4: true,
        // Tentukan nama bucket.
        bucket: 'example-bucket',
    });

    // Header permintaan kustom.
    const headers = {
        // Tentukan kelas penyimpanan objek.
        'x-oss-storage-class': 'Standard',
        // Tentukan daftar kontrol akses (ACL) objek.
        'x-oss-object-acl': 'private',
        // Tentukan bahwa file diunduh sebagai lampiran saat diakses melalui URL.
        'Content-Disposition': 'attachment',
        // Atur tag untuk objek. Anda dapat mengatur beberapa tag.
        'x-oss-tagging': 'Tag1=1&Tag2=2',
        // Tentukan apakah objek dengan nama yang sama akan ditimpa. Pada contoh ini, parameter ini diatur ke true, yang berarti objek dengan nama yang sama tidak akan ditimpa.
        'x-oss-forbid-overwrite': 'true',
    };

    try {
        // Konfigurasikan informasi file.
        const key = 'dest.jpg';                    // Jalur file di OSS.
        const localFilePath = path.normalize('dest.jpg'); // Jalur lengkap file lokal.
        
        // Unggah file lokal ke jalur yang ditentukan di OSS.
        const result = await client.put(key, localFilePath, { headers });
        
        console.log(`File diunggah: ${localFilePath} -> ${key}`);
        console.log('Hasil unggah:', result);
        
    } catch (err) {
        console.log('Unggah gagal. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Unduh file

Contoh berikut menunjukkan cara mengunduh file dari bucket OSS ke jalur lokal yang ditentukan.

// Contoh kode untuk mengunduh file menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
        region: 'oss-cn-hangzhou',
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Aktifkan Signature V4.
        authorizationV4: true,
        // Tentukan nama bucket.
        bucket: 'example-bucket',
    });

    try {
        // Konfigurasikan informasi file.
        const key = 'dest.jpg';       // Jalur file di OSS.
        const filePath = 'dest.jpg';  // Jalur lokal untuk menyimpan file.
        
        // Unduh file dari OSS ke jalur lokal yang ditentukan.
        const result = await client.get(key, filePath);
        
        console.log(`File diunduh: ${key} -> ${filePath}`);
        
    } catch (err) {
        console.log('Unduh gagal. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Hapus file

Contoh berikut menunjukkan cara menghapus file tertentu dari bucket OSS.

// Contoh kode untuk menghapus file menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
        region: 'oss-cn-hangzhou',
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Aktifkan Signature V4.
        authorizationV4: true,
        // Tentukan nama bucket.
        bucket: 'example-bucket',
    });

    try {
        // Konfigurasikan informasi file.
        const key = 'dest.jpg';  // Jalur file yang akan dihapus di OSS.
        
        // Hapus file tertentu dari OSS.
        const result = await client.delete(key);
        
        console.log(`File dihapus: ${key}`);
        console.log('Hasil hapus:', result);
        
    } catch (err) {
        console.log('Hapus gagal. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Daftar file

Contoh berikut menunjukkan cara mencantumkan file dalam bucket OSS. Secara default, detail hingga 100 file dikembalikan.

// Contoh kode untuk mencantumkan file menggunakan OSS SDK for Node.js

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

async function main() {
    
    // Dapatkan kredensial akses dari variabel lingkungan. Anda harus mengatur variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET.
    const client = new OSS({
        // Atur wilayah ke oss-cn-hangzhou, yaitu wilayah China (Hangzhou).
        region: 'oss-cn-hangzhou',
        // Dapatkan kredensial akses dari variabel lingkungan.
        accessKeyId: process.env.OSS_ACCESS_KEY_ID,
        accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
        // Aktifkan Signature V4.
        authorizationV4: true,
        // Tentukan nama bucket.
        bucket: 'example-bucket',
    });

    try {
        // Secara default, maksimal 100 file dikembalikan jika tidak ada parameter yang ditentukan.
        const result = await client.list();
        
        console.log(`Ditemukan ${result.objects ? result.objects.length : 0} file:`);
        
        // Cetak daftar file.
        if (result.objects && result.objects.length > 0) {
            for (const object of result.objects) {
                console.log(`Nama file: ${object.name}, Ukuran: ${object.size} byte, Terakhir dimodifikasi: ${object.lastModified}`);
            }
        } else {
            console.log('Tidak ada file yang ditemukan di bucket.');
        }
        
    } catch (err) {
        console.log('Gagal mencantumkan file. Detail:');
        console.error(err);
        return;
    }
}

// Jalankan fungsi utama.
main().catch(console.error);

Gunakan pasangan AccessKey pengguna RAM

Metode ini cocok untuk aplikasi yang diterapkan di lingkungan aman dan stabil, memerlukan akses jangka panjang ke OSS, dan tidak memerlukan rotasi kredensial yang sering. Anda dapat menginisialisasi penyedia kredensial menggunakan pasangan AccessKey (ID AccessKey dan Rahasia AccessKey) dari akun Alibaba Cloud atau pengguna RAM. Metode ini mengharuskan Anda memelihara pasangan AccessKey secara manual, yang dapat menimbulkan risiko keamanan dan meningkatkan kompleksitas pemeliharaan.

1. Gunakan pasangan AccessKey pengguna RAM untuk mengonfigurasi variabel lingkungan.

   Linux

   1. Jalankan perintah berikut di antarmuka baris perintah untuk menambahkan pengaturan variabel lingkungan ke file ~/.bashrc.

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

   2. Jalankan perintah berikut untuk menerapkan perubahan.

      source ~/.bashrc

   3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Jalankan perintah berikut di terminal untuk melihat jenis shell default.

      echo $SHELL

   2. Lakukan operasi berikut berdasarkan jenis shell default.

      Zsh

      1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.zshrc.

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

      2. Jalankan perintah berikut untuk menerapkan perubahan.

         source ~/.zshrc

      3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Jalankan perintah berikut untuk menambahkan pengaturan variabel lingkungan ke file ~/.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. Jalankan perintah berikut untuk menerapkan perubahan.

         source ~/.bash_profile

      3. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Jalankan perintah berikut di CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Jalankan perintah berikut di 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. Jalankan perintah berikut untuk memverifikasi bahwa variabel lingkungan telah dikonfigurasi.

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

2. Setelah mengubah variabel lingkungan sistem, mulai ulang atau refresh lingkungan kompilasi dan runtime—seperti IDE, antarmuka baris perintah, aplikasi desktop lainnya, dan layanan backend—untuk memastikan variabel lingkungan sistem terbaru dimuat.

3. Teruskan informasi kredensial menggunakan variabel lingkungan.

   const OSS = require("ali-oss");
   
   // Inisialisasi OSS.
   const client = new OSS({
     // Dapatkan nilai ID AccessKey dari variabel lingkungan.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Dapatkan nilai Rahasia AccessKey dari variabel lingkungan.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Gunakan token STS

Metode ini cocok untuk aplikasi yang memerlukan akses sementara ke OSS. Anda dapat menginisialisasi penyedia kredensial menggunakan kredensial identitas sementara (ID AccessKey, Rahasia AccessKey, dan token keamanan) yang diperoleh dari STS. Metode ini mengharuskan Anda memelihara token STS secara manual, yang dapat menimbulkan risiko keamanan dan meningkatkan kompleksitas pemeliharaan. Untuk mengakses OSS sementara beberapa kali, Anda harus me-refresh token STS secara manual.

1. Gunakan kredensial identitas sementara untuk mengatur variabel lingkungan.

   macOS, Linux, dan Unix

   Penting

   • Gunakan kredensial identitas sementara (ID AccessKey, Rahasia AccessKey, dan token keamanan) yang diperoleh dari STS, bukan pasangan AccessKey pengguna RAM.

   • ID AccessKey yang diperoleh dari STS diawali dengan "STS", misalnya "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

   Penting

   • Gunakan kredensial identitas sementara (ID AccessKey, Rahasia AccessKey, dan token keamanan) yang diperoleh dari STS, bukan pasangan AccessKey (ID AccessKey dan Rahasia AccessKey) pengguna RAM.

   • ID AccessKey yang diperoleh dari STS diawali dengan "STS", misalnya "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. Teruskan informasi kredensial menggunakan variabel lingkungan.

   const OSS = require("ali-oss");
   
   // Inisialisasi OSS.
   const client = new OSS({
     // Dapatkan nilai ID AccessKey dari variabel lingkungan.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Dapatkan nilai Rahasia AccessKey dari variabel lingkungan.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // Dapatkan nilai token STS dari variabel lingkungan.
     stsToken: process.env.OSS_SESSION_TOKEN
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Gunakan ARN peran RAM

Metode ini cocok untuk aplikasi yang memerlukan akses resmi ke OSS, seperti akses lintas akun. Anda dapat menginisialisasi penyedia kredensial dengan menentukan Nama Sumber Daya Alibaba Cloud (ARN) dari peran RAM. Metode ini berbasis token STS. Alat kredensial memperoleh token STS dari STS dan memanggil operasi AssumeRole untuk meminta token STS baru sebelum yang saat ini kedaluwarsa. Anda juga dapat memberikan nilai pada parameter policy untuk membatasi lebih lanjut izin peran RAM.

1. Tambahkan dependensi kredensial.

   npm install @alicloud/credentials

2. Konfigurasikan pasangan AccessKey dan ARN peran RAM sebagai kredensial akses.

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // Inisialisasi klien Credentials menggunakan ARN peran RAM.
   const credentialsConfig = new Credential.Config({
     // Jenis kredensial.
     type: "ram_role_arn",
     // Dapatkan nilai ID AccessKey dari variabel lingkungan.
     accessKeyId: process.env.OSS_ACCESS_KEY_ID,
     // Dapatkan nilai Rahasia AccessKey dari variabel lingkungan.
     accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
     // ARN peran RAM yang akan diasumsikan. Contoh: acs:ram::123456789012****:role/adminrole. Anda dapat mengatur roleArn menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
     roleArn: '<RoleArn>',
     // Nama sesi peran. Anda dapat mengatur RoleSessionName menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
     roleSessionName: '<RoleSessionName>',
     // Kebijakan akses yang lebih restriktif. Parameter ini opsional. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: '<Policy>',
     roleSessionExpiration: 3600
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // Inisialisasi OSS.
   const client = new OSS({
     accessKeyId:credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // Penyedia kredensial mengontrol pembaruan accessKeyId, accessKeySecret, dan stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log( buckets);

Gunakan peran RAM ECS

Metode ini cocok untuk aplikasi yang berjalan pada instance ECS, instance ECI, atau node pekerja Container Service for Kubernetes. Kami merekomendasikan Anda menginisialisasi penyedia kredensial menggunakan peran RAM ECS. Metode ini berbasis token STS. Peran RAM ECS memungkinkan Anda menyambungkan peran ke instance ECS, instance ECI, atau node pekerja Container Service for Kubernetes untuk me-refresh token STS secara otomatis di dalam instance. Metode ini menghilangkan kebutuhan untuk menyediakan pasangan AccessKey atau token STS, sehingga mengurangi risiko yang terkait dengan pemeliharaan manual. Untuk mempelajari cara mendapatkan peran RAM ECS, lihat Buat peran RAM untuk akun Alibaba Cloud tepercaya. Untuk mempelajari cara menyambungkan peran ke instance ECS, lihat Sambungkan peran RAM instans.

1. Tambahkan dependensi kredensial.

   npm install @alicloud/credentials

2. Konfigurasikan peran RAM ECS sebagai kredensial akses.

   const Credential = require("@alicloud/credentials");
   const OSS = require("ali-oss");
   
   // Inisialisasi klien Credentials menggunakan ARN peran RAM.
   const credentialsConfig = new Credential.Config({
     // Jenis kredensial.
     type: "ecs_ram_role",
     // Opsional. Nama peran ECS. Jika Anda tidak menentukan parameter ini, nama peran akan diperoleh secara otomatis. Kami menyarankan Anda menentukan parameter ini untuk mengurangi jumlah permintaan. Anda dapat mengatur roleName menggunakan variabel lingkungan ALIBABA_CLOUD_ECS_METADATA.
     roleName: '<RoleName>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   
   const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
   // Inisialisasi klien OSS.
   const client = new OSS({
     accessKeyId,
     accessKeySecret,
     stsToken: securityToken,
     refreshSTSTokenInterval: 0, // Penyedia kredensial mengontrol pembaruan accessKeyId, accessKeySecret, dan stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);

Gunakan ARN peran OIDC

Setelah Anda mengonfigurasi peran RAM untuk node pekerja di Container Service for Kubernetes, aplikasi dalam pod pada node tersebut dapat memperoleh token STS dari peran yang dilampirkan melalui layanan meta global. Proses ini mirip dengan cara aplikasi yang diterapkan di ECS memperoleh kredensial. Namun, jika aplikasi tidak tepercaya diterapkan pada kluster kontainer, seperti aplikasi dari pelanggan dengan kode sumber tertutup, Anda mungkin tidak ingin mereka memperoleh token STS dari peran RAM instans yang dilampirkan ke node pekerja. Untuk memastikan keamanan sumber daya cloud Anda sekaligus memungkinkan aplikasi tidak tepercaya ini memperoleh token STS yang diperlukan secara aman dan mencapai minimalisasi izin tingkat aplikasi, Anda dapat menggunakan fitur RAM Roles for Service Accounts (RRSA). Metode ini berbasis token STS. Kluster kontainer Alibaba Cloud membuat dan memasang file token OIDC service account yang sesuai untuk pod aplikasi yang berbeda serta menyuntikkan informasi konfigurasi terkait ke dalam variabel lingkungan. Alat kredensial memperoleh informasi konfigurasi dari variabel lingkungan dan memanggil operasi AssumeRoleWithOIDC dari STS untuk menukar token STS dari peran yang terikat. Metode ini menghilangkan kebutuhan untuk menyediakan pasangan AccessKey atau token STS, sehingga mengurangi risiko yang terkait dengan pemeliharaan manual. Untuk informasi selengkapnya, lihat Konfigurasikan izin RAM ServiceAccount menggunakan RRSA untuk mencapai isolasi izin tingkat pod.

1. Tambahkan dependensi kredensial.

   npm install @alicloud/credentials

2. Konfigurasikan peran RAM OIDC sebagai kredensial akses.

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   const credentialsConfig = new Credential.Config({
     // Jenis kredensial.
     type: "oidc_role_arn",
     // ARN peran RAM. Anda dapat mengatur roleArn menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_ARN.
     roleArn: '<RoleArn>',
     // ARN penyedia OIDC. Anda dapat mengatur oidcProviderArn menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_PROVIDER_ARN.
     oidcProviderArn: '<OidcProviderArn>',
     // Jalur file token OIDC. Anda dapat mengatur oidcTokenFilePath menggunakan variabel lingkungan ALIBABA_CLOUD_OIDC_TOKEN_FILE.
     oidcTokenFilePath: '<OidcTokenFilePath>',
     // Nama sesi peran. Anda dapat mengatur roleSessionName menggunakan variabel lingkungan ALIBABA_CLOUD_ROLE_SESSION_NAME.
     roleSessionName: '<RoleSessionName>',
     // Kebijakan akses yang lebih restriktif. Parameter ini opsional. Contoh: {"Statement": [{"Action": ["*"],"Effect": "Allow","Resource": ["*"]}],"Version":"1"}
     // policy: "<Policy>",
     // Atur waktu kedaluwarsa sesi.
     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, // Penyedia kredensial mengontrol pembaruan accessKeyId, accessKeySecret, dan stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
       
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   const buckets = await client.listBuckets();
   
   console.log(buckets);

Gunakan URI kredensial

Metode ini cocok untuk aplikasi yang perlu memperoleh kredensial Alibaba Cloud dari sistem eksternal untuk manajemen kredensial yang fleksibel dan akses tanpa kunci. Anda dapat menginisialisasi penyedia kredensial menggunakan URI kredensial. Metode ini berbasis token STS. Alat kredensial memperoleh token STS dari URI yang disediakan untuk menginisialisasi klien kredensial. Metode ini menghilangkan kebutuhan untuk menyediakan pasangan AccessKey atau token STS, sehingga mengurangi risiko yang terkait dengan pemeliharaan manual.

1. Agar alat kredensial dapat mengurai dan menggunakan token STS dengan benar, URI harus mematuhi protokol respons berikut:

   • Kode status respons: 200

   • Struktur isi respons:

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

2. Tambahkan dependensi kredensial.

   npm install @alicloud/credentials

3. Konfigurasikan URI kredensial sebagai kredensial akses.

   const OSS = require("ali-oss");
   const Credential = require("@alicloud/credentials");
   
   // Inisialisasi klien Credentials menggunakan URI kredensial.
   const credentialsConfig = new Credential.Config({
     // Jenis kredensial.
     type: "credentials_uri",
     // URI tempat memperoleh kredensial. Formatnya http://local_or_remote_uri/. Anda dapat mengatur credentialsUri menggunakan variabel lingkungan ALIBABA_CLOUD_CREDENTIALS_URI.
     credentialsURI: '<CredentialsUri>'
   });
   const credentialClient = new Credential.default(credentialsConfig);
   const credential = await credentialClient.getCredential();
   
   // Inisialisasi OSS.
   const client = new OSS({
     accessKeyId: credential.accessKeyId,
     accessKeySecret: credential.accessKeySecret,
     stsToken: credential.securityToken,
     refreshSTSTokenInterval: 0, // Penyedia kredensial mengontrol pembaruan accessKeyId, accessKeySecret, dan stsToken.
     refreshSTSToken: async () => {
       const { accessKeyId, accessKeySecret, securityToken } = await credentialClient.getCredential();
   
       return {
         accessKeyId,
         accessKeySecret,
         stsToken: securityToken,
       };
     }
   });
   
   // listBuckets
   const buckets = await client.listBuckets();
   console.log(buckets);