Blob Batch

  • Artikel

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 Opsional. 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 Azure Active Directory. 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 Azure Active Directory. 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.

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. Prinsip keamanan dapat berupa pengguna, grup, perwakilan layanan aplikasi, atau identitas terkelola Azure. Prinsip 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 bagi pengguna, grup, atau perwakilan layanan Microsoft Entra untuk membuat Blob Batch permintaan induk, dan peran Azure RBAC bawaan paling tidak istimewa yang mencakup tindakan ini:

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 subrequest individu juga dihitung sebagai satu transaksi. Untuk mempelajari selengkapnya tentang penagihan untuk subrequest 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 cara akun ditagih. Misalnya, transaksi baca 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:

  • Subkueri yang didukung dalam batch adalah Set Blob Tier (untuk blob blok) dan Delete 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 subrequest 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 menggunakan restype=container.

Cakupan semua subkueri ke kontainer tertentu

Dimulai dengan REST versi 2020-04-08, Blob Batch API mendukung subkueri cakupan 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 subrequest 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 tercakup dalam kontainer. Setiap subkueri mengirimkan header otorisasi ke layanan.

Lihat juga

Mengotorisasi permintaan ke Status Azure Storagedan kode kesalahanKode kesalahan Blob StorageMengatur batas waktu untuk operasi Blob Storage