Penerapan versi untuk Azure Storage
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 diperlukanSignedVersion (sv)
menentukan versi layanan yang akan digunakan untuk mengotorisasi permintaan yang dibuat dengan SAS.api-version
Jika header tidak ditentukan, nilaiSignedVersion (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 menentukanx-ms-version
header. Semua permintaan ke Blob Storage yang tidak menggunakan tanda tangan akses bersama harus menentukanx-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
, 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 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.