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 untuk 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 ke bucket examplebucket.

      ossutil cp uploadFile.txt oss://examplebucket

      Output berikut menunjukkan bahwa file berhasil diunggah ke 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 file dalam bucket examplebucket berhasil didaftarkan.

   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 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 menggunakan file konfigurasi, variabel lingkungan, atau opsi baris perintah.

Urutan prioritas konfigurasi

ossutil membaca pengaturan dalam 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 menggunakan flag -c. Jika Anda menggunakan file konfigurasi default, Anda dapat menjalankan perintah ossutil langsung tanpa menentukan path file. Contohnya:

ossutil ls oss://examplebucket

Jika Anda menggunakan path file konfigurasi kustom, seperti /path/yourconfig, Anda harus menggunakan 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 diatur 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 AccessKey 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 dengan pasangan AccessKey (ID AccessKey dan Secret AccessKey) dari Akun Alibaba Cloud atau Pengguna RAM. Metode ini memerlukan pemeliharaan manual pasangan AccessKey, yang 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 dengan kredensial keamanan sementara (ID AccessKey, Secret AccessKey, dan token keamanan) yang diperoleh dari Security Token Service (STS). Metode ini memerlukan pemeliharaan manual token keamanan, meningkatkan risiko keamanan dan kompleksitas. Anda juga harus memperbarui token secara manual untuk 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 policy untuk membatasi peran RAM ke set izin yang lebih kecil.

Buat file konfigurasi berikut dan simpan sebagai ~/.ossutilconfig. Konfigurasi ini tidak dapat diatur menggunakan 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 Anda menggunakan ECSRAMRole untuk menginisialisasi penyedia kredensial. Metode ini menggunakan token STS dalam implementasi dasarnya. ECSRAMRole memungkinkan Anda mengaitkan peran dengan instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes untuk memperbarui token STS secara otomatis dalam instans. Metode ini menghilangkan kebutuhan untuk menyediakan AccessKey (AK) atau token STS dan menghilangkan 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

Mode EcsRamRole IMDSv2

[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 node pekerja di Container Service for Kubernetes, aplikasi dalam Pod pada node tersebut dapat memperoleh token STS untuk peran terkait melalui layanan metadata, seperti aplikasi yang diterapkan di instans ECS. Namun, jika aplikasi tidak tepercaya, seperti aplikasi yang diajukan oleh pelanggan dengan kode sumber tertutup, diterapkan pada kluster kontainer, Anda mungkin tidak ingin mereka memperoleh token STS peran RAM yang dikaitkan dengan instans node pekerja melalui layanan metadata. Untuk menghindari mengompromikan keamanan sumber daya cloud Anda sekaligus memungkinkan aplikasi tidak tepercaya ini memperoleh token STS yang diperlukan secara aman dan menerapkan hak istimewa minimal tingkat aplikasi, Anda dapat menggunakan fitur RRSA (Peran RAM untuk Akun Layanan). Metode ini berbasis token STS. Kluster kontainer Alibaba Cloud membuat dan memasang file token OIDC akun layanan yang sesuai untuk setiap Pod aplikasi dan menyuntikkan informasi konfigurasi terkait ke variabel lingkungan. Alat kredensial kemudian mengambil informasi konfigurasi dari variabel lingkungan dan memanggil API AssumeRoleWithOIDC layanan STS untuk menukar token OIDC dengan token STS yang dikaitkan dengan peran. Metode ini tidak memerlukan Anda untuk menyediakan Access Key (AK) atau token STS, yang menghilangkan risiko yang terkait dengan pemeliharaan manual AK atau token STS. 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. Anda tidak dapat menentukan konfigurasi ini menggunakan 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 mengembalikan kredensial ke ossutil melalui standard output (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 menggunakan 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 bantu.

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 ini, 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 berisi spasi dengan tanda kutip ganda untuk memastikan 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, konfigurasikan item wajib berikut: ID AccessKey, Secret AccessKey, dan ID wilayah. ID wilayah wajib karena versi tanda tangan telah ditingkatkan ke V4. Untuk informasi lebih lanjut tentang cara mendapatkan ID wilayah, lihat Wilayah dan endpoint.