Bagikan melalui

Penerapan versi untuk Azure Storage

  • Artikel

Azure Storage mendukung beberapa versi. Untuk membuat permintaan terhadap layanan penyimpanan, Anda harus menentukan versi yang ingin Anda gunakan untuk operasi tersebut, kecuali permintaannya anonim.

Versi layanan penyimpanan Azure saat ini adalah 2024-11-04, dan kami sarankan Anda menggunakannya jika memungkinkan. Untuk daftar semua versi lain yang didukung, dan untuk informasi tentang menggunakan setiap versi, lihat versi layanan Azure Storage Sebelumnya.

Versi layanan 2024-11-04 mencakup fitur-fitur berikut:

  • Dukungan untuk autentikasi berbasis token untuk semua API sarana data dalam layanan file. Untuk informasi selengkapnya, lihat Otorisasi dengan MICROSOFT Entra ID.
  • Dukungan untuk bursting berbayar pada akun berbagi file premium. Fitur ini dapat diaktifkan dengan Buat Berbagi dan Atur Properti Berbagi API.
  • Dukungan untuk format biner saat mendapatkan dan mengatur izin file di layanan file. Untuk informasi selengkapnya, lihat Membuat Izin dan Dapatkan Izin

Tentukan versi layanan dalam permintaan

Cara Anda menentukan versi layanan penyimpanan yang akan digunakan untuk permintaan terkait dengan bagaimana permintaan tersebut diotorisasi. Bagian berikut menjelaskan opsi otorisasi dan bagaimana versi layanan ditentukan untuk masing-masing opsi.

  • Permintaan yang menggunakan token OAuth 2.0 dari Microsoft Entra: Untuk mengotorisasi permintaan dengan ID Microsoft Entra, berikan header x-ms-version pada permintaan dengan versi layanan 2017-11-09 atau yang lebih tinggi. Untuk informasi selengkapnya, lihat operasi penyimpanan Panggilan dengan token OAuth di Otorisasi dengan ID Microsoft Entra.

  • Permintaan yang menggunakan Kunci Bersama atau Kunci Bersama Lite: Untuk mengotorisasi permintaan dengan Kunci Bersama atau Shared Key Lite, teruskan header x-ms-version pada permintaan. Dalam kasus Azure Blob Storage, Anda dapat menentukan versi default untuk semua permintaan dengan memanggil Mengatur Properti Blob Service.

  • Permintaan yang menggunakan tanda tangan akses bersama (SAS): Anda dapat menentukan dua opsi penerapan versi pada tanda tangan akses bersama. Header api-version opsional menunjukkan versi layanan mana yang akan digunakan untuk menjalankan operasi API. Parameter SignedVersion (sv) yang diperlukan menentukan versi layanan yang akan digunakan untuk mengotorisasi permintaan yang dibuat dengan SAS. Jika header api-version tidak ditentukan, nilai parameter SignedVersion (sv) juga menunjukkan versi yang akan digunakan untuk menjalankan operasi API.

  • Permintaan yang menggunakan akses anonim: Dalam kasus akses anonim terhadap Blob Storage, tidak ada versi yang diteruskan. Heuristik untuk menentukan versi mana yang akan digunakan untuk permintaan dijelaskan di bagian berikutnya.

Mengotorisasi permintaan dengan menggunakan ID Microsoft Entra, Kunci Bersama, atau Shared Key Lite

Untuk mengotorisasi permintaan dengan ID Microsoft Entra, Kunci Bersama, atau Shared Key Lite, tentukan header x-ms-version pada permintaan. Nilai header permintaan x-ms-version harus ditentukan dalam format YYYY-MM-DD. Misalnya:

Request Headers:  
x-ms-version: 2020-04-08

Aturan berikut menjelaskan bagaimana permintaan ini dievaluasi untuk menentukan versi mana yang akan digunakan untuk memproses permintaan.

  • Jika permintaan memiliki header x-ms-version yang valid, layanan penyimpanan menggunakan versi yang ditentukan. Semua permintaan ke Azure Table Storage dan Azure Queue Storage yang tidak menggunakan tanda tangan akses bersama harus menentukan header x-ms-version. Semua permintaan ke Blob Storage yang tidak menggunakan tanda tangan akses bersama harus menentukan header x-ms-version kecuali versi default telah ditetapkan, seperti yang dijelaskan di paragraf berikutnya.

  • Jika permintaan ke Blob Storage tidak memiliki header x-ms-version, tetapi pemilik akun telah mengatur versi default dengan menggunakan operasi Set Blob Service Properties, versi default yang ditentukan digunakan sebagai versi untuk permintaan.

Mengotorisasi permintaan dengan menggunakan tanda tangan akses bersama

Tanda tangan akses bersama (SAS) yang dihasilkan dengan menggunakan versi 2014-02-14 atau yang lebih baru mendukung dua opsi penerapan versi:

  • Parameter kueri api-version menentukan versi protokol REST yang akan digunakan untuk memproses permintaan yang dibuat dengan menggunakan SAS.

  • Parameter kueri SignedVersion (sv) menentukan versi SAS yang akan digunakan untuk otorisasi.

Parameter kueri SignedVersion digunakan untuk otorisasi saat klien membuat permintaan dengan menggunakan SAS. Parameter otorisasi seperti si, sr, sp, sig, st, se, tn, spk, srk, epk, dan erk semuanya ditafsirkan dengan menggunakan versi yang ditentukan.

Parameter protokol REST seperti rscc, rscd, rsce, rscl, dan rsct diberlakukan dengan menggunakan versi yang disediakan di header parameter api-version. Jika header api-version tidak ditentukan, versi layanan yang disediakan untuk SignedVersion digunakan.

Parameter api-version bukan bagian dari string-to-sign di header otorisasi, seperti yang dijelaskan di Membuat layanan SAS.

Tabel berikut menjelaskan skema penerapan versi yang digunakan oleh layanan untuk otorisasi dan untuk memanggil protokol REST saat parameter SignedVersion diatur ke versi 2014-02-14 atau yang lebih baru.

Nilai parameter versi api Versi yang digunakan untuk otorisasi Versi yang digunakan untuk perilaku protokol
Tidak ditentukan Versi yang ditentukan dalam parameter sv Versi yang ditentukan dalam parameter sv
Versi layanan penyimpanan yang valid dalam format XXXX-XX-XX Versi yang ditentukan dalam parameter sv Layanan penyimpanan yang valid versi XXXX-XX-XX

Contoh 1

Contoh permintaan berikut memanggil Daftar Blob dengan sv=2015-04-05, dan tanpa parameter api-version.

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d

Dalam hal ini, layanan mengautentikasi dan mengotorisasi permintaan dengan menggunakan versi 2015-04-05, dan menjalankan operasi dengan menggunakan versi 2015-04-05.

Contoh 2

Contoh permintaan berikut memanggil Daftar Blob dengan sv=2015-04-05 dan dengan parameter api-version.

https://myaccount.blob.core.windows.net/mycontainer?restype=container&comp=list&sv=2015-04-05&si=readpolicy&sig=a39 %2BYozJhGp6miujGymjRpN8tsrQfLo9Z3i8IRyIpnQ%3d&api-version=2012-02-12

Di sini, layanan mengotorisasi permintaan dengan menggunakan versi 2015-04-05, dan menjalankan operasi dengan menggunakan versi 2012-02-12.

Nota

Pustaka klien .NET Storage selalu mengatur versi protokol REST (dalam parameter api-version) ke versi yang menjadi dasarnya.

Permintaan melalui akses anonim

Permintaan yang dibuat melalui akses anonim ditangani secara berbeda, tergantung pada jenis akun penyimpanan yang mereka buat.

Untuk akun penyimpanan tujuan umum

Jika permintaan anonim ke akun penyimpanan tujuan umum tidak menentukan header x-ms-version, dan versi default untuk layanan belum ditetapkan dengan menggunakan Atur Properti Layanan Blob, layanan menggunakan versi paling awal yang mungkin untuk memproses permintaan. Namun, jika kontainer dibuat publik dengan operasi Set Container ACL yang dilakukan dengan menggunakan versi 2009-09-19 atau yang lebih baru, permintaan diproses dengan menggunakan versi 2009-09-19.

Untuk akun Blob Storage

Jika permintaan anonim ke akun Blob Storage tidak menentukan header x-ms-version, dan versi default untuk layanan belum diatur dengan menggunakan Atur Properti Blob Service, layanan menggunakan versi paling awal yang mungkin untuk memproses permintaan. Untuk akun Blob Storage, versi paling awal yang mungkin adalah 2014-02-14.

Masalah yang diketahui

Bagian ini merinci masalah yang diketahui untuk REST API Azure Storage.

pesan kesalahan InvalidHeaderValue

Dalam skenario yang jarang terjadi, aplikasi yang melakukan panggilan REST API langsung dapat menerima pesan kesalahan InvalidHeaderValue. Kesalahan terlihat mirip dengan sampel berikut:

HTTP/1.1 400 The value for one of the HTTP headers is not in the correct format.
Content-Length: 328
Content-Type: application/xml
Server: Microsoft-HTTPAPI/2.0
x-ms-request-id: <REMOVED>
Date: Fri, 19 May 2023 17:10:33 GMT
 
<?xml version="1.0" encoding="utf-8"?><Error><Code>InvalidHeaderValue</Code><Message>The value for one of the HTTP headers is not in the correct format.
RequestId:<REMOVED>
Time:2023-05-19T17:10:34.2972651Z</Message><HeaderName>x-ms-version</HeaderName><HeaderValue>yyyy-mm-dd</HeaderValue></Error>

Disarankan agar Anda menggunakan versi REST API sebelumnya untuk melihat apakah masalah diselesaikan. Jika masalah berlanjut, atau jika rekomendasi tidak layak, silakan membuka tiket dukungan untuk membahas opsi lebih lanjut.

Lihat juga