Letakkan Blok

Operasi ini Put Block membuat blok baru untuk diterapkan sebagai bagian dari blob.

Permohonan

Anda dapat membuat permintaan Put Block sebagai berikut. Kami menyarankan agar Anda menggunakan HTTPS. Ganti akun saya dengan nama akun penyimpanan Anda:

URI permintaan metode PUT Versi HTTP
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Permintaan layanan penyimpanan yang ditimulasi

Saat Anda membuat permintaan terhadap layanan penyimpanan yang diemulasi, tentukan nama host emulator dan port layanan Blob sebagai 127.0.0.1:10000, diikuti dengan nama akun penyimpanan yang diemulasi:

URI permintaan metode PUT Versi HTTP
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=block&blockid=id HTTP/1.1

Untuk informasi selengkapnya, lihat Menggunakan emulator Azurite untuk pengembangan Azure Storage lokal.

URI Parameter

Pengaturan Description
blockid Dibutuhkan. Nilai string Base64 valid yang mengidentifikasi blok. Sebelum dikodekan, string harus berukuran kurang dari atau sama dengan 64 byte.

Untuk blob yang ditentukan, panjang nilai untuk blockid parameter harus memiliki ukuran yang sama untuk setiap blok.

Catatan: String Base64 harus dikodekan URL.
timeout Optional. Parameter dinyatakan timeout dalam detik. Untuk informasi selengkapnya, lihat Mengatur batas waktu untuk operasi layanan Blob.

Tajuk permintaan

Header permintaan yang diperlukan dan opsional dijelaskan dalam tabel berikut:

Tajuk permintaan Description
Authorization Dibutuhkan. Menentukan skema otorisasi, nama akun, dan tanda tangan. Lihat Mengotorisasi permintaan ke Azure Storage untuk informasi selengkapnya.
Date atau x-ms-date Dibutuhkan. Menentukan Waktu Universal Terkoordinasi (UTC) untuk permintaan tersebut. Untuk informasi selengkapnya, lihat Mengotorisasi permintaan ke Azure Storage.
x-ms-version Diperlukan untuk semua permintaan resmi. Menentukan versi operasi yang akan digunakan untuk permintaan ini. Untuk informasi selengkapnya, lihat Penerapan Versi untuk Azure Storage Services.
Content-Length Dibutuhkan. Panjang konten blok dalam byte. Blok harus berukuran kurang dari atau sama dengan 4.000 mebibyte (MiB) untuk versi 2019-12-12 dan yang lebih baru. Lihat bagian Keterangan untuk batasan di versi yang lebih lama.

Ketika panjang tidak disediakan, operasi gagal dengan kode status 411 (Panjang Diperlukan).
Content-MD5 Optional. Hash MD5 dari konten blok. Hash ini digunakan untuk memverifikasi integritas blok selama transportasi. Saat header ini ditentukan, layanan penyimpanan membandingkan hash konten yang telah tiba dengan nilai header ini.

Catatan: Hash MD5 ini tidak disimpan dengan blob.

Jika kedua hash tidak cocok, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).
x-ms-content-crc64 Optional. Hash CRC64 dari konten blok. Hash ini digunakan untuk memverifikasi integritas blok selama transportasi. Saat header ini ditentukan, layanan penyimpanan membandingkan hash konten yang telah tiba dengan nilai header ini.

Catatan: Hash CRC64 ini tidak disimpan dengan blob.

Jika kedua hash tidak cocok, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).

Jika header Content-MD5 dan x-ms-content-crc64 ada, permintaan gagal dengan 400 (Permintaan Buruk).

Header ini didukung dalam versi 2019-02-02 dan yang lebih baru.
x-ms-encryption-scope Optional. Menunjukkan cakupan enkripsi yang akan digunakan untuk mengenkripsi konten permintaan. Header ini didukung dalam versi 2019-02-02 dan yang lebih baru.
x-ms-lease-id:<ID> Diperlukan jika blob memiliki sewa aktif. Untuk melakukan operasi ini pada blob dengan sewa aktif, tentukan ID sewa yang valid untuk header ini.
x-ms-client-request-id Optional. 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.

Header permintaan (kunci enkripsi yang disediakan pelanggan)

Pada versi 2019-02-02, header berikut dapat ditentukan pada permintaan untuk mengenkripsi blob dengan kunci yang disediakan pelanggan. Enkripsi dengan kunci yang disediakan pelanggan (dan kumpulan header yang sesuai) bersifat opsional.

Tajuk permintaan Description
x-ms-encryption-key Dibutuhkan. Kunci enkripsi AES-256 yang dikodekan Base64.
x-ms-encryption-key-sha256 Dibutuhkan. Hash SHA256 yang dikodekan Base64 dari kunci enkripsi.
x-ms-encryption-algorithm: AES256 Dibutuhkan. Menentukan algoritme yang akan digunakan untuk enkripsi. Nilai header ini harus .AES256

Header permintaan (isi terstruktur)

Pada versi 05-01-2025, header berikut dapat ditentukan pada permintaan untuk memanfaatkan format isi terstruktur.

Tajuk permintaan Description
Content-Length Dibutuhkan. Harus panjang permintaan yang dikodekan (tidak hanya panjang konten blok).

Jika nilai header tidak cocok dengan panjang yang diharapkan dari permintaan yang dikodekan, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).
x-ms-structured-body Dibutuhkan. Harus disertakan jika format pesan terstruktur. Nilai header ini berisi versi dan properti skema pesan.

Saat ini, satu-satunya nilai yang didukung adalah XSM/1.0; properties=crc64, yang menunjukkan permintaan menggunakan segmen checksum crc64 dalam pesan yang dikodekan. Jika nilainya tidak cocok dengan ini, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk). Permintaan juga akan gagal jika konten yang disediakan dalam permintaan tidak cocok dengan checksum yang disediakan untuk segmen tertentu dengan kode kesalahan 400 (Permintaan Buruk).
x-ms-structured-content-length Dibutuhkan. Harus disertakan jika format pesan terstruktur. Nilai header ini adalah panjang konten blok dan akan selalu lebih kecil dari Content-Length nilai header karena pengkodean pesan.

Jika nilai header tidak cocok dengan panjang konten blok yang disediakan dalam permintaan, operasi gagal dengan kode kesalahan 400 (Permintaan Buruk).

Isi dari permintaan

Isi permintaan berisi konten blok.

Permohonan sampel

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=block&blockid=AAAAAA%3D%3D HTTP/1.1  
  
Request Headers:  
x-ms-version: 2011-08-18  
x-ms-date: Sun, 25 Sep 2011 14:37:35 GMT  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048576

Jawaban

Respons mencakup kode status HTTP dan sekumpulan header respons.

Kode status

Operasi yang berhasil mengembalikan kode status 201 (Dibuat).

Untuk informasi tentang kode status, lihat Status dan Kode Kesalahan.

Tajuk 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.

Respons Header Description
Content-MD5 Dikembalikan sehingga klien dapat memeriksa integritas konten pesan. Nilai header ini dihitung oleh Blob Storage, dan belum tentu nilai yang sama yang ditentukan dalam header permintaan. Untuk versi 2019-02-02 dan yang lebih baru, header ini hanya dikembalikan ketika permintaan memiliki header ini.
x-ms-content-crc64 Untuk versi 2019-02-02 dan yang lebih baru, header ini dikembalikan sehingga klien dapat memeriksa integritas konten pesan. Nilai header ini dihitung oleh Blob Storage, dan belum tentu nilai yang sama yang ditentukan dalam header permintaan.

Header ini dikembalikan saat Content-md5 header tidak ada dalam permintaan.
x-ms-request-id Mengidentifikasi permintaan yang dibuat secara unik, dan Anda dapat menggunakannya untuk memecahkan masalah permintaan. Untuk informasi selengkapnya, lihat Memecahkan masalah operasi API.
x-ms-version Menunjukkan versi Blob Storage yang digunakan untuk mengeksekusi permintaan. Header ini dikembalikan untuk permintaan yang dibuat terhadap versi 2009-09-19 atau yang lebih baru.
Date Nilai tanggal/waktu UTC yang dihasilkan oleh layanan, yang menunjukkan kapan respons dimulai.
x-ms-request-server-encrypted: true/false Versi 2015-12-11 dan yang lebih baru. Nilai header ini diatur ke true jika konten permintaan berhasil dienkripsi dengan menggunakan algoritme yang ditentukan. Jika tidak, nilainya diatur ke false.
x-ms-encryption-key-sha256 Versi 2019-02-02 dan yang lebih baru. Header ini dikembalikan jika permintaan menggunakan kunci yang disediakan pelanggan untuk enkripsi, sehingga klien dapat memastikan bahwa konten permintaan berhasil dienkripsi dengan menggunakan kunci yang disediakan.
x-ms-encryption-scope Versi 2019-02-02 dan yang lebih baru. Header ini dikembalikan jika permintaan menggunakan cakupan enkripsi, sehingga klien dapat memastikan bahwa konten permintaan berhasil dienkripsi dengan menggunakan cakupan enkripsi.
x-ms-client-request-id Dapat digunakan untuk memecahkan masalah permintaan dan respons yang sesuai. Nilai header ini sama dengan nilai header x-ms-client-request-id jika ada dalam permintaan dan nilai berisi tidak lebih dari 1.024 karakter ASCII yang terlihat. Jika header x-ms-client-request-id tidak ada dalam permintaan, header tersebut tidak ada dalam respons.
x-ms-structured-body Dikembalikan jika permintaan diproses sebagai permintaan isi terstruktur. Nilai header ini sama dengan nilai yang dikirim dalam permintaan, yang saat ini harus .XSM/1.0; properties=crc64

Contoh tanggapan

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 23:47:09 GMT  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0

Authorization

Otorisasi diperlukan saat memanggil operasi akses data apa pun di Azure Storage. Anda dapat mengotorisasi operasi Put Block seperti yang dijelaskan di bawah ini.

Penting

Microsoft merekomendasikan penggunaan ID Microsoft Entra dengan identitas terkelola untuk mengotorisasi permintaan ke Azure Storage. MICROSOFT Entra ID menyediakan keamanan yang unggul dan kemudahan penggunaan dibandingkan dengan otorisasi Kunci Bersama.

Azure Storage mendukung penggunaan ID Microsoft Entra 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 mungkin 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 layanan Blob.

Untuk mempelajari selengkapnya tentang otorisasi menggunakan ID Microsoft Entra, lihat Mengotorisasi akses ke blob menggunakan ID Microsoft Entra.

Permissions

Tercantum di bawah ini adalah tindakan RBAC yang diperlukan untuk pengguna, grup, identitas terkelola, atau perwakilan layanan Microsoft Entra untuk memanggil operasi Put Block, dan peran Azure RBAC bawaan yang 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.

Komentar

Put Block mengunggah blok untuk disertakan di masa mendatang dalam blob blok. Setiap blok dalam blob blok dapat memiliki ukuran yang berbeda. Blob blok dapat menyertakan maksimum 50.000 blok yang diterapkan.

Tabel berikut menjelaskan ukuran blok dan blob maksimum yang diizinkan, berdasarkan versi layanan:

Versi layanan Ukuran blok maksimum (melalui)Put Block Ukuran blob maksimum (melalui Put Block List) Ukuran blob maksimum melalui operasi tulis tunggal (melalui Put Blob)
Versi 2019-12-12 dan yang lebih baru 4.000 MiB Sekitar 190,7 tebibyte (TiB) (4.000 MiB × 50.000 blok) 5.000 MiB
Versi 2016-05-31 hingga 2019-07-07 100 MiB Sekitar 4,75 TiB (100 MiB × 50.000 blok) 256 MiB
Versi lebih awal dari 31-05-2016 4 MiB Sekitar 195 gibibyte (GiB) (4 MiB × 50.000 blok) 64 MiB

Jumlah maksimum blok yang tidak diterapkan yang mungkin dikaitkan dengan blob adalah 100.000. Jika jumlah ini terlampaui, layanan mengembalikan kode status 409 (RequestEntityTooLargeBlockCountExceedsLimit).

Setelah mengunggah sekumpulan blok, Anda dapat membuat atau memperbarui blob di server dari kumpulan ini dengan memanggil operasi Put Block List . Setiap blok dalam kumpulan diidentifikasi oleh ID blok yang unik dalam blob tersebut. ID blok dicakup ke blob tertentu, sehingga blob yang berbeda dapat memiliki blok dengan ID yang sama.

Jika Anda memanggil Put Block blob yang belum ada, blob blok baru dibuat dengan panjang konten 0. Blob ini dihitung oleh List Blobs operasi jika include=uncommittedblobs opsi ditentukan. Blok atau blok yang Anda unggah tidak diterapkan sampai Anda memanggil Put Block List blob baru. Blob yang dibuat dengan cara ini dipertahankan di server selama seminggu. Jika Anda belum menambahkan lebih banyak blok atau blok yang diterapkan ke blob dalam jangka waktu tersebut, blob tersebut dikumpulkan sampah.

Blok yang telah berhasil diunggah dengan Put Block operasi tidak menjadi bagian dari blob hingga diterapkan dengan Put Block List. Sebelum Put Block List dipanggil untuk melakukan blob baru atau yang diperbarui, panggilan apa pun ke Get Blob mengembalikan konten blob tanpa penyertaan blok yang tidak diterapkan.

Jika Anda mengupload blok yang memiliki ID blok yang sama dengan blok lain yang belum diterapkan, blok terakhir yang diupload dengan ID tersebut akan diterapkan pada operasi berikutnya yang berhasil Put Block List .

Setelah Put Block List dipanggil, semua blok yang tidak diterapkan yang ditentukan dalam daftar blokir diterapkan sebagai bagian dari blob baru. Setiap blok yang tidak diterapkan yang tidak ditentukan dalam daftar blokir untuk blob adalah sampah yang dikumpulkan dan dihapus dari Blob Storage. Setiap blok yang tidak diterapkan juga dikumpulkan sampah jika tidak ada panggilan yang berhasil ke Put Block atau Put Block List pada blob yang sama dalam waktu seminggu setelah operasi terakhir yang berhasil Put Block . Jika Put Blob dipanggil pada blob, blok yang tidak diterapkan akan dikumpulkan sampah.

Jika blob memiliki sewa aktif, klien harus menentukan ID sewa yang valid pada permintaan untuk menulis blok ke blob. Jika klien tidak menentukan ID sewa atau menentukan ID sewa yang tidak valid, Blob Storage mengembalikan kode status 412 (Prasyarat Gagal). Jika klien menentukan ID sewa tetapi blob tidak memiliki sewa aktif, Blob Storage juga mengembalikan kode status 412 (Prasyarat Gagal).

Untuk blob tertentu, semua ID blok harus memiliki panjang yang sama. Jika blok diunggah dengan ID blok dengan panjang yang berbeda dari ID blok untuk blok yang tidak diterapkan, layanan akan menampilkan kode respons error 400 (Permintaan Buruk).

Jika Anda mencoba mengunggah blok yang lebih besar dari 4.000 MiB untuk versi 2019-12-12 atau yang lebih baru, lebih besar dari 100 MiB untuk versi 2016-05-31 atau yang lebih baru, atau lebih besar dari 4 MiB untuk versi yang lebih lama, layanan akan mengembalikan kode status 413 (Entitas Permintaan Terlalu Besar). Layanan ini juga mengembalikan informasi tambahan tentang kesalahan dalam respons, termasuk ukuran blok maksimum yang diizinkan, dalam byte.

Memanggil Put Block tidak memperbarui waktu modifikasi terakhir dari blob yang ada.

Memanggil Put Block blob halaman mengembalikan kesalahan.

Memanggil Put Block From URL blob tidak mengubah tingkat blob, tetapi memanggil archive blob akan mengembalikan kesalahan.

Billing

Permintaan harga dapat berasal dari klien yang menggunakan API Blob Storage, baik langsung melalui REST API Blob Storage, atau dari pustaka klien Azure Storage. Permintaan ini menimbulkan biaya per transaksi. Jenis transaksi memengaruhi bagaimana akun ditagih. Misalnya, transaksi baca bertambah ke kategori penagihan yang berbeda dari transaksi tulis. Tabel berikut menunjukkan kategori penagihan untuk Put Block permintaan berdasarkan jenis akun penyimpanan:

Operasi Jenis akun penyimpanan Kategori penagihan
Letakkan Blok Objek besar biner blok premium
Standar tujuan umum versi 2
Tujuan umum standar v1		 Operasi tulis1

1Put Block Operasi menulis blok ke penyimpanan sementara menggunakan tingkat akses default akun penyimpanan. Misalnya, jika Anda mengunggah blob ke tingkat arsip, operasi apa pun Put Block yang merupakan bagian dari unggahan akan dikenakan biaya sebagai operasi tulis berdasarkan tingkat akses default akun penyimpanan, bukan tingkat tujuan. Put Block List dan Put Blob operasi, bagaimanapun, dibebankan sebagai operasi tulis berdasarkan tingkat tujuan blob.

Untuk mempelajari tentang harga untuk kategori penagihan yang ditentukan, lihat Harga Azure Blob Storage.

Lihat juga

Mengotorisasi permintaan ke Azure Storage
Status dan kode galat
Kode kesalahan layanan blob
Atur batas waktu untuk operasi layanan Blob

  • Last updated on