Object Storage Service：antarmuka baris perintah ossutil 2.0

Integrasi cepat

Untuk mulai menggunakan antarmuka baris perintah ossutil 2.0, ikuti langkah-langkah berikut:

Konfigurasi ossutil

Untuk mencegah kegagalan operasi akibat konfigurasi yang tidak lengkap, Anda dapat menggunakan wizard perintah `ossutil config` untuk mengonfigurasi ID AccessKey, rahasia AccessKey, dan ID wilayah secara cepat. Untuk mengelola konfigurasi lanjutan, lihat Panduan konfigurasi untuk informasi tentang cara mengonfigurasi kredensial akses secara manual.

Contoh berikut menunjukkan cara menggunakan wizard konfigurasi untuk mengonfigurasi 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 tersebut telah 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 tersebut.

   Unduh file contoh `uploadFile.txt` dari bucket `examplebucket` ke folder lokal `localfolder`.

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

   Output berikut menunjukkan bahwa file tersebut telah diunduh ke folder lokal `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` telah 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 `uploadFile.txt` dari bucket `examplebucket`.

   ossutil rm oss://examplebucket/uploadFile.txt

   Output berikut menunjukkan bahwa `uploadFile.txt` telah dihapus dari bucket `examplebucket`.

   0.295530(s) elapsed

6. Hapus bucket `examplebucket`.

   ossutil rb oss://examplebucket

   Output berikut menunjukkan bahwa bucket `examplebucket` telah dihapus. 0,478659s elapsed

   0.478659(s) elapsed

Panduan konfigurasi

ossutil mendukung konfigurasi melalui file konfigurasi, variabel lingkungan, dan opsi baris perintah. Hal ini memberikan tingkat fleksibilitas yang tinggi.

Urutan prioritas konfigurasi

ossutil membaca konfigurasi 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 dengan opsi -c). Jika Anda menggunakan file konfigurasi default, Anda tidak perlu menentukan path file tersebut dan dapat langsung menjalankan perintah ossutil. Contoh:

ossutil ls oss://examplebucket

Jika Anda menggunakan path file konfigurasi kustom, seperti /path/yourconfig, Anda harus menentukan path tersebut dengan opsi -c. 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

Konfigurasi variabel lingkungan

Anda dapat mengonfigurasi variabel lingkungan dengan mengikuti langkah-langkah berikut.

Variabel lingkungan berikut dapat dikonfigurasi:

Konfigurasi opsi baris perintah

ossutil menyediakan berbagai opsi baris perintah, termasuk dukungan untuk 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"

Konfigurasi kredensial akses

Gunakan pasangan AccessKey Pengguna RAM

Jika aplikasi Anda berjalan di lingkungan yang aman dan stabil yang tidak rentan terhadap serangan eksternal, memerlukan akses jangka panjang ke OSS, dan tidak dapat memutar kredensial secara berkala, Anda dapat menginisialisasi penyedia kredensial dengan pasangan AccessKey (ID AccessKey dan rahasia AccessKey) dari akun Alibaba Cloud atau Pengguna RAM. Metode ini mengharuskan Anda untuk memelihara pasangan AccessKey secara manual, yang meningkatkan risiko keamanan dan kompleksitas 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

Gunakan token STS

Jika aplikasi Anda memerlukan akses sementara ke OSS, Anda dapat menginisialisasi penyedia kredensial dengan kredensial identitas sementara (ID AccessKey, rahasia AccessKey, dan Token Keamanan) yang diperoleh dari layanan STS. Metode ini mengharuskan Anda untuk memelihara token STS secara manual, yang meningkatkan risiko keamanan dan kompleksitas pemeliharaan. Selain itu, untuk mengakses OSS secara sementara beberapa kali, Anda harus memperbarui token STS secara manual.

[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

Gunakan RAMRoleARN

Jika aplikasi Anda memerlukan akses berwenang ke OSS, seperti akses lintas akun, Anda dapat menginisialisasi penyedia kredensial dengan RAMRoleARN. Metode ini berbasis token STS. Dengan menentukan Nama Sumber Daya Alibaba Cloud (ARN) dari peran RAM, alat kredensial meminta token STS dari layanan STS dan memanggil operasi AssumeRole untuk meminta token STS baru sebelum sesi saat ini berakhir. Anda juga dapat memberikan nilai ke parameter policy untuk membatasi peran RAM ke set izin yang lebih kecil.

Buat file konfigurasi berikut dan simpan sebagai ~/.ossutilconfig. Metode ini tidak didukung 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

Jalankan perintah berikut untuk mengkueri objek dalam bucket `examplebucket`.

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

Gunakan EcsRamRole

Jika aplikasi Anda berjalan di instance ECS, instance ECI, atau node pekerja Container Service for Kubernetes, kami menyarankan Anda menginisialisasi penyedia kredensial dengan EcsRamRole. Metode ini berbasis token STS. EcsRamRole memungkinkan Anda mengaitkan peran dengan instance ECS, instance ECI, atau node pekerja Container Service for Kubernetes untuk memperbarui token STS secara otomatis di dalam instance tersebut. Metode ini tidak memerlukan Anda untuk menyediakan pasangan AccessKey atau token STS, sehingga menghilangkan risiko pemeliharaan manual. Untuk informasi lebih lanjut tentang cara mendapatkan EcsRamRole, lihat CreateRole.

[default]
mode = EcsRamRole
# ecsRoleName is optional. If not set, it is automatically obtained.
ecsRoleName = EcsRamRoleOss 
region=ap-southeast-1

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

ossutil ls oss://examplebucket --mode EcsRamRole

Gunakan OIDCRoleARN

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 yang terkait melalui Metadata Server, mirip dengan aplikasi yang dideploy di instance ECS. Namun, jika Anda menerapkan aplikasi yang tidak tepercaya pada kluster tersebut, seperti aplikasi yang diajukan oleh pelanggan dengan kode yang belum diverifikasi, Anda mungkin tidak ingin aplikasi tersebut mengakses token STS dari peran RAM instance yang terkait dengan node pekerja. Untuk melindungi sumber daya cloud Anda sekaligus memungkinkan aplikasi yang tidak tepercaya ini memperoleh token STS yang diperlukan secara aman dan mencapai minimisasi izin tingkat aplikasi, Anda dapat menggunakan fitur RAM Roles for Service Accounts (RRSA). Metode ini berbasis token STS. Kluster container Alibaba Cloud membuat dan memasang file token OIDC akun layanan yang sesuai untuk pod aplikasi yang berbeda serta menyuntikkan informasi konfigurasi terkait ke dalam variabel lingkungan. Alat kredensial mengambil konfigurasi ini dari variabel lingkungan dan memanggil operasi `AssumeRoleWithOIDC` dari STS untuk menukar token OIDC dengan token STS untuk peran yang terikat. Metode ini menghilangkan risiko memelihara pasangan AccessKey atau token STS secara manual. Untuk informasi lebih lanjut, lihat Isolasi izin Pod berdasarkan RRSA.

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

[default]
mode = oidcRoleArn
# Specifies the Alibaba Cloud Resource Name (ARN) 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 for the OIDC token.
OIDCTokenFilePath=OIDCTokenFilePath
# Enter the ARN of the role to assume. The format is acs:ram::113511544585****:oidc-provider/TestOidcProvider.
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 mengkueri objek dalam bucket `examplebucket`.

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

Dapatkan kredensial dari proses eksternal

ossutil dapat menjalankan proses eksternal independen menggunakan perintah eksternal. Proses eksternal tersebut berjalan dan mengembalikan hasilnya ke ossutil melalui output standar. Anda dapat menggunakan proses eksternal untuk mendapatkan kredensial.

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. Anda tidak dapat mengonfigurasi pengaturan ini menggunakan variabel lingkungan atau opsi baris perintah.

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

Jalankan perintah berikut untuk mengkueri objek dalam bucket `examplebucket`:

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

Akses Anonim

Jika Anda hanya perlu mengakses sumber daya OSS yang memiliki izin baca-publik, 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 pembantu.

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

Dalam operasi baris perintah, beberapa perintah memerlukan parameter tambahan untuk menentukan target operasi atau mengatur opsi, sedangkan perintah lain tidak. Untuk perintah yang memerlukan parameter, Anda dapat memberikan nilai parameter yang sesuai untuk mencapai fungsionalitas yang diinginkan. Sebagai contoh:

ossutil ls --profile dev

Perintah ossutil ls --profile dev memungkinkan pengguna menentukan profil konfigurasi tertentu menggunakan nilai parameter dev. Opsi yang memerlukan parameter biasanya memerlukan spasi atau tanda sama dengan (`=`) untuk memisahkan nama opsi dari nilai parameternya, seperti --profile dev atau --profile=dev. Jika nilai parameter berisi spasi, Anda harus mengapit seluruh nilai tersebut dengan tanda kutip ganda untuk memastikan perintah diurai dengan benar, seperti --description "OSS bucket list".

FAQ

Saat saya menjalankan perintah ossutil, muncul error "region must be set in sign version 4"

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

Solusi: Untuk mencegah kegagalan operasi akibat item konfigurasi yang hilang saat menggunakan ossutil, pastikan Anda mengonfigurasi item dasar yang diperlukan: ID AccessKey, rahasia AccessKey, dan ID wilayah. ID wilayah sangat penting karena tanda tangan telah ditingkatkan ke V4, yang menjadikannya item wajib. Untuk informasi lebih lanjut tentang cara mendapatkan ID wilayah, lihat Wilayah dan titik akhir.