Blok Ekle

İşlem, Append Block mevcut bir ek blobun sonuna yeni bir veri bloğu bağlar.

İşlem Append Block yalnızca blob olarak ayarlanmış x-ms-blob-typeAppendBlobolarak oluşturulmuşsa izin verilir. Append Block yalnızca 2015-02-21 veya daha sonraki sürümlerde desteklenmektedir.

İstek

Append Block isteğini aşağıdaki gibi oluşturabilirsiniz. HTTPS önerilir. myaccount değerini depolama hesabınızın adıyla değiştirin.

PUT yöntem isteği URI HTTP sürümü
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

Emülasyon depolama hizmetine karşı bir talep yaparken, emülatör ana bilgisayar adını ve Azure Blob Depolama portunu , ardından emülasyon edilmiş depolama hesabı adını belirtin 127.0.0.1:10000.

PUT yöntem isteği URI HTTP sürümü
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock HTTP/1.1

Daha fazla bilgi için bkz. Yerel Azure Depolama geliştirmesi için Azurite öykünücüsü kullanma.

URI parametreleri

Parametre Description
timeout Optional. Parametre timeout saniye cinsinden ifade edilir. Daha fazla bilgi için Azure Blob Storage işlemleri için zaman aşımını ayarlamak bölümünü inceleyebilirsiniz.

İstek başlıkları

Aşağıdaki tabloda gerekli ve isteğe bağlı istek üst bilgileri açıklanmaktadır.

İstek başlığı Description
Authorization Gerekli. Yetkilendirme düzenini, hesap adını ve imzayı belirtir. Daha fazla bilgi için Azure Storage'a Requests Authorize sayfasına bakınız.
Date veya x-ms-date Gerekli. İstek için Eşgüdümlü Evrensel Saati (UTC) belirtir. Daha fazla bilgi için bkz. azure depolamaistekleri yetkilendirme .
x-ms-version Tüm yetkili talepler için gereklidir. Bu istek için kullanılacak işlemin sürümünü belirtir. Daha fazla bilgi için bkz . Azure Depolama hizmetleri için sürüm oluşturma.
Content-Length Gerekli. Blok içeriğinin bayt cinsinden uzunluğu. Blok boyutu, 2022-11-02 ve sonraki sürümler için 100 MiB'den (önizleme) daha az veya eşit olmalıdır. Eski sürümlerdeki sınırlar için Açıklamalar bölümüne bakınız.

Uzunluk sağlanmadığında, işlem 411 (Uzunluk Gerekli) durum koduyla başarısız olur.
Content-MD5 Optional. Blok içeriğinin MD5 hash'i. Bu hash, taşıma sırasında blokun bütünlüğünü doğrulamak için kullanılır. Bu başlık belirtildiğinde, depolama hizmeti gelen içeriğin hash'ını bu başlık değeriyle karşılaştırır.

Bu MD5 hash'i blobla birlikte saklanmıyor.

İki hash eşleşmezse, işlem 400 (Kötü İstek) hata kodu ile başarısız olur.
x-ms-content-crc64 Optional. Ekleme bloğu içeriğinin CRC64 hash'i. Bu hash, taşıma sırasında ekleyici bloğun bütünlüğünü doğrulamak için kullanılır. Bu başlık belirtildiğinde, depolama hizmeti gelen içeriğin hash'ını bu başlık değeriyle karşılaştırır.

Bu CRC64 hash'ının blobla birlikte saklanmadığını unutmayın.

İki hash eşleşmezse, işlem 400 (Kötü İstek) hata kodu ile başarısız olur.

Eğer her ikisi Content-MD5 ve x-ms-content-crc64 başlıklar varsa, istek 400 hata kodu ile başarısız olur.

Bu başlık, 2019-02-02 veya sonraki sürümlerde desteklenmektedir.
x-ms-encryption-scope Optional. İstek içeriğini şifrelemek için kullanılacak şifreleme kapsamını gösterir. Bu başlık, 2019-02-02 veya sonraki sürümlerde desteklenmektedir.
x-ms-lease-id:<ID> Blob etkin bir kiraya sahipse gereklidir. Bu işlemi etkin kirası olan bir blobda gerçekleştirmek için bu üst bilgi için geçerli kira kimliğini belirtin.
x-ms-client-request-id Optional. Günlük kaydı yapılandırıldığında günlüklere kaydedilen 1 kibibayt (KiB) karakter sınırına sahip istemci tarafından oluşturulan, opak bir değer sağlar. İstemci tarafı etkinliklerini sunucunun aldığı isteklerle ilişkilendirmek için bu üst bilgiyi kullanmanızı kesinlikle öneririz. Daha fazla bilgi için bkz.
x-ms-blob-condition-maxsize Isteğe bağlı koşullu başlık. Ekleyici blob için izin verilen bayt cinsinden maksimum uzunluğu belirtir. Eğer işlem Append Block blobun bu sınırı aşmasına neden olursa veya blob boyutu bu başlıkta belirtilen değerden zaten büyükse, istek hata kodu 412 (Ön Koşul Başarısız Oldu) ile başarısız olur.
x-ms-blob-condition-appendpos Yalnızca işlem için Append Block kullanılan isteğe bağlı koşullu başlık. Karşılaştırmak için bayt ofsetini bir sayı, gösterir. Append Block yalnızca eklenmiş pozisyon bu sayıya eşitse başarılı olur. Eğer olmazsa, istek hata kodu 412 (Ön Koşul Başarısız Oldu) ile başarısız olur.

Bu işlem, API'nin yalnızca belirli bir koşul yerine getirildiğinde başarılı olmasını sağlamak için ek koşullu başlıkların kullanılmasını destekler. Daha fazla bilgi için bkz. Azure Blob Storage işlemleri için conditional headers belirtmek.

İstek başlıkları (müşteri tarafından sağlanan şifreleme anahtarları)

2019-02-02 sürümünden itibaren, müşteri tarafından sağlanan bir anahtarla bir blob şifreleme isteğinde aşağıdaki başlıkları belirtebilirsiniz. Müşteri tarafından sağlanan anahtarla (ve ilgili başlık setiyle şifreleme) isteğe bağlıdır.

İstek başlığı Description
x-ms-encryption-key Gerekli. Base64 kodlu AES-256 şifreleme anahtarı.
x-ms-encryption-key-sha256 Gerekli. Base64 kodlu SHA256 şifreleme anahtarının hash'i.
x-ms-encryption-algorithm: AES256 Gerekli. Şifreleme için kullanılacak algoritmayı belirler. Bu başlığın değeri olmalıdır AES256.

Talep başlıkları (yapılandırılmış gövde)

2025-01-05 sürümü itibarıyla, yapılandırılmış gövde formatından yararlanmak için talebe göre aşağıdaki başlıklar belirtilebilir.

İstek başlığı Description
Content-Length Gerekli. Kodlanmış talebin uzunluğu olmalıdır (sadece blok içeriğinin uzunluğu değil).

Başlığın değeri, kodlanmış isteğin beklenen uzunluğuyla eşleşmiyorsa, işlem hata kodu 400 (Kötü İstek) ile başarısız olur.
x-ms-structured-body Gerekli. Mesaj formatı yapılandırılmışsa dahil edilmelidir. Bu başlığın değeri, mesaj şeması versiyonu ve özelliklerini içerir.

Şu anda desteklenen XSM/1.0; properties=crc64tek değer , bu da isteğin kodlanmış mesajda crc64 kontrol toplamı segmentleri kullandığını gösterir. Değer bu değerle eşleşmezse, işlem hata kodu 400 (Kötü İstek) ile başarısız olur. Talep ayrıca istekte sağlanan içerik, belirli bir segment için sağlanan kontrol toplamıyla eşleşmiyorsa da başarısız olur.
x-ms-structured-content-length Gerekli. Mesaj formatı yapılandırılmışsa dahil edilmelidir. Bu başlığın değeri, blok içeriğinin uzunluğudur ve mesaj kodlaması nedeniyle her zaman başlık değerinden daha küçük Content-Length olacaktır.

Başlığın değeri, istekte verilen blok içeriğinin uzunluğuyla eşleşmiyorsa, işlem hata kodu 400 (Kötü İstek) ile başarısız olur.

İstek içeriği

İstek gövdesi blokun içeriğini içerir.

Numune isteği

Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock  HTTP/1.1  
  
Request Headers:  
x-ms-version: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

Yanıt

Yanıt bir HTTP durum kodu ve bir dizi yanıt üst bilgisi içerir.

Durum kodu

Başarılı bir işlem 201 (Oluşturuldu) durum kodunu döndürür.

Durum kodları hakkında bilgi için bkz. Durum ve hata kodları.

Yanıt başlıkları

Bu işlemin yanıtı aşağıdaki üst bilgileri içerir. Yanıt, ek standart HTTP başlıkları da içerebilir. Tüm standart başlıklar HTTP/1.1 protokol belirtimine uygundur.

Yanıt üst bilgisi Description
ETag Bir ETag değer içinde tırnak içinde bulunur. İstemci, değeri istek başlığını kullanarak koşullu PUT işlemler If-Match gerçekleştirebilir.
Last-Modified Blobun en son değiştirildiği tarih ve saat. Tarih biçimi RFC 1123'e uygundur. Daha fazla bilgi için, başlıklarda tarih-saat değerlerinin temsili bölümüne bakınız.

Blob üzerindeki herhangi bir yazma işlemi (blobun meta veri veya özelliklerindeki güncellemeler dahil) blobun son değiştirilme zamanını değiştirir.
Content-MD5 İstemcinin ileti içerik bütünlüğünü denetleyebilmesi için bu üst bilgi döndürülür. Bu başlığın değeri Blob Storage tarafından hesaplanır. İstek başlıklarında belirtilen aynı değer mutlaka aynı olmayabilir. 2019-02-02 veya daha sonraki sürümler için, bu başlık yalnızca istek bu başlığa sahip olduğunda döner.
x-ms-content-crc64 2019-02-02 veya daha sonraki sürümler için, istemcinin mesaj içeriği bütünlüğünü kontrol edebilmesi için bu başlık geri döner. Bu başlığın değeri Blob Storage tarafından hesaplanır. İstek başlıklarında belirtilen aynı değer mutlaka aynı olmayabilir.

Bu başlık, başlık istekte bulunmadığında Content-md5 geri döner.
x-ms-request-id Bu üst bilgi, yapılan isteği benzersiz olarak tanımlar ve isteğin sorunlarını gidermek için kullanılabilir.
x-ms-version İsteği çalıştırmak için kullanılan Blob Depolama sürümünü gösterir. Bu üst bilgi, 2009-09-19 ve sonraki sürümlere karşı yapılan istekler için döndürülür.
Date Yanıtın başlatıldığı saati gösteren UTC tarih/saat değeri. Hizmet bu değeri oluşturur.
x-ms-blob-append-offset Bu yanıt üst bilgisi yalnızca ekleme işlemleri için döndürülür. Bloğun işlendiği uzaklığı bayt cinsinden döndürür.
x-ms-blob-committed-block-count Blobda bulunan işlenen blokların sayısı. Bunu, daha kaç tane ekleyebileceğini kontrol etmek için kullanabilirsiniz.
x-ms-request-server-encrypted: true/false 2015-12-11 veya daha sonraki sürüm. Bu başlığın true değeri, isteğin içeriği belirtilen algoritma kullanılarak başarıyla şifrelenmişse ayarlanır. Aksi takdirde, değer olarak ayarlanır false.
x-ms-encryption-key-sha256 2019-02-02 veya daha sonraki sürüm. Bu başlık, istekte şifreleme için müşteri tarafından sağlanan bir anahtar kullanılmışsa geri döner. İstemci, verilen anahtarı kullanarak isteğin içeriğinin başarıyla şifrelendiğinden emin olabilir.
x-ms-encryption-scope 2019-02-02 veya daha sonraki sürüm. Bu başlık, istek şifreleme kapsamı kullanıyorsa döner. İstemci, şifreleme kapsamını kullanarak talebin içeriğinin başarıyla şifrelendiğinden emin olabilir.
x-ms-client-request-id İstekler ve karşılık gelen yanıtlarla ilgili sorunları gidermek için bu üst bilgiyi kullanabilirsiniz. Bu başlığın değeri, eğer talebe sahipse, başlığın değerine x-ms-client-request-id eşittir. Değer en fazla 1024 görünür ASCII karakterdir. Eğer x-ms-client-request-id başlık istekte yoksa, bu başlık yanıtta da yoktur.
x-ms-structured-body Eğer talep yapılandırılmış bir vücut talebi olarak işleniyorsa geri gönderilir. Bu başlığın değeri, talebe gönderilen değere eşittir ve şu anda bu değer olarak olmalıdır XSM/1.0; properties=crc64.

Örnek yanıt

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
Transfer-Encoding: chunked  
x-ms-content-crc64: 77uWZTolTHU  
Date: <date>  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
x-ms-blob-append-offset: 2097152  
x-ms-blob-committed–block-count: 1000

Authorization

Azure Depolama'da herhangi bir veri erişim işlemi çağrılırken yetkilendirme gereklidir. aşağıda açıklandığı gibi Append Block işlemini yetkileyebilirsiniz.

Önemli

Microsoft, Azure Depolama'ya yönelik istekleri yetkilendirmek için Yönetilen kimliklerle Microsoft Entra Id kullanılmasını önerir. Microsoft Entra ID, Paylaşılan Anahtar yetkilendirmesine kıyasla üstün güvenlik ve kullanım kolaylığı sağlar.

Azure Depolama, blob verilerine yönelik istekleri yetkilendirmek için Microsoft Entra Id kullanılmasını destekler. Microsoft Entra Id ile azure rol tabanlı erişim denetimini (Azure RBAC) kullanarak bir güvenlik sorumlusuna izin vekleyebilirsiniz. Güvenlik sorumlusu bir kullanıcı, grup, uygulama hizmet sorumlusu veya Azure yönetilen kimliği olabilir. OAuth 2.0 belirtecini döndürmek için güvenlik sorumlusunun kimliği Microsoft Entra Id tarafından doğrulanır. Daha sonra belirteç, Blob hizmetine karşı bir isteği yetkilendirmek için kullanılabilir.

Microsoft Entra Id kullanarak yetkilendirme hakkında daha fazla bilgi edinmek için bkz.Microsoft Entra Id kullanarak bloblara erişimi yetkilendirme .

Permissions

Aşağıda bir Microsoft Entra kullanıcısı, grubu, yönetilen kimliği veya hizmet sorumlusunun Append Block işlemini çağırması için gereken RBAC eylemi ve bu eylemi içeren en az ayrıcalıklı yerleşik Azure RBAC rolü verilmiştir:

Azure RBAC kullanarak rol atama hakkında daha fazla bilgi edinmek için bkz.

Açıklamalar

Append Block Mevcut bir ek blobun sonuna bir blok yükler. Çağrı sunucuda başarılı olduktan sonra veri bloğu hemen erişilebilir olur. Her ek blob için en fazla 50.000 ekleme izin verilir. Her blok farklı boyutlarda olabilir.

Aşağıdaki tablo, hizmet versiyonlarına göre izin verilen maksimum blok ve blob boyutlarını açıklar:

Hizmet sürümü Maksimum blok boyutu (via Append Block) Maksimum blob boyutu
2022-11-02 ve sonrası sürümler 100 MiB (Önizleme) Yaklaşık 4.75 TiB (100 MiB × 50.000 blok)
2022-11-02 tarihinden önceki sürümler 4 MiB Yaklaşık 195 gibibayt (GiB) (4 MiB × 50.000 blok)

Append Block ancak bu leke zaten varsa başarılı olur.

Kullanılarak Append Block yüklenen bloblar blok kimliklerini açığa çıkarmaz. Bir ek blob'a karşı Get Block List çağıramazsınız. Bunu yapmak bir hata ile sonuçlanır.

İstekte aşağıdaki isteğe bağlı, koşullu başlıkları belirtebilirsiniz:

  • x-ms-blob-condition-appendpos: Bu başlığı, istemcinin bloğu eklemeyi beklediği bir bayt ofsetine ayarlayabilirsiniz. İstek, yalnızca mevcut ofset istemcinin belirttiği ile eşleşirse başarılı olur. Aksi takdirde, istek 412 hata kodu (Ön Koşul Başarısız Oldu) ile başarısız olur.

    Tek bir yazar kullanan istemciler, ağ arızasına rağmen bir Append Block işlemin başarılı olup olmadığını belirlemek için bu başlığı kullanabilir.

  • x-ms-blob-condition-maxsize: İstemciler, bu başlığı kullanarak ekleme işlemlerinin blob boyutunu beklenen maksimum bayt boyutunun ötesine çıkarmamasını sağlayabilir. Koşul başarısız olursa, istek hata kodu 412 (Ön Koşul Başarısız Oldu) ile başarısız olur.

İzin verilen boyuttan büyük bir blok yüklemeye çalışırsanız, hizmet hata kodu 413'ü (Varlık Çok Büyük İstek) döndürür. Hizmet ayrıca yanıttaki hata hakkında bayt cinsinden izin verilen maksimum blok boyutu dahil olmak üzere ek bilgi de döndürür. 50.000'den fazla blok yüklemeye çalışırsanız, hizmet 409 hata kodu (Çatışma) döndürür.

Blob'un aktif bir kira sözleşmesi varsa, istemci blob'a blok yazabilmek için talebe geçerli bir kira kimliği belirtmelidir. İstemci bir kira kimliği belirtmezse veya geçersiz bir kira kimliği belirtirse, Blob Storage hata kodu 412'yi (Ön Koşul Başarısız Oldu) döndürür. İstemci bir kira kimliği belirtirse ama blobun aktif bir kiralaması yoksa, Blob Storage ayrıca 412 hata kodu döndürür.

Mevcut bir blok blobunu veya sayfa blobunu çağırırsanız Append Block , servis bir çakışma hatası döndürür. Var olmayan bir blob'u çağırırsanız Append Block , servis de hata döndürür.

Tekrarlanan veya gecikmiş eklemelerden kaçının

Tek bir yazar senaryosunda istemci, mevcut ofseti kontrol etmek için koşullu *x-ms-blob-condition-appendpos başlığı kullanarak tekrarlanan eklemeleri veya gecikmeli yazımları önleyebilir. İstemci ayrıca, koşullu olarak If-Matchkontrol ederek tekrarları veya gecikmeleri ETag önleyebilir.

Birden fazla yazar senaryosunda her istemci koşullu başlıklar kullanabilir, ancak bu performans için optimal olmayabilir. En yüksek eşzamanlı ek veri kapasitesi için, uygulamalar uygulama katmanında yedek ekleri ve gecikmeli eklemeleri işlemelidir. Örneğin, uygulama eklenen veriye dönem veya dizi numaraları ekleyebilir.

Billing

Fiyatlandırma istekleri, doğrudan Blob Depolama REST API'si aracılığıyla veya bir Azure Depolama istemci kitaplığından Blob Depolama API'lerini kullanan istemcilerden kaynaklanabilir. Bu istekler işlem başına ücret tahakkuk ettirir. İşlem türü, hesabın nasıl ücretlendirileceğini etkiler. Örneğin, okuma işlemleri yazma işlemlerinden farklı bir faturalama kategorisine tahakkuk eder. Aşağıdaki tabloda, depolama hesabı türüne göre istekler için Append Block faturalama kategorisi gösterilmektedir:

Operation Depolama hesabı türü Faturalama kategorisi
Blok Ekle Premium blok blob
Standart Genel Amaçlı Versiyon 2
Standart genel amaçlı v1		 Yazma işlemleri

Eklenti Blokları nesne düzeyinde katmanlamayı desteklemez, ancak erişim katmanlarını varsayılan hesap erişim seviyesi ayarından çıkarır ve buna göre faturalandırılır. Varsayılan hesap seviye ayarı hakkında daha fazla bilgi almak için Access tiers for blob data - Azure Storage sayfasına bakınız.

Belirtilen faturalama kategorisinin fiyatlandırması hakkında bilgi edinmek için bkz.

  • Last updated on