Object Storage Service:ossutil 2.0 CLI

Mulai cepat

Untuk menggunakan antarmuka baris perintah ossutil 2.0, Anda perlu melakukan langkah-langkah berikut:

Mengonfigurasi ossutil

Untuk menghindari kesalahan akibat pengaturan yang hilang, sebaiknya gunakan wizard konfigurasi ossutil untuk mengonfigurasi AccessKey ID, AccessKey Secret, dan region ID dengan cepat. Untuk opsi tingkat lanjut, lihat Panduan konfigurasi guna mengonfigurasi kredensial akses secara manual.

Contoh ini menunjukkan cara menggunakan wizard konfigurasi untuk mengatur Pasangan Kunci Akses pengguna RAM sebagai kredensial akses Anda dengan cepat.

Menjalankan perintah

1. Membuat bucket.

   ossutil mb oss://examplebucket

   Output berikut menandakan bahwa bucket examplebucket telah berhasil dibuat.

   0.668238(s) elapsed

2. Mengunggah 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 menandakan bahwa file telah 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. Mengunduh file.

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

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

   Output berikut menandakan bahwa file telah 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. Melihat daftar file dalam bucket examplebucket.

   ossutil ls oss://examplebucket

   Output berikut menandakan bahwa daftar file dalam bucket examplebucket telah 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. Menghapus file uploadFile.txt dari bucket examplebucket.

   ossutil rm oss://examplebucket/uploadFile.txt

   Output berikut menandakan bahwa uploadFile.txt telah berhasil dihapus dari bucket examplebucket.

   0.295530(s) elapsed

6. Menghapus bucket examplebucket.

   ossutil rb oss://examplebucket

   Output berikut menandakan bahwa bucket examplebucket telah berhasil dihapus.

   0.478659(s) elapsed

Konfigurasi

ossutil sangat fleksibel dan dapat dikonfigurasi melalui file konfigurasi, variabel lingkungan, atau opsi command-line.

Prioritas konfigurasi

ossutil membaca konfigurasi berdasarkan urutan prioritas berikut:

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

File konfigurasi

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

ossutil ls oss://examplebucket

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

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

Mengonfigurasi variabel lingkungan

Variabel lingkungan berikut didukung:

Opsi command-line

ossutil menyediakan berbagai opsi command-line, termasuk opsi command-line global. Opsi command-line memiliki prioritas tertinggi dan akan menimpa 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 RAM user

Jika aplikasi Anda berjalan di lingkungan yang aman, memerlukan akses jangka panjang ke OSS, dan tidak dapat merotasi kredensial secara berkala, Anda dapat menginisialisasi penyedia kredensial menggunakan Pasangan Kunci Akses (AccessKey ID dan AccessKey Secret) dari Akun Alibaba Cloud atau RAM user. Metode ini memerlukan pemeliharaan manual Pasangan Kunci Akses, 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 temporary

Jika aplikasi Anda memerlukan akses sementara ke OSS, Anda dapat menginisialisasi penyedia kredensial dengan kredensial keamanan sementara (AccessKey ID, AccessKey Secret, dan token keamanan) yang diperoleh dari Security Token Service (STS). Metode ini mengharuskan pemeliharaan token keamanan secara manual, sehingga meningkatkan risiko keamanan dan kompleksitas. Selain itu, Anda 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 terotorisasi ke OSS, misalnya untuk akses lintas Akun Alibaba Cloud, Anda dapat menggunakan RAMRoleARN guna menginisialisasi penyedia kredensial. Metode ini menggunakan token STS secara internal. Dengan menentukan ARN (Alibaba Cloud Resource Name) dari RAM role, alat kredensial akan memperoleh token STS dari layanan STS dan memanggil API AssumeRole untuk meminta token baru sebelum sesi berakhir. Selain itu, Anda dapat menetapkan nilai pada policy untuk membatasi RAM role pada kumpulan izin yang lebih kecil.

Buat file konfigurasi berikut dan simpan sebagai ~/.ossutilconfig. Konfigurasi ini tidak dapat diatur melalui variabel lingkungan atau opsi command-line.

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

Untuk melakukan kueri objek di bucket examplebucket, jalankan perintah berikut:

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

RAM role instans ECS

Jika aplikasi Anda berjalan pada instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes, sebaiknya gunakan ECSRAMRole untuk menginisialisasi penyedia kredensial. Metode ini menggunakan token STS dalam implementasi dasarnya dan memungkinkan Anda mengaitkan role dengan instans ECS, instans ECI, atau node pekerja Container Service for Kubernetes untuk me-refresh token STS secara otomatis di dalam instans. Cara ini menghilangkan kebutuhan untuk menyediakan AccessKey (AK) atau token STS serta menghapus risiko yang terkait dengan pemeliharaan manual. Untuk informasi selengkapnya tentang cara mendapatkan ECSRAMRole, lihat Membuat role.

Mode EcsRamRole

[default]
mode = EcsRamRole
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
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
# The ecsRoleName parameter is optional. If it is not set, the role is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

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

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

ARN role OIDC

Setelah Anda mengonfigurasi RAM role node pekerja di Container Service for Kubernetes, aplikasi dalam Pod pada node tersebut dapat memperoleh token STS untuk role yang terkait melalui layanan metadata, serupa dengan aplikasi pada instans ECS. Namun, jika aplikasi tidak tepercaya, seperti aplikasi pihak ketiga dengan kode sumber tertutup, dijalankan pada Kluster kontainer, Anda mungkin perlu mencegah aplikasi tersebut mengakses token STS dari RAM role node pekerja melalui layanan metadata. Untuk menjaga keamanan resource cloud sekaligus memungkinkan aplikasi tidak tepercaya memperoleh token STS secara aman dengan prinsip hak istimewa minimal tingkat aplikasi, gunakan fitur RRSA (RAM Roles for Service Account). Berdasarkan metode ini, Kluster kontainer Alibaba Cloud membuat dan memasang file token OIDC service account untuk setiap Pod aplikasi, lalu menyuntikkan informasi konfigurasi terkait ke dalam variabel lingkungan. Tool kredensial kemudian mengambil konfigurasi dari variabel lingkungan dan memanggil API AssumeRoleWithOIDC dari layanan STS untuk menukar token OIDC dengan token STS yang dikaitkan dengan role tersebut. Metode ini menghilangkan kebutuhan akan Access Key (AK) atau token STS manual, sehingga mengurangi risiko keamanan yang terkait dengan pemeliharaannya. Untuk informasi selengkapnya, lihat Mengonfigurasi 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 menggunakan variabel lingkungan atau opsi command-line.

[default]
mode = oidcRoleArn
# Specifies the ARN (Aliyun Resource Name) of the OIDC provider. The format is acs:ram::account-id:oidc-provider/provider-name.
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Specifies the file path where the OIDC token is stored.
OIDCTokenFilePath=OIDCTokenFilePath
# The ARN of the role to assume. The format is acs:ram::account-id:role/role-name.
roleArn=acs:ram::113511544585****:role/testoidc
# A custom role session name to distinguish different tokens.
roleSessionName= TestOidcAssumedRoleSession
region=ap-southeast-1

Jalankan perintah berikut untuk melakukan kueri 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 output standar (stdout).

Perintah eksternal dapat mengembalikan kredensial jangka panjang atau 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 command-line.

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

Jalankan perintah berikut untuk melakukan kueri objek di bucket examplebucket:

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

Akses anonim

Jika Anda hanya perlu mengakses resource 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 command-line

Beberapa perintah memerlukan parameter untuk menentukan target atau opsi. Berikan nilai yang diperlukan untuk perintah tersebut. Contoh:

ossutil ls --profile dev

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

FAQ

Kesalahan ossutil: region must be set in sign version 4

Penyebab: ID region tidak ditentukan saat mengonfigurasi ossutil 2.0.

Solusi: Untuk mencegah kesalahan ini, konfigurasikan parameter wajib berikut: AccessKey ID, AccessKey Secret, dan ID region. ID region diperlukan karena versi tanda tangan telah ditingkatkan ke V4. Untuk informasi selengkapnya tentang cara mendapatkan ID region, lihat Region dan endpoint.