Object Storage Service:ossutil 2.0 CLI

Mulai cepat

Untuk menggunakan antarmuka baris perintah ossutil 2.0, Anda perlu:

Konfigurasikan ossutil

Untuk menghindari kesalahan akibat pengaturan yang tidak lengkap, kami menyarankan menggunakan wizard konfigurasi ossutil guna mengatur ID AccessKey, Secret AccessKey, dan ID wilayah secara cepat. Untuk opsi lanjutan, lihat Panduan konfigurasi untuk mengonfigurasi kredensial akses secara manual.

Contoh ini menunjukkan cara menggunakan wizard konfigurasi untuk mengatur pasangan AccessKey Pengguna RAM sebagai kredensial akses Anda.

Jalankan perintah

1. Buat bucket.

   ossutil mb oss://examplebucket

   Output berikut menunjukkan bahwa bucket examplebucket telah dibuat.

   0.668238(s) elapsed

2. Unggah file ke bucket.

   1. Buat file lokal bernama uploadFile.txt.

      echo 'Hello, OSS!' > uploadFile.txt

   2. Unggah file tersebut ke bucket examplebucket.

      ossutil cp uploadFile.txt oss://examplebucket

      Output berikut menunjukkan bahwa file berhasil diunggah ke bucket examplebucket.

      Success: Total 1 file, size 12 B, Upload done:(1 objects, 12 B), avg 44 B/s
      
      0.271779(s) elapsed

3. Unduh file.

   Unduh file uploadFile.txt dari bucket examplebucket ke direktori localfolder.

   ossutil cp oss://examplebucket/uploadFile.txt localfolder/

   Output berikut menunjukkan bahwa file berhasil diunduh ke direktori localfolder.

   Success: Total 1 object, size 12 B, Download done:(1 files, 12 B), avg 74 B/s
   
   0.162447(s) elapsed

4. Daftar file dalam bucket examplebucket.

   ossutil ls oss://examplebucket

   Output berikut menunjukkan bahwa daftar file dalam bucket examplebucket berhasil ditampilkan.

   LastModifiedTime                   Size(B)  StorageClass   ETAG                                  ObjectName
   2024-11-26 14:35:29 +0800 CST           12      Standard   1103F650EB2C292D179A032D2A97B0F5      oss://examplebucket/uploadFile.txt
   Object Number is: 1
   
   0.124679(s) elapsed

5. Hapus file uploadFile.txt dari bucket examplebucket.

   ossutil rm oss://examplebucket/uploadFile.txt

   Output berikut menunjukkan bahwa file uploadFile.txt berhasil dihapus dari bucket examplebucket.

   0.295530(s) elapsed

6. Hapus bucket examplebucket.

   ossutil rb oss://examplebucket

   Output berikut menunjukkan bahwa bucket examplebucket berhasil dihapus.

   0.478659(s) elapsed

Konfigurasi

ossutil sangat fleksibel dan dapat dikonfigurasi melalui file konfigurasi, variabel lingkungan, atau opsi baris perintah.

Urutan prioritas konfigurasi

ossutil membaca pengaturan berdasarkan urutan prioritas berikut:

opsi baris perintah (seperti -i, -k, dan -e) > variabel lingkungan (seperti OSS_ACCESS_KEY_ID) > file konfigurasi (~/.ossutilconfig)

File konfigurasi

Anda dapat mengonfigurasi ossutil menggunakan file konfigurasi. Path default-nya adalah ~/.ossutilconfig, atau Anda dapat menentukan path kustom dengan flag -c. Jika menggunakan file konfigurasi default, Anda dapat menjalankan perintah ossutil secara langsung tanpa perlu menentukan path file. Contohnya:

ossutil ls oss://examplebucket

Jika Anda menggunakan path file konfigurasi kustom, seperti /path/yourconfig, gunakan opsi -c untuk menentukan path tersebut. Contohnya:

ossutil -c /path/yourconfig ls oss://examplebucket

[default]
accessKeyID = "your-access-key-id"
accessKeySecret = "your-access-key-secret"

[buckets name]
bucket-name = 
  key=value

[buckets dev-bucket]
bucket-hz-01 = 
  region=cn-hangzhou
bucket-hz-02 = 
  region=cn-hangzhou
  endpoint=test.com
  addressing-style=cname
bucket-bj-01 = 
  region=cn-beijing

Konfigurasi variabel lingkungan

Variabel lingkungan berikut didukung:

Opsi baris perintah

ossutil menyediakan berbagai opsi baris perintah, termasuk opsi baris perintah global. Opsi baris perintah memiliki prioritas tertinggi dan menggantikan parameter yang ditetapkan dalam file konfigurasi atau variabel lingkungan.

ossutil ls oss://examplebucket -i "your-access-key-id" -k "your-access-key-secret" --region cn-hangzhou

Kredensial akses

Pasangan Kunci Akses Pengguna RAM

Jika aplikasi Anda berjalan di lingkungan aman, memerlukan akses jangka panjang ke OSS, dan tidak dapat sering memutar kredensial, Anda dapat menginisialisasi penyedia kredensial menggunakan pasangan AccessKey (ID AccessKey dan Secret AccessKey) dari Akun Alibaba Cloud atau Pengguna RAM. Pendekatan ini memerlukan pemeliharaan manual pasangan AccessKey, sehingga meningkatkan risiko keamanan dan beban pemeliharaan.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourAccessKeySecret
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourAccessKeyID -k yourAccessKeySecret

Kredensial keamanan sementara

Jika aplikasi Anda memerlukan akses sementara ke OSS, Anda dapat menginisialisasi penyedia kredensial menggunakan kredensial keamanan sementara (ID AccessKey, Secret AccessKey, dan token keamanan) yang diperoleh dari Security Token Service (STS). Pendekatan ini memerlukan pemeliharaan manual token keamanan, sehingga meningkatkan risiko keamanan dan kompleksitas, serta mengharuskan Anda memperbarui token secara manual untuk setiap akses sementara berulang.

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

export OSS_ACCESS_KEY_ID=yourSTSAccessKeyID
export OSS_ACCESS_KEY_SECRET=yourSTSAccessKeySecret
export OSS_SESSION_TOKEN=yourSecurityToken
ossutil ls oss://examplebucket

ossutil ls oss://examplebucket -i yourSTSAccessKeyID -k yourSTSAccessKeySecret -t yourSecurityToken --region cn-hangzhou

ARN Peran RAM

Jika aplikasi Anda memerlukan akses berwenang ke OSS—misalnya, untuk mengakses OSS lintas akun Alibaba Cloud—Anda dapat menggunakan RAMRoleARN untuk menginisialisasi penyedia kredensial. Metode ini menggunakan token STS secara internal. Dengan menentukan ARN (Nama Sumber Daya Alibaba Cloud) dari peran RAM, alat kredensial memperoleh token STS dari layanan STS dan memanggil API AssumeRole untuk meminta token STS baru sebelum sesi berakhir. Selain itu, Anda dapat memberikan nilai ke parameter policy guna membatasi peran RAM pada kumpulan izin yang lebih kecil.

Buat file konfigurasi berikut dan simpan sebagai ~/.ossutilconfig. Konfigurasi ini tidak dapat ditetapkan melalui variabel lingkungan atau opsi baris perintah.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
mode = RamRoleArn
roleArn = acs:ram::137918634953****:role/Alice
roleSessionName = session_name_example
region=ap-southeast-1

Untuk mengkueri objek di bucket examplebucket, jalankan perintah berikut:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Peran RAM instans ECS

Jika aplikasi Anda berjalan di instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes, kami menyarankan menggunakan ECSRAMRole untuk menginisialisasi penyedia kredensial. Metode ini memanfaatkan token STS dalam implementasi dasarnya. ECSRAMRole memungkinkan Anda mengaitkan peran dengan instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes guna memperbarui token STS secara otomatis pada instans tersebut. Pendekatan ini menghilangkan kebutuhan untuk menyediakan AccessKey (AK) atau token STS secara manual, sekaligus mengurangi risiko yang terkait dengan pemeliharaan manual. Untuk informasi lebih lanjut tentang cara mendapatkan ECSRAMRole, lihat Buat peran.

Mode EcsRamRole

[default]
mode = EcsRamRole
# Parameter ecsRoleName opsional. Jika tidak diatur, peran akan diperoleh secara otomatis.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode EcsRamRole

EcsRamRole IMDSv2 mode

[default]
mode = Ali-EcsRamRole
# Parameter ecsRoleName opsional. Jika tidak diatur, peran akan diperoleh secara otomatis.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

ossutil ls oss://examplebucket -c ~/.ossutilconfig

ossutil ls oss://examplebucket --mode Ali-EcsRamRole

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 untuk peran terkait melalui layanan metadata, sebagaimana halnya aplikasi yang diterapkan pada instans ECS. Namun, jika aplikasi tidak tepercaya—misalnya, aplikasi dari pelanggan dengan kode sumber tertutup—dijalankan pada kluster kontainer, Anda mungkin tidak ingin aplikasi tersebut memperoleh token STS peran RAM yang dikaitkan dengan instans node pekerja melalui layanan metadata. Untuk menjaga keamanan sumber daya cloud sekaligus memungkinkan aplikasi tidak tepercaya tersebut memperoleh token STS yang diperlukan secara aman dengan menerapkan prinsip hak istimewa minimal tingkat aplikasi, Anda dapat menggunakan fitur RRSA (Peran RAM untuk Akun Layanan). Pendekatan ini berbasis token STS. Kluster kontainer Alibaba Cloud secara otomatis membuat dan memasang file token OIDC akun layanan yang sesuai untuk setiap Pod aplikasi, serta menyuntikkan informasi konfigurasi terkait ke dalam variabel lingkungan. Alat kredensial kemudian mengambil informasi konfigurasi tersebut dari variabel lingkungan dan memanggil API AssumeRoleWithOIDC dari layanan STS untuk menukar token OIDC dengan token STS yang dikaitkan dengan peran tersebut. Metode ini tidak memerlukan penyediaan Access Key (AK) atau token STS secara manual, sehingga menghilangkan risiko yang terkait dengan pengelolaan AK atau token STS secara manual. Untuk informasi lebih lanjut, lihat Konfigurasi izin RAM untuk ServiceAccount menggunakan RRSA untuk menerapkan isolasi izin tingkat pod.

Buat file konfigurasi berikut dan simpan sebagai ~/.ossutilconfig. Konfigurasi ini tidak dapat ditentukan melalui variabel lingkungan atau opsi baris perintah.

[default]
mode = oidcRoleArn
# Menentukan ARN (Nama Sumber Daya Aliyun) penyedia OIDC. Formatnya adalah acs:ram::account-id:oidc-provider/provider-name.
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Menentukan path file tempat token OIDC disimpan.
OIDCTokenFilePath=OIDCTokenFilePath
# ARN peran yang akan diasumsikan. Formatnya adalah acs:ram::account-id:role/role-name.
roleArn=acs:ram::113511544585****:role/testoidc
# Nama sesi peran kustom untuk membedakan token yang berbeda.
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

Jalankan perintah berikut untuk mengkueri objek di examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Kredensial proses eksternal

ossutil dapat menjalankan perintah eksternal untuk memperoleh kredensial. Proses eksternal tersebut mengembalikan kredensial ke ossutil melalui stdout.

Perintah eksternal dapat mengembalikan kredensial jangka panjang atau kredensial sementara dalam format berikut.

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk"
}

{
  "AccessKeyId" : "ak",
  "AccessKeySecret" : "sk",
  "Expiration" : "2023-12-29T07:45:02Z",
  "SecurityToken" : "token"
}

Buat file konfigurasi berikut dan simpan ke ~/.ossutilconfig. Pengaturan ini tidak dapat dikonfigurasi melalui variabel lingkungan atau opsi baris perintah.

[default]
mode = Process
credentialProcess = user-cmd
region=ap-southeast-1

Jalankan perintah berikut untuk mengkueri objek di bucket examplebucket:

ossutil ls oss://examplebucket -c ~/.ossutilconfig

Akses anonim

Jika Anda hanya perlu mengakses sumber daya OSS dengan izin public-read, Anda dapat menggunakan akses anonim tanpa menyediakan kredensial apa pun.

ossutil cat oss://bucket/public-object --mode Anonymous

Referensi perintah

ossutil menyediakan tiga jenis perintah: perintah tingkat tinggi, perintah tingkat API, dan perintah bantuan.

ossutil command [argument] [flags]  

ossutil command subcommond [argument] [flags]  

ossutil topic

{
  "CORSRule": {
    "AllowedOrigin": ["www.aliyun.com"],
    "AllowedMethod": ["PUT","GET"],
    "MaxAgeSeconds": 10000
  }
}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration file://cors-configuration.json

{"CORSRule":{"AllowedOrigin":["www.aliyun.com"],"AllowedMethod":["PUT","GET"],"MaxAgeSeconds":10000}}

ossutil api put-bucket-cors --bucket examplebucket --cors-configuration  "{\"CORSRule\":{\"AllowedOrigin\":[\"www.aliyun.com\"],\"AllowedMethod\":[\"PUT\",\"GET\"],\"MaxAgeSeconds\":10000}}"

cat cors-configuration.json | ossutil api put-bucket-cors --bucket examplebucket --cors-configuration -

ossutil api get-bucket-cors --bucket bucketexample
<?xml version="1.0" encoding="UTF-8"?>
<CORSConfiguration>
  <CORSRule>
    <AllowedOrigin>www.aliyun.com</AllowedOrigin>
    <AllowedMethod>PUT</AllowedMethod>
    <AllowedMethod>GET</AllowedMethod>
    <MaxAgeSeconds>10000</MaxAgeSeconds>
  </CORSRule>
  <ResponseVary>false</ResponseVary>
</CORSConfiguration>

ossutil api get-bucket-cors --bucket bucketexample --output-format json
{
  "CORSRule": {
    "AllowedMethod": [
      "PUT",
      "GET"
    ],
    "AllowedOrigin": "www.aliyun.com",
    "MaxAgeSeconds": "10000"
  },
  "ResponseVary": "false"
}

ossutil api get-bucket-cors --bucket bucketexample --output-query CORSRule.AllowedMethod --output-format json
[
  "PUT",
  "GET"
]

ossutil stat oss://bucketexample
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131072
...
StandardObjectCount         : 119212
StandardStorage             : 66756852803
Storage                     : 66756852813
StorageClass                : Standard
TransferAcceleration        : Disabled

ossutil stat oss://bucketexample --human-readable
ACL                         : private
AccessMonitor               : Disabled
ArchiveObjectCount          : 2
ArchiveRealStorage          : 10
ArchiveStorage              : 131.072k
...
StandardObjectCount         : 119.212k
StandardStorage             : 66.757G
Storage                     : 66.757G
StorageClass                : Standard
TransferAcceleration        : Disabled

Opsi baris perintah

Beberapa perintah memerlukan parameter untuk menentukan target atau opsi. Untuk perintah tersebut, berikan nilai yang diperlukan. Contohnya:

ossutil ls --profile dev

Perintah ossutil ls --profile dev menentukan profil konfigurasi dev. Untuk opsi yang memerlukan nilai parameter, pisahkan nama opsi dari nilainya dengan spasi atau tanda sama dengan (=), seperti --profile dev atau --profile=dev. Apit nilai parameter yang mengandung spasi dengan tanda kutip ganda agar penguraiannya benar, misalnya, --description "OSS bucket list".

FAQ

Kesalahan Ossutil: region must be set in sign version 4

Penyebab: Anda tidak menentukan ID wilayah saat mengonfigurasi ossutil 2.0.

Solusi: Untuk mencegah kesalahan ini, konfigurasikan item wajib berikut: AccessKey ID, Secret AccessKey, dan ID wilayah. ID wilayah bersifat wajib karena versi tanda tangan telah ditingkatkan ke V4. Untuk informasi lebih lanjut tentang cara memperoleh ID wilayah, lihat Wilayah dan endpoint.