Cara mengonfigurasi ossutil - Object Storage Service

Topik ini menjelaskan cara mengonfigurasi ossutil.

Peningkatan versi

Kami menyarankan Anda menggunakan ossutil 2.0 yang telah ditingkatkan. Untuk informasi selengkapnya tentang cara menginstal dan menggunakannya dengan cepat, lihat Instal ossutil.

Berikut adalah fitur utama ossutil 2.0:

Struktur perintah baru: ossutil 2.0 mendukung perintah multi-level, termasuk perintah tingkat API seperti ossutil api put-bucket-acl dan perintah tingkat tinggi seperti ossutil config.
Manajemen konfigurasi yang ditingkatkan: Proses konfigurasi awal disederhanakan. Anda cukup memberikan ID AccessKey, rahasia AccessKey, dan ID wilayah untuk menyelesaikan konfigurasi dasar setelah instalasi. Selain itu, Anda dapat menentukan beberapa file konfigurasi menggunakan parameter --profile guna meningkatkan fleksibilitas.
Parameter filter yang kaya: ossutil 2.0 mendukung berbagai kondisi filter untuk perintah pemrosesan batch, seperti ls, cp, dan rm. Anda dapat memfilter berdasarkan path, ukuran file, waktu modifikasi, atau metadata objek, sehingga meningkatkan presisi dan efisiensi operasi secara signifikan.
Penyesuaian format output yang fleksibel: Parameter baru --output-format memungkinkan Anda mengatur format output menjadi JSON, YAML, atau XML sesuai kebutuhan pemrosesan data. Opsi baru --output-query memungkinkan Anda memfilter output untuk mendapatkan informasi yang dibutuhkan.
Keamanan yang ditingkatkan: Untuk meningkatkan keamanan, ossutil 2.0 memungkinkan Anda mengatur parameter sensitif melalui variabel lingkungan. Pendekatan ini mencegah kunci terpapar di baris perintah dan mengurangi risiko kebocoran informasi. Selain itu, opsi baru --dry-run memungkinkan Anda memverifikasi perilaku perintah sebelum menjalankannya guna memastikan operasi berjalan dengan benar.

Konfigurasi cepat menggunakan perintah config

Dalam kebanyakan kasus, Anda dapat menggunakan perintah ini untuk mengonfigurasi ossutil secara cepat. Perintah ini menyediakan antarmuka interaktif untuk menghasilkan file konfigurasi.

Langkah-langkah berikut menggunakan lingkungan Linux sebagai contoh.

Masukkan perintah konfigurasi.
```
ossutil config
```

Atur path file konfigurasi sesuai permintaan.

Anda dapat menentukan path file konfigurasi sesuai keinginan. Secara default, file konfigurasi disimpan di ~/.ossutilconfig. Tekan Enter untuk menggunakan pengaturan default.

Enter the configuration file name. The file name can include a path (Default: /home/user/.ossutilconfig. Press Enter to use the default path. If you set a different path, you must set the --config-file option to that path when you use commands.):

Atur bahasa alat sesuai permintaan.
Masukkan CH untuk Bahasa Tiongkok atau EN untuk Bahasa Inggris. Secara default, bahasa alat mengikuti bahasa sistem operasi Anda. Pengaturan ini akan berlaku setelah perintah config berhasil dijalankan.

Atur parameter Endpoint, ID AccessKey, rahasia AccessKey, dan STSToken sesuai permintaan. Jika Anda menggunakan kredensial akses sementara dari Security Token Service (STS) untuk mengakses OSS, Anda harus mengonfigurasi parameter STSToken. Jika tidak, biarkan kosong.

Tabel berikut menjelaskan parameter tersebut.

Parameter	Wajib	Deskripsi
endpoint	Ya	Masukkan endpoint wilayah tempat bucket berada. Misalnya, contoh ini menggunakan titik akhir publik untuk wilayah Singapura. Atur ke `https://oss-ap-southeast-1.aliyuncs.com`. Jika Anda ingin mengakses OSS dari layanan Alibaba Cloud lainnya di wilayah yang sama, gunakan titik akhir internal. Atur ke `https://oss-ap-southeast-1-internal.aliyuncs.com`. Untuk informasi selengkapnya tentang wilayah dan endpoint, lihat Wilayah dan endpoint. Penting Karena adanya perubahan kebijakan untuk meningkatkan kepatuhan dan keamanan, mulai 20 Maret 2025, pengguna OSS baru harus menggunakan nama domain kustom (CNAME) untuk melakukan operasi API data pada bucket OSS yang berlokasi di wilayah daratan Tiongkok. Titik akhir publik default dibatasi untuk operasi ini. Lihat pengumuman resmi untuk daftar lengkap operasi yang terdampak. Jika Anda mengakses data melalui HTTPS, Anda harus mengikat Sertifikat SSL yang valid ke domain kustom Anda. Hal ini wajib untuk akses Konsol OSS, karena konsol menerapkan HTTPS.
accessKeyID	Ya	Masukkan pasangan AccessKey untuk akun Anda. Untuk mendapatkan pasangan AccessKey, lihat Buat pasangan AccessKey. Buat pasangan AccessKey secara cepat untuk pengguna RAM dengan izin manajemen OSS menggunakan skrip ROS Pada halaman Create Stack di konsol Resource Orchestration Service (ROS), pilih kotak centang konfirmasi di bawah Security Confirmation, lalu klik Create. Setelah stack dibuat, salin pasangan AccessKey yang dibuat dari tab Outputs.
accessKeySecret	Ya
stsToken	Tidak	Parameter ini hanya diperlukan ketika Anda menggunakan kredensial akses temporary dari STS untuk mengakses OSS. Jika tidak, biarkan kosong dan lewati langkah ini. Untuk informasi tentang cara menghasilkan stsToken, lihat AssumeRole - Dapatkan kredensial identitas temporary untuk peran RAM.

Jika Anda menentukan path kustom untuk file konfigurasi di langkah 2, tambahkan opsi -c untuk menentukan file konfigurasi setiap kali menjalankan perintah.
Sebagai contoh, jika file konfigurasi disimpan di /home/config, gunakan format perintah berikut saat menjalankan perintah ls:
```
ossutil -c /home/config ls oss://examplebucket
```

File konfigurasi perintah

Untuk kenyamanan, Anda dapat menyimpan kredensial dan informasi konfigurasi yang sering digunakan ke dalam file konfigurasi. File konfigurasi menggunakan format INI yang terdiri atas bagian dan kunci. Parameter konfigurasi disimpan dalam bagian tertentu. Tabel berikut menjelaskan parameter konfigurasi umum:

Parameter konfigurasi	Deskripsi	Kode contoh
language	Mengatur bahasa tool ossutil. Nilai yang valid: CH: Cina. EN: Inggris.	`[Credentials] language = CH`
endpoint	Mengatur informasi nama domain untuk wilayah tempat bucket berada.	`[Credentials] endpoint = oss-ap-southeast-1.aliyuncs.com` `[Credentials] endpoint = https://oss-ap-southeast-1.aliyuncs.com`
accessKeyID	Bagian dari pasangan AccessKey yang digunakan untuk mengidentifikasi pengguna dan mengautentikasi permintaan perintah.	`[Credentials] accessKeyID = your_accesskey_id`
accessKeySecret	Bagian dari pasangan AccessKey yang digunakan untuk mengautentikasi kunci pengguna untuk permintaan perintah.	`[Credentials] accessKeySecret = your_accesskey_secret`
stsToken	Token untuk kunci temporary, digunakan untuk mengautentikasi permintaan perintah.	`[Credentials] stsToken = your_sts_token`
mode	Mode autentikasi yang digunakan. Nilai yang valid dapat berupa AK, StsToken, RamRoleArn, atau EcsRamRole.	`[Credentials] mode = RamRoleArn`
ramRoleArn	ARN dari peran RAM untuk mode autentikasi.	`[Credentials] ramRoleArn = your_ram_role_arn`
roleSessionName	Nama sesi untuk mode autentikasi RamRoleArn. Jika tidak diatur, nilai acak akan dihasilkan.	`[Credentials] roleSessionName = your_ram_role_seesion_name`
tokenTimeout	Periode validitas token dalam detik. Ini digunakan untuk mode RamRoleArn. Nilai default adalah 3600.	`[Credentials] tokenTimeout = your_token_timetout`
ecsRoleName	Nama peran untuk mode autentikasi EcsRamRole.	`[Credentials] ecsRoleName = your_ecs_role_name`

Untuk informasi selengkapnya tentang parameter konfigurasi perintah, lihat Edit file konfigurasi.

Opsi baris perintah

Selain menggunakan file konfigurasi, Anda dapat menentukan konfigurasi melalui opsi baris perintah. Opsi baris perintah memiliki prioritas lebih tinggi daripada pengaturan dalam file konfigurasi. Tabel berikut menjelaskan opsi baris perintah umum:

Opsi	Deskripsi	Kode contoh
--loglevel	Tingkat log. Nilai default kosong, yang berarti tidak ada file log yang dihasilkan. Nilai yang valid: info: Menghasilkan log informasi. debug: Menghasilkan log detail, termasuk informasi permintaan dan respons HTTP.	`ossutil64 commandname options --loglevel debug`
--connect-timeout	Periode timeout koneksi client dalam detik. Nilai default adalah 120.	`ossutil64 commandname options --connect-timeout 60`
--read-timeout	Periode timeout pembacaan client dalam detik. Nilai default adalah 1200.	`ossutil64 commandname options --read-timeout 60`
--retry-times	Jumlah percobaan ulang saat terjadi error. Nilai default adalah 10.	`ossutil64 commandname options --retry-times 20`
-e, --endpoint	Nama domain yang diminta.	`ossutil64 commandname options -e oss-ap-southeast-1.aliyuncs.com` `ossutil64 commandname options -e https://oss-ap-southeast-1.aliyuncs.com`
-i, --access-key-id	Kredensial akses yang digunakan untuk mengakses OSS.	`ossutil64 commandname options -i your_access_key`
-k, --access-key-secret	Kredensial akses yang digunakan untuk mengakses OSS.	`ossutil64 commandname options -k your_access_key_secrect`
-t, --sts-token	STSToken yang digunakan untuk mengakses OSS.	`ossutil64 commandname options -i your_sts_token_accesskey_id -k your_sts_token_accesskey_secret -t your_sts_token`
--mode	Mode autentikasi. Nilai yang valid dapat berupa AK, StsToken, RamRoleArn, atau EcsRamRole. Nilai default kosong.	Berikut adalah contoh perintah untuk mengakses OSS dalam mode AK: `ossutil64 commandname options -i your_accesskey_id -k your_accesskey_secret --mode AK`
--ram-role-arn	ARN dari peran RAM untuk mode autentikasi.	`ossutil64 commandname options --ram-role-arn your_ram_role_arn`
--role-session-name	Nama sesi untuk mode autentikasi.	`ossutil64 commandname options --role-session-name your_ram_session_name`
--token-timeout	Periode validitas token dalam detik. Nilai default adalah 3600.	`ossutil64 commandname options --token-timeout 1800`
--ecs-role-name	Nama peran untuk mode autentikasi EcsRamRole.	`ossutil64 commandname options --ecs-role-name your_ecs_role_name`

Untuk informasi selengkapnya tentang konfigurasi opsi, lihat Opsi umum.

Konfigurasikan kredensial akses

Anda dapat mengonfigurasi kredensial akses dengan berbagai cara, seperti menggunakan file konfigurasi atau opsi baris perintah.

Akses menggunakan pasangan AccessKey

Bagian ini menggunakan bucket bernama example-bucket di wilayah Singapura sebagai contoh.

Melalui file konfigurasi

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret

Jalankan perintah berikut untuk mengkueri objek dalam bucket.

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Melalui opsi baris perintah
Anda juga dapat meneruskan pasangan AccessKey sebagai parameter baris perintah. Contoh perintah berikut menunjukkan cara melakukannya:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret ls oss://example-bucket
```
Penting
Meneruskan pasangan AccessKey sebagai parameter baris perintah dapat menyebabkan pasangan tersebut terekam oleh sistem log, sehingga menimbulkan risiko keamanan kebocoran kunci. Gunakan metode ini dengan hati-hati.

Akses menggunakan token temporary

Bagian ini menggunakan bucket bernama example-bucket di wilayah Singapura sebagai contoh.

Melalui file konfigurasi

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
stsToken = yourSecurityToken

Jalankan perintah berikut untuk mengkueri objek dalam bucket.

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Melalui opsi baris perintah
Anda juga dapat meneruskan kredensial akses sebagai parameter baris perintah. Contoh perintah berikut menunjukkan cara melakukannya:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret -t yourSecurityToken ls oss://example-bucket
```
Catatan
Meneruskan pasangan AccessKey sebagai parameter baris perintah dapat menyebabkan pasangan tersebut terekam oleh sistem log, sehingga menimbulkan risiko keamanan kebocoran kunci. Gunakan metode ini dengan hati-hati.

Akses menggunakan peran RAM

Bagian ini menggunakan bucket bernama example-bucket di wilayah Singapura dan peran RAM yang akan diasumsikan bernama ramRoleArnExample sebagai contoh.

Melalui file konfigurasi

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
ramRoleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example (Opsional)
tokenTimeout = 1800 (Opsional)

Jalankan perintah berikut untuk mengkueri objek dalam bucket.

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Melalui opsi baris perintah
Anda juga dapat meneruskan kredensial akses sebagai parameter baris perintah. Contoh perintah berikut menunjukkan cara melakukannya:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com -i yourAccessKeyID -k yourAccessKeySecret --mode RamRoleArn --ram-role-arn acs:ram::137918634953****:role/Alice ls oss://example-bucket
```
Catatan
Meneruskan pasangan AccessKey sebagai parameter baris perintah dapat menyebabkan pasangan tersebut terekam oleh sistem log, sehingga menimbulkan risiko keamanan kebocoran kunci. Gunakan metode ini dengan hati-hati.

Akses menggunakan instance RAM role

Pada instans Elastic Compute Service (ECS), Anda dapat menggunakan instance RAM role untuk mengonfigurasi kredensial akses bagi ossutil. Instance RAM role memungkinkan Anda mengaitkan peran RAM dengan instans ECS dan menggunakan kredensial temporary dari STS untuk menjalankan ossutil pada instans tersebut. Sistem secara otomatis menghasilkan dan memperbarui kredensial temporary tersebut. Aplikasi dapat memperoleh kredensial temporary dari URL metadata instans tertentu tanpa memerlukan manajemen khusus. Penggunaan peran RAM membantu melindungi pasangan AccessKey Anda serta memungkinkan kontrol dan manajemen izin dengan detail halus.

Sebelum memulai, Anda harus membuat instance RAM role pada instans ECS. Untuk informasi selengkapnya, lihat Buat instance RAM role.

Bagian ini menggunakan bucket bernama example-bucket di wilayah Singapura dan peran RAM bernama EcsRamRoleOss yang dibuat pada instans ECS sebagai contoh.

Melalui file konfigurasi

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.

[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
mode = EcsRamRole
ecsRoleName = EcsRamRoleOss

Jalankan perintah berikut untuk mengkueri objek dalam bucket.

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket

Melalui opsi baris perintah
Anda juga dapat meneruskan kredensial akses sebagai parameter baris perintah. Berikut adalah contoh perintah:
```
ossutil64 -e oss-ap-southeast-1.aliyuncs.com --mode EcsRamRole --ecs-role-name EcsRamRoleOss ls oss://example-bucket
```

Konfigurasi endpoint terpisah untuk bucket

Saat menggunakan ossutil, Anda mungkin perlu mengelola beberapa bucket. Dalam kasus ini, Anda harus mengonfigurasi endpoint terpisah untuk setiap bucket. Anda dapat menggunakan salah satu dari dua metode berikut:

Melalui file konfigurasi
Dalam file konfigurasi, Anda dapat menambahkan bagian [Bucket-Endpoint] untuk mengonfigurasi endpoint terpisah bagi setiap bucket yang ditentukan. Formatnya sebagai berikut:
```
[Bucket-Endpoint]
bucket1 = endpoint1
bucket2 = endpoint2
...
```
Contoh berikut menunjukkan cara mengonfigurasi endpoint untuk bucket di wilayah Singapura (example-bucket-sg) dan bucket di wilayah Jepang (Tokyo) (example-bucket-jp).
Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Endpoint]
example-bucket-sg=oss-ap-southeast-1.aliyuncs.com
example-bucket-jp=oss-ap-northeast-1.aliyuncs.com
```
Jalankan perintah berikut untuk mengkueri objek dalam bucket.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-jp
```
Melalui opsi baris perintah
Contoh berikut menunjukkan cara mengonfigurasi endpoint untuk bucket di wilayah Singapura (example-bucket-sg) dan bucket di wilayah Jepang (Tokyo) (example-bucket-jp).
Konfigurasi informasi akun dalam ~/.myossutilconfig.
```
[Credentials]
endpoint = oss-ap-southeast-1.aliyuncs.com
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
```
Tentukan endpoint menggunakan parameter -e.
```
ossutil64 -c ~/.myossutilconfig ls oss://example-bucket-sg
ossutil64 -c ~/.myossutilconfig -e oss-ap-northeast-1.aliyuncs.com ls oss://example-bucket-jp
```

Konfigurasi nama domain kustom

ossutil memungkinkan Anda mengakses sumber daya OSS menggunakan nama domain kustom. Sebelum menggunakan fitur ini, Anda harus mengonfigurasi pemetaan antara bucket dan nama domain kustom dalam file konfigurasi.

Dalam file konfigurasi, Anda dapat menambahkan bagian [Bucket-Cname] untuk mengonfigurasi nama domain kustom bagi setiap bucket yang ditentukan. Formatnya sebagai berikut:

[Bucket-Cname]
bucket1 = cname1
bucket2 = cname2
...

Contoh berikut menunjukkan cara mengakses bucket bernama example-bucket di wilayah Singapura menggunakan nama domain kustom cname.example-***.com.

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig.

[Credentials]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
[Bucket-Cname]
example-bucket=cname.example-***.com

Jalankan perintah berikut untuk mengkueri objek dalam bucket.

ossutil64 -c ~/.myossutilconfig ls oss://example-bucket