Blob Batch
Operasi ini Blob Batch
memungkinkan beberapa panggilan API disematkan ke dalam satu permintaan HTTP. API ini mendukung dua jenis subrequest: Atur Tingkat Blob untuk blob blok dan Hapus Blob. Respons yang dikembalikan oleh server untuk permintaan batch berisi hasil untuk setiap subrequest dalam batch. Permintaan dan respons batch menggunakan sintaks OData
spesifikasi pemrosesan batch, dengan modifikasi pada semantik. API ini tersedia mulai versi 2018-11-09.
Minta
Anda dapat membuat Blob Batch
permintaan sebagai berikut. HTTPS disarankan. Ganti myaccount dengan nama akun penyimpanan Anda.
Metode | Meminta URI | Versi HTTP |
---|---|---|
POST |
https://myaccount.blob.core.windows.net/?comp=batch https://myaccount.blob.core.windows.net/containername?restype=container&comp=batch |
HTTP/1.1 |
Parameter URI
Anda dapat menentukan parameter tambahan berikut pada URI permintaan.
Parameter | Deskripsi |
---|---|
timeout |
Opsional. Parameter batas waktu dinyatakan dalam hitungan detik, dengan nilai maksimum 120 detik. Untuk informasi selengkapnya, lihat Mengatur batas waktu untuk operasi Blob Storage. |
restype |
Opsional, versi 2020-04-08 dan yang lebih baru. Satu-satunya nilai yang restype didukung untuk parameter adalah container . Ketika parameter ini ditentukan, URI harus menyertakan nama kontainer. Setiap subrequest harus dilingkup ke kontainer yang sama. |
Header permintaan
Tabel berikut ini menjelaskan header permintaan yang diperlukan dan opsional.
Meminta kop | Deskripsi |
---|---|
Authorization |
Wajib diisi. Menentukan skema otorisasi, nama akun penyimpanan, dan tanda tangan. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage. |
Date atau x-ms-date |
Wajib diisi. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage. |
x-ms-version |
Diperlukan untuk semua permintaan yang diotorisasi. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Versi ini akan digunakan untuk semua subrequest. Untuk informasi selengkapnya, lihat Penerapan versi untuk layanan Azure Storage. |
Content-Length |
Wajib diisi. Panjang permintaan. |
Content-Type |
Wajib diisi. Nilai header ini harus multipart/mixed , dengan batas batch. Contoh nilai header: multipart/mixed; boundary=batch_a81786c8-e301-4e42-a729-a32ca24ae252 . |
x-ms-client-request-id |
Pilihan. Menyediakan nilai buram yang dihasilkan klien dengan batas karakter 1 kibibyte (KiB) yang dicatat dalam log saat pengelogan dikonfigurasi. Kami sangat menyarankan Anda menggunakan header ini untuk menghubungkan aktivitas sisi klien dengan permintaan yang diterima server. Untuk informasi selengkapnya, lihat Memantau Azure Blob Storage. |
Isi permintaan
Isi permintaan untuk batch blob berisi daftar semua subrequest. Format menggunakan sintaks OData
spesifikasi batch, dengan modifikasi pada semantik.
Isi permintaan dimulai dengan batas batch, diikuti oleh dua header wajib: Content-Type
header dengan nilai application/http
, dan Content-Transfer-Encoding
header dengan nilai binary
. Ini diikuti oleh header opsional Content-ID
, dengan nilai string untuk melacak setiap subrequest. Respons berisi Content-ID
header untuk setiap respons subkueri yang sesuai untuk digunakan untuk pelacakan.
Header permintaan ini diikuti oleh baris kosong wajib, lalu definisi untuk setiap subrequest. Isi setiap subrequest adalah permintaan HTTP lengkap dengan kata kerja, URL, header, dan isi yang diperlukan untuk permintaan tersebut. Perhatikan peringatan berikut:
- Subrequest tidak boleh memiliki
x-ms-version header
. Semua subrequest dijalankan dengan versi permintaan batch tingkat atas. - URL subkueri hanya boleh memiliki jalur URL (tanpa host).
- Setiap permintaan batch mendukung maksimum 256 subrequest.
- Semua subrequest harus memiliki jenis permintaan yang sama.
- Setiap subkueri diotorisasi secara terpisah, dengan informasi yang disediakan di subkueri.
- Setiap baris dalam isi permintaan harus diakhir dengan karakter\r\n .
Contoh permintaan
POST http://account.blob.core.windows.net/?comp=batch HTTP/1.1
Content-Type: multipart/mixed; boundary=batch_357de4f7-6d0b-4e02-8cd2-6361411a9525
x-ms-version: 2018-11-09
Authorization: SharedKey account:QvaoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Host: 127.0.0.1:10000
Content-Length: 1569
--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 0
DELETE /container0/blob0 HTTP/1.1
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT
Authorization: SharedKey account:G4jjBXA7LI/RnWKIOQ8i9xH4p76pAQ+4Fs4R1VxasaE=
Content-Length: 0
--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 1
DELETE /container1/blob1 HTTP/1.1
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT
Authorization: SharedKey account:IvCoYDQ+0VcaA/hKFjUmQmIxXv2RT3XwwTsOTHL39HI=
Content-Length: 0
--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525
Content-Type: application/http
Content-Transfer-Encoding: binary
Content-ID: 2
DELETE /container2/blob2 HTTP/1.1
x-ms-date: Thu, 14 Jun 2018 16:46:54 GMT
Authorization: SharedKey account:S37N2JTjcmOQVLHLbDmp2johz+KpTJvKhbVc4M7+UqI=
Content-Length: 0
--batch_357de4f7-6d0b-4e02-8cd2-6361411a9525--
Respons
Respons mencakup kode status HTTP dan sekumpulan header respons untuk permintaan batch tingkat atas. Respons juga mencakup informasi respons untuk semua sub-kuerinya.
Isi Respons
Respons batch adalah multipart/mixed
respons, yang berisi respons untuk setiap subkueri. Respons dipotong. Setiap subrespons dimulai dengan Content-Type: application/http
header . Header Content-ID
mengikuti, jika disediakan dalam permintaan. Ini diikuti oleh kode status respons HTTP, dan header respons untuk setiap subkueri.
Untuk informasi tentang header yang dikembalikan oleh setiap subkueri, lihat dokumentasi untuk operasi Hapus Blob dan Atur Tingkat Blob .
Respons sampel
HTTP/1.1 202 Accepted
Transfer-Encoding: chunked
Content-Type: multipart/mixed; boundary=batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed
x-ms-request-id: 778fdc83-801e-0000-62ff-033467000000
x-ms-version: 2018-11-09
409
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed
Content-Type: application/http
Content-ID: 0
HTTP/1.1 202 Accepted
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e284f
x-ms-version: 2018-11-09
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed
Content-Type: application/http
Content-ID: 1
HTTP/1.1 202 Accepted
x-ms-delete-type-permanent: true
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2851
x-ms-version: 2018-11-09
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed
Content-Type: application/http
Content-ID: 2
HTTP/1.1 404 The specified blob does not exist.
x-ms-error-code: BlobNotFound
x-ms-request-id: 778fdc83-801e-0000-62ff-0334671e2852
x-ms-version: 2018-11-09
Content-Length: 216
Content-Type: application/xml
<?xml version="1.0" encoding="utf-8"?>
<Error><Code>BlobNotFound</Code><Message>The specified blob does not exist.
RequestId:778fdc83-801e-0000-62ff-0334671e2852
Time:2018-06-14T16:46:54.6040685Z</Message></Error>
--batchresponse_66925647-d0cb-4109-b6d3-28efe3e1e5ed--
0
Kode status
Jika permintaan batch dibentuk dengan baik dan diotorisasi, maka operasi mengembalikan kode status 202 (Diterima). Setiap subkueri memiliki responsnya sendiri, tergantung pada hasil operasi. Status subkueri dikembalikan dalam isi respons.
Untuk informasi selengkapnya, lihat Kode status dan kesalahan.
Header respons
Respons untuk operasi ini mencakup header berikut. Respons juga dapat mencakup header HTTP standar tambahan. Semua header standar sesuai dengan spesifikasi protokol HTTP/1.1.
Authorization
Ketika restype=container
dihilangkan, Anda harus mengotorisasi permintaan batch induk dengan menggunakan kunci bersama. Anda dapat menggunakan kunci akses akun, tanda tangan akses bersama akun, atau Microsoft Entra. Detail untuk mekanisme otorisasi tertentu yang ditunjukkan di bawah ini.
Ketika restype=container
disertakan pada permintaan, Anda dapat mengotorisasi permintaan batch induk melalui kunci bersama atau Microsoft Entra. Anda juga dapat mengotorisasi dengan tanda tangan akses bersama yang ditandatangani oleh salah satu mekanisme otorisasi tersebut. Detail untuk mekanisme otorisasi tertentu yang ditunjukkan di bawah ini.
Setiap subkueri diotorisasi secara terpisah. Subrequest mendukung mekanisme otorisasi yang sama dengan yang didukung operasi saat bukan bagian dari operasi batch.
Penting
Microsoft merekomendasikan penggunaan Microsoft Entra ID dengan identitas terkelola untuk mengotorisasi permintaan ke Azure Storage. Microsoft Entra ID memberikan keamanan yang unggul dan kemudahan penggunaan dibandingkan dengan otorisasi Kunci Bersama.
Azure Storage mendukung penggunaan Microsoft Entra ID untuk mengotorisasi permintaan ke data blob. Dengan Microsoft Entra ID, Anda dapat menggunakan kontrol akses berbasis peran Azure (Azure RBAC) untuk memberikan izin kepada prinsip keamanan. Perwakilan keamanan mungkin pengguna, grup, perwakilan layanan aplikasi, atau identitas terkelola Azure. Perwakilan keamanan diautentikasi oleh Microsoft Entra ID untuk mengembalikan token OAuth 2.0. Token kemudian dapat digunakan untuk mengotorisasi permintaan terhadap Blob service.
Untuk mempelajari selengkapnya tentang otorisasi menggunakan Microsoft Entra ID, lihat Mengotorisasi akses ke blob menggunakan Microsoft Entra ID.
Izin
Tercantum di bawah ini adalah tindakan RBAC yang diperlukan untuk pengguna, grup, identitas terkelola, atau perwakilan layanan Microsoft Entra untuk membuat Blob Batch
permintaan induk, dan peran Azure RBAC bawaan yang paling tidak istimewa yang mencakup tindakan ini:
- Tindakan Azure RBAC:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Peran bawaan dengan hak istimewa paling sedikit:Kontributor Data Blob Penyimpanan
Untuk mempelajari selengkapnya tentang menetapkan peran menggunakan Azure RBAC, lihat Menetapkan peran Azure untuk akses ke data blob.
Billing
Permintaan Blob Batch
REST dihitung sebagai satu transaksi, dan setiap subkueri individu juga dihitung sebagai satu transaksi. Untuk mempelajari selengkapnya tentang penagihan untuk subrekueri individual, lihat dokumentasi untuk operasi Hapus Blob dan Atur Tingkat Blob .
Permintaan harga dapat berasal dari klien yang menggunakan API Blob Storage, baik langsung melalui BLob Storage REST API, atau dari pustaka klien Azure Storage. Permintaan ini mengumpulkan biaya per transaksi. Jenis transaksi memengaruhi bagaimana akun ditagih. Misalnya, membaca transaksi bertambah ke kategori penagihan yang berbeda dari transaksi tulis. Tabel berikut ini memperlihatkan kategori penagihan untuk Blob Batch
permintaan induk berdasarkan jenis akun penyimpanan:
Operasi | Jenis akun penyimpanan | Kategori penagihan |
---|---|---|
Blob Batch (Atur Tingkat Blob) | Objek besar biner blok premium Tujuan umum standar v2 |
Operasi lainnya |
Untuk mempelajari tentang harga untuk kategori penagihan yang ditentukan, lihat harga Azure Blob Storage.
Keterangan
Salah satu manfaat utama menggunakan permintaan batch adalah pengurangan jumlah koneksi yang harus dibuka klien. Perhatikan batasan berikut:
- Subrequest yang didukung dalam batch adalah
Set Blob Tier
(untuk blob blok) danDelete Blob
. - Hanya mendukung hingga 256 subrequest dalam satu batch. Ukuran isi untuk permintaan batch tidak boleh melebihi 4 MB.
- Permintaan batch kosong gagal dengan kode 400 (Permintaan Buruk).
- Tidak ada jaminan pada urutan eksekusi subkueri batch.
- Eksekusi subrequest Batch bukan atomik. Setiap subkueri berjalan secara independen.
- Setiap subkueri harus untuk sumber daya dalam akun penyimpanan yang sama. Satu permintaan batch tidak mendukung permintaan yang berjalan dari akun penyimpanan yang berbeda.
- Isi permintaan berlapis tidak didukung.
- Jika server gagal mengurai isi permintaan, seluruh batch gagal, dan tidak ada permintaan yang akan dijalankan.
- Perhatikan bahwa SAS Akun adalah satu-satunya jenis tanda tangan akses bersama yang didukung oleh
Blob Batch
, ketika batch tidak menggunakanrestype=container
.
Cakupan semua subrequest ke kontainer tertentu
Dimulai dengan REST versi 2020-04-08, Blob Batch
API mendukung subrequest pencakupan ke kontainer tertentu. Ketika URI permintaan menyertakan nama kontainer dan restype=container
parameter, maka setiap subkueri harus berlaku untuk kontainer yang sama. Jika nama kontainer yang ditentukan untuk subkueri tidak cocok dengan nama kontainer yang disediakan dalam URI, layanan mengembalikan kode kesalahan 400 (Permintaan Buruk).
Semua mekanisme otorisasi yang didukung untuk kontainer valid untuk Blob Batch
operasi yang dicakup ke kontainer. Setiap subrequest mengirimkan header otorisasi ke layanan.
Lihat juga
Mengotorisasi permintaan ke Status Azure Storagedan kode kesalahan kodekesalahan Blob StorageMengatur batas waktu untuk operasi Blob Storage