Inisialisasi Node.js SDK untuk terhubung ke OSS -

Client adalah objek utama untuk berinteraksi dengan Object Storage Service (OSS) melalui kit pengembangan perangkat lunak (SDK) Node.js. Client ini mengelola resource OSS, seperti bucket dan file. Untuk mengirim permintaan ke OSS menggunakan SDK Node.js, inisialisasi instance Client dan sesuaikan konfigurasi default sesuai kebutuhan.

Catatan

Anda harus mengonfigurasi kredensial akses sebelum menginisialisasi instance OSSClient. Topik ini memberikan contoh penggunaan variabel lingkungan. Untuk informasi selengkapnya, lihat Konfigurasi kredensial akses (Node.js SDK).
Untuk informasi tentang wilayah OSS dan titik akhir yang sesuai, lihat Wilayah dan titik akhir.
Untuk informasi tentang cara membuat pasangan AccessKey untuk pengguna Resource Access Management (RAM), lihat Buat pasangan AccessKey.

Prasyarat

Penting

Sebelum mengonfigurasi client, Anda harus menyetel variabel lingkungan menggunakan AccessKey pengguna RAM.

Contoh konfigurasi default

Contoh kode berikut menunjukkan cara mengonfigurasi instance OSSClient menggunakan Signature V4 dan Signature V1.

Signature V4 (direkomendasikan)

Penting

Saat menginisialisasi instance OSSClient dengan algoritma Signature V4, tentukan ID wilayah spesifik OSS. ID ini mengidentifikasi wilayah tujuan permintaan dikirim. Misalnya, untuk wilayah China (Hangzhou), atur Region ke oss-cn-hangzhou. Untuk ID wilayah lainnya, lihat Wilayah dan titik akhir.
Dalam kode Anda, Anda harus secara eksplisit mendeklarasikan penggunaan algoritma Signature V4. Contohnya: authorizationV4: true.

Kode berikut memberikan contoh cara mengonfigurasi instance OSSClient menggunakan nama domain OSS dan Signature V4.

Secara default, contoh kode berikut menggunakan nama domain publik bucket dan informasi AccessKey pengguna RAM.

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

const client = new OSS({
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Setel region ke wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel region ke oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Gunakan algoritma Signature V4.
  authorizationV4: true,
  // Setel bucket ke nama bucket Anda.
  bucket: 'yourBucketName',
  // Setel endpoint ke titik akhir publik wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel endpoint ke https://oss-cn-hangzhou.aliyuncs.com.
  endpoint: 'https://oss-cn-hangzhou.aliyuncs.com',
});

Signature V1 (tidak direkomendasikan)

Penting

Mulai 1 Maret 2025, algoritma signature V1 OSS tidak lagi tersedia untuk pelanggan baru dengan UID baru. Mulai 1 September 2025, OSS tidak lagi memperbarui dan memelihara algoritma signature V1, serta algoritma tersebut tidak lagi tersedia untuk bucket baru. Segera tingkatkan dari signature V1 ke signature V4 untuk mencegah dampak pada bisnis Anda.

Kode berikut mengonfigurasi instance OSSClient menggunakan nama domain OSS. Untuk informasi tentang nama domain OSS di berbagai wilayah, lihat Wilayah dan titik akhir.

Buat instance Client menggunakan nama domain OSS

Kode berikut menunjukkan cara menginisialisasi instance menggunakan nama domain OSS.

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

const client = new OSS({
  // Setel region ke wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel region ke oss-cn-hangzhou.
  region: 'yourRegion',
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Setel bucket ke nama bucket Anda.
  bucket: 'yourBucketName',
});

Buat instance Client menggunakan nama domain kustom

Kode berikut menunjukkan cara membuat instance Client menggunakan nama domain kustom. Untuk informasi selengkapnya tentang mengakses OSS menggunakan nama domain kustom, lihat Akses OSS menggunakan nama domain kustom.

Penting

Anda tidak dapat menggunakan metode client.listBuckets() jika menggunakan nama domain kustom.

const OSS = require('ali-oss')

const client = new OSS({  
 // Gunakan nama domain kustom sebagai endpoint.
 endpoint: 'http://img.example.com', 
 // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
 accessKeyId: process.env.OSS_ACCESS_KEY_ID,
 accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
 cname: true,
 // Setel bucket ke nama bucket Anda.
 bucket: 'yourBucketName',
});

Contoh konfigurasi untuk skenario umum

Contoh kode berikut menunjukkan cara mengonfigurasi nama domain lainnya. Secara default, contoh-contoh ini menggunakan Signature V4 dan informasi AccessKey pengguna RAM.

Contoh konfigurasi nama domain internal

Jika aplikasi Anda dideploy pada instance ECS Alibaba Cloud dan perlu sering mengakses resource OSS di wilayah yang sama, Anda dapat menggunakan nama domain internal untuk mengurangi biaya trafik dan meningkatkan kecepatan akses.

Kode berikut menunjukkan contoh cara mengonfigurasi instance OSSClient menggunakan nama domain internal OSS.

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

const client = new OSS({
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Setel region ke wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel region ke oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Gunakan Signature V4.
  authorizationV4: true,
  // Setel bucket ke nama bucket Anda.
  bucket: 'yourBucketName',
  // Setel endpoint ke titik akhir internal wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel endpoint ke https://oss-cn-hangzhou-internal.aliyuncs.com.
  endpoint: 'yourEndpoint',
});

Contoh konfigurasi nama domain kustom

Kode berikut menunjukkan contoh cara mengonfigurasi instance OSSClient menggunakan nama domain kustom.

Peringatan

Anda harus terlebih dahulu menyambungkan nama domain kustom ke nama domain default bucket. Jika tidak, akan terjadi error. Untuk informasi selengkapnya tentang cara menyambungkan nama domain kustom, lihat Akses OSS menggunakan nama domain kustom.

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

const client = new OSS({
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Setel region ke wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel region ke oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  // Gunakan algoritma Signature V4.
  authorizationV4: true,
  // Setel bucket ke nama bucket Anda.
  bucket: 'yourBucketName',
  // Setel endpoint ke nama domain kustom Anda. Misalnya, https://static.example.com.
  endpoint: 'yourEndpoint',
  // Setel cname ke true untuk mengaktifkan opsi CNAME.
  cname: true,
});

Contoh konfigurasi titik akhir percepatan

Kode berikut menunjukkan contoh cara mengonfigurasi instance OSSClient menggunakan titik akhir percepatan.

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

const client = new OSS({
  // Dapatkan kredensial akses dari variabel lingkungan. Sebelum menjalankan kode ini, pastikan variabel lingkungan OSS_ACCESS_KEY_ID dan OSS_ACCESS_KEY_SECRET telah disetel.
  accessKeyId: process.env.OSS_ACCESS_KEY_ID,
  accessKeySecret: process.env.OSS_ACCESS_KEY_SECRET,
  // Setel region ke wilayah tempat bucket berada. Misalnya, untuk China (Hangzhou), setel region ke oss-cn-hangzhou.
  region: 'oss-cn-hangzhou',
  //Gunakan Signature V4.
  authorizationV4: true,
  // Setel bucket ke nama bucket Anda.
  bucket: 'yourBucketName',
  // Setel endpoint ke titik akhir percepatan. Misalnya, oss-accelerate.aliyuncs.com.
  endpoint: 'oss-accelerate.aliyuncs.com',
});

Referensi

Untuk informasi selengkapnya tentang opsi konfigurasi OSSClient, lihat Contoh di GitHub.