Object Storage Service：antarmuka baris perintah ossutil 2.0

Integrasi Cepat

Alur berikut menjelaskan cara berintegrasi dengan antarmuka baris perintah ossutil 2.0:

Konfigurasikan ossutil

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

Contoh berikut menunjukkan cara menggunakan pasangan AccessKey dari pengguna RAM sebagai kredensial akses untuk menyelesaikan konfigurasi melalui wizard.

Jalankan perintah

1. Buat bucket.

   ossutil mb oss://examplebucket

   Keluaran 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

      Keluaran berikut menunjukkan 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. Unduh file.

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

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

   Keluaran berikut menunjukkan bahwa file 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 di bucket examplebucket.

   ossutil ls oss://examplebucket

   Keluaran berikut menunjukkan daftar file di bucket examplebucket.

   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

   Keluaran berikut menunjukkan bahwa file uploadFile.txt telah dihapus dari bucket examplebucket.

   0.295530(s) elapsed

6. Hapus bucket examplebucket.

   ossutil rb oss://examplebucket

   Keluaran berikut menunjukkan bahwa bucket examplebucket telah dihapus.

   0.478659(s) elapsed

Panduan konfigurasi

ossutil menawarkan metode konfigurasi yang fleksibel, mencakup file konfigurasi, variabel lingkungan, dan opsi baris perintah.

Prioritas konfigurasi

ossutil membaca konfigurasi 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. Jalur default untuk file tersebut adalah ~/.ossutilconfig. Namun, Anda juga dapat menentukan jalur kustom dengan menggunakan opsi -c. Jika Anda menggunakan file konfigurasi default, jalur file tidak perlu ditentukan, dan Anda dapat langsung menjalankan perintah ossutil. Berikut adalah contohnya:

ossutil ls oss://examplebucket

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

Konfigurasikan variabel lingkungan

Anda dapat mengonfigurasi variabel lingkungan dengan cara berikut.

Berikut ini adalah variabel lingkungan yang didukung saat ini:

Konfigurasikan opsi baris perintah

ossutil menyediakan beberapa opsi baris perintah yang mendukung konfigurasi opsi baris perintah global. Opsi ini memiliki prioritas tertinggi dan dapat menimpa parameter yang ditetapkan 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 dari Pengguna RAM

Jika aplikasi Anda beroperasi di lingkungan yang aman dan stabil, tidak rentan terhadap serangan eksternal, memerlukan akses jangka panjang ke OSS, serta tidak dapat memutar kredensial secara berkala, Anda dapat menginisialisasi penyedia kredensial menggunakan pasangan Kunci Akses (ID AccessKey dan Rahasia AccessKey) dari akun Alibaba Cloud atau Pengguna RAM. Metode ini mengharuskan pemeliharaan manual pasangan Kunci Akses, sehingga meningkatkan risiko keamanan dan kompleksitas pemeliharaan.

[default]
accessKeyID = yourAccessKeyID
accessKeySecret = yourAccessKeySecret
region=cn-hangzhou

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

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 kredensial akses sementara STS

Jika aplikasi Anda memerlukan akses sementara ke OSS, inisialisasikan penyedia kredensial menggunakan kredensial identitas sementara (ID AccessKey, Rahasia AccessKey, dan token Layanan Token Keamanan) yang diperoleh dari Layanan Token Keamanan (STS). Metode ini mengharuskan pemeliharaan manual token STS, yang dapat meningkatkan risiko keamanan dan kompleksitas pemeliharaan. Selain itu, untuk akses sementara berulang ke OSS, Anda perlu memperbarui token STS secara manual.

[default]
accessKeyID = yourSTSAccessKeyID
accessKeySecret = yourSTSAccessKeySecret
stsToken = yourSecurityToken
region=cn-hangzhou

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

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 terotorisasi ke Object Storage Service (OSS), seperti untuk akses lintas akun, Anda dapat menginisialisasi penyedia kredensial menggunakan ARN Peran RAM. Metode ini memanfaatkan token STS. Saat menentukan ARN Peran RAM, penyedia kredensial memanggil operasi AssumeRole untuk mendapatkan token STS. Penyedia secara otomatis meminta token baru sebelum Sesi saat ini kedaluwarsa. Anda juga dapat menentukan nilai untuk parameter policy guna membatasi lebih lanjut izin untuk sesi tersebut.

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig. Penggunaan variabel lingkungan atau opsi baris perintah untuk konfigurasi tidak didukung.

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

Jalankan perintah berikut untuk mengkueri objek di bucket examplebucket.

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

Gunakan EcsRamRole

Jika aplikasi Anda berjalan di instance ECS, instance ECI, atau node pekerja dari Container Service for Kubernetes, kami merekomendasikan untuk menginisialisasi penyedia kredensial menggunakan EcsRamRole. Metode ini didasarkan pada token STS. Dengan EcsRamRole, Anda dapat mengaitkan peran dengan instance ECS, instance ECI, atau node pekerja dari Container Service for Kubernetes untuk memperbarui token STS secara otomatis di dalam instans. Metode ini tidak memerlukan penyediaan Pasangan Kunci Akses atau token STS, sehingga menghilangkan risiko pemeliharaan manual. Untuk informasi lebih lanjut tentang cara mendapatkan EcsRamRole, lihat CreateRole.

[default]
mode = EcsRamRole
# ecsRoleName bersifat opsional. Jika tidak disetel, akan diperoleh secara otomatis.
ecsRoleName = EcsRamRoleOss 
region=cn-hangzhou

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

ossutil ls oss://examplebucket --mode EcsRamRole

Gunakan OIDCRoleARN

Setelah 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, serupa dengan aplikasi yang di-deploy di ECS. Namun, jika aplikasi yang tidak tepercaya di-deploy di kluster kontainer (misalnya, aplikasi yang dikirimkan oleh pelanggan dengan kode yang belum ditinjau), Anda mungkin ingin mencegahnya memperoleh token STS dari peran RAM instans yang terkait dengan node pekerja. Untuk melindungi sumber daya cloud Anda sambil tetap mengizinkan aplikasi yang tidak tepercaya ini memperoleh token STS secara aman dan mencapai isolasi izin tingkat aplikasi, Anda dapat menggunakan fitur RAM Roles for Service Accounts (RRSA). Metode ini diimplementasikan berdasarkan token STS. Kluster kontainer Alibaba Cloud membuat dan memasang file token OpenID Connect (OIDC) akun layanan yang sesuai untuk setiap Pod aplikasi serta menyuntikkan informasi konfigurasi relevan ke dalam variabel lingkungan. Alat kredensial mengambil konfigurasi dari variabel lingkungan dan memanggil operasi AssumeRoleWithOIDC dari layanan STS untuk menukar token OIDC dengan token STS dari peran yang terikat. Metode ini tidak memerlukan penyediaan pasangan Kunci Akses atau token STS, sehingga menghilangkan risiko pemeliharaan manual. Untuk informasi lebih lanjut, lihat Isolasi izin pod berdasarkan RRSA.

Buat file konfigurasi berikut dan simpan ke ~/.myossutilconfig. Penggunaan variabel lingkungan atau opsi baris perintah untuk konfigurasi tidak didukung.

[default]
mode = oidcRoleArn
# Menentukan ARN penyedia OIDC, dalam format acs:ram::account-id:oidc-provider/provider-name.
OIDCProviderArn=acs:ram::113511544585****:oidc-provider/TestOidcProvider
# Menentukan jalur file untuk token OIDC.
OIDCTokenFilePath=OIDCTokenFilePath
# Masukkan ARN peran untuk diasumsikan, dalam format acs:ram::113511544585****:oidc-provider/TestOidcProvider.
roleArn=acs:ram::113511544585****:role/testoidc
# Nama sesi peran kustom untuk membedakan token yang berbeda.
roleSessionName= TestOidcAssumedRoleSession
region=cn-hangzhou

Jalankan perintah berikut untuk mengkueri objek di bucket examplebucket.

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

Dapatkan kredensial dari proses eksternal

ossutil dapat memulai proses eksternal independen untuk mendapatkan kredensial. Proses eksternal ini berjalan dan mengembalikan kredensial ke ossutil melalui keluaran standar.

Kredensial yang dikembalikan oleh perintah eksternal dapat berupa kredensial jangka panjang atau sementara. Formatnya adalah sebagai berikut:

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

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

Buat file konfigurasi berikut dan simpan sebagai ~/.myossutilconfig. Konfigurasi melalui variabel lingkungan atau opsi baris perintah tidak didukung.

[default]
mode = Process
credentialProcess = user-cmd
region=cn-hangzhou

Jalankan perintah berikut untuk mengkueri objek di bucket examplebucket.

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

Akses anonim

Jika Anda hanya perlu mengakses sumber daya OSS yang bersifat baca-publik, Anda dapat menggunakan akses anonim tanpa perlu menyediakan kredensial apa pun.

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

Referensi Perintah

ossutil menyediakan tiga jenis perintah: perintah tingkat lanjut, 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 ossutil memerlukan parameter tambahan untuk menentukan objek target atau mengatur opsi. Untuk perintah ini, Anda dapat memberikan nilai parameter guna mencapai fungsi yang diinginkan. Contohnya:

ossutil ls --profile dev

Perintah ossutil ls --profile dev menggunakan parameter --profile untuk menentukan profil konfigurasi bernama dev. Opsi dan nilai parameternya biasanya dipisahkan oleh spasi atau tanda sama dengan (=), seperti --profile dev atau --profile=dev. Jika nilai parameter berisi spasi, seluruh nilai harus diapit dengan tanda kutip dua agar perintah diurai dengan benar, seperti --description "OSS bucket list".

FAQ

Saat menjalankan perintah ossutil, saya mendapatkan kesalahan "region must be set in sign version 4"

Penyebab: ID Wilayah tidak dikonfigurasi saat menyiapkan ossutil 2.0.

Solusi: Untuk menghindari kegagalan operasi akibat item konfigurasi yang tidak lengkap saat menggunakan ossutil, pastikan Anda telah mengonfigurasi item dasar yang diperlukan, yaitu ID AccessKey, rahasia AccessKey, dan ID Wilayah. ID Wilayah merupakan item wajib karena versi tanda tangan telah ditingkatkan ke V4. Untuk informasi lebih lanjut tentang cara mendapatkan ID Wilayah, lihat Wilayah dan titik akhir OSS.