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 itu, kecuali jika permintaan tersebut anonim.

Versi layanan penyimpanan Azure saat ini adalah 2023-11-03, 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 2023-11-03 mencakup fitur-fitur berikut:

  • Tidak ada.

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 Microsoft Entra ID, teruskan x-ms-version header pada permintaan dengan versi layanan 2017-11-09 atau lebih tinggi. Untuk informasi selengkapnya, lihat Memanggil operasi penyimpanan dengan token OAuth di Otorisasi dengan Microsoft Entra ID.

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

  • Permintaan yang menggunakan tanda tangan akses bersama (SAS): Anda dapat menentukan dua opsi penerapan versi pada tanda tangan akses bersama. Header opsional api-version menunjukkan versi layanan mana yang akan digunakan untuk menjalankan operasi API. Parameter yang diperlukan SignedVersion (sv) menentukan versi layanan yang akan digunakan untuk mengotorisasi permintaan yang dibuat dengan SAS. api-version Jika header tidak ditentukan, nilai SignedVersion (sv) parameter 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 Microsoft Entra ID, Kunci Bersama, atau Shared Key Lite

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

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 yang valid x-ms-version , 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 x-ms-version header. Semua permintaan ke Blob Storage yang tidak menggunakan tanda tangan akses bersama harus menentukan x-ms-version header kecuali versi default telah ditetapkan, seperti yang dijelaskan di paragraf berikutnya.

  • Jika permintaan ke Blob Storage tidak memiliki x-ms-version header, 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 api-version kueri menentukan versi protokol REST yang akan digunakan untuk memproses permintaan yang dibuat dengan menggunakan SAS.

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

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

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

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

Tabel berikut menjelaskan skema penerapan versi yang digunakan oleh layanan untuk otorisasi dan untuk memanggil protokol REST saat SignedVersion parameter 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 sv parameter Versi yang ditentukan dalam sv parameter
Versi layanan penyimpanan yang valid dalam format XXXX-XX-XX Versi yang ditentukan dalam sv parameter Versi layanan penyimpanan yang valid XXXX-XX-XX

Contoh 1

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

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 api-version parameter .

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.

Catatan

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

Permintaan melalui akses anonim

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

Untuk akun penyimpanan tujuan umum

Jika permintaan anonim ke akun penyimpanan tujuan umum tidak menentukan x-ms-version header, dan versi default untuk layanan belum diatur dengan menggunakan Set Blob Service Properties, layanan menggunakan versi paling awal yang mungkin untuk memproses permintaan. Namun, jika kontainer dibuat publik dengan operasi ACL Atur Kontainer 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 x-ms-version header, dan versi default untuk layanan belum diatur dengan menggunakan Set Blob Service Properties, 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.

InvalidHeaderValue pesan kesalahan

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 teratasi. Jika masalah berlanjut, atau jika rekomendasi tidak layak, silakan buka tiket dukungan untuk membahas opsi lebih lanjut.

Lihat juga