Ekleme Bloğu

  • Makale

bu Append Block işlem, mevcut ekleme blobunun sonuna yeni bir veri bloğu işler.

İşleme Append Block yalnızca blob ile x-ms-blob-typeAppendBloboluşturulduysa izin verilir. Append Block yalnızca 2015-02-21 veya sonraki bir sürümde desteklenir.

İstek

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

PUT yöntemi istek URI'si HTTP sürümü
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

Öykünülmüş depolama hizmetine yönelik istekte bulunurken öykünücü ana bilgisayar adını ve Azure Blob Depolama bağlantı noktasını olarak 127.0.0.1:10000ve ardından öykünülen depolama hesabı adını belirtin.

PUT yöntemi istek URI'si 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 Açıklama
timeout İsteğe bağlı. timeout parametresi saniye cinsinden ifade edilir. Daha fazla bilgi için bkz. Azure Blob Depolama işlemleri için zaman aşımlarını ayarlama.

İstek üst bilgileri

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

İstek üst bilgisi Açıklama
Authorization Gereklidir. Yetkilendirme düzenini, hesap adını ve imzayı belirtir. Daha fazla bilgi için bkz. Azure Depolama isteklerini yetkilendirme .
Date veya x-ms-date Gereklidir. İstek için Eşgüdümlü Evrensel Saat (UTC) biçimini belirtir. Daha fazla bilgi için bkz. Azure Depolama'ya istekleri yetkilendirme.
x-ms-version Tüm yetkili istekler 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 Gereklidir. Blok içeriğinin bayt cinsinden uzunluğu. Blok boyutu, sürüm 2022-11-02 ve üzeri için boyut olarak 100 MiB'den küçük veya buna eşit olmalıdır. Eski sürümlerdeki sınırlar için Açıklamalar bölümüne bakın.

Uzunluk sağlanmadığında işlem 411 (Uzunluk Gerekli) durum koduyla başarısız olur.
Content-MD5 İsteğe bağlı. Blok içeriğinin MD5 karması. Bu karma, taşıma sırasında bloğun bütünlüğünü doğrulamak için kullanılır. Bu üst bilgi belirtildiğinde, depolama hizmeti bu üst bilgi değeriyle gelen içeriğin karmasıyla karşılaştırılır.

Bu MD5 karması blob ile depolanmaz.

İki karma eşleşmezse işlem 400 (Hatalı İstek) hata koduyla başarısız olur.
x-ms-content-crc64 İsteğe bağlı. Ekleme bloğu içeriğinin CRC64 karması. Bu karma, taşıma sırasında ekleme bloğunun bütünlüğünü doğrulamak için kullanılır. Bu üst bilgi belirtildiğinde, depolama hizmeti bu üst bilgi değeriyle gelen içeriğin karmasıyla karşılaştırılır.

Bu CRC64 karması blob ile depolanmaz.

İki karma eşleşmezse işlem 400 (Hatalı İstek) hata koduyla başarısız olur.

Hem hem de Content-MD5x-ms-content-crc64 üst bilgiler varsa istek 400 hata koduyla başarısız olur.

Bu üst bilgi 2019-02-02 veya sonraki sürümlerde desteklenir.
x-ms-encryption-scope İsteğe bağlı. İstek içeriğini şifrelemek için kullanılacak şifreleme kapsamını gösterir. Bu üst bilgi 2019-02-02 veya sonraki sürümlerde desteklenir.
x-ms-lease-id:<ID> Blob etkin bir kiraya sahipse gereklidir. Bu işlemi etkin kiralaması olan bir blob üzerinde gerçekleştirmek için bu üst bilgi için geçerli kira kimliğini belirtin.
x-ms-client-request-id İsteğe bağlı. Günlüğe kaydetme yapılandırıldığında günlüklere kaydedilen 1 kibibayt (KiB) karakter sınırıyla istemci tarafından oluşturulan, opak bir değer sağlar. İstemci tarafı etkinlikleriyle sunucunun aldığı istekler arasında bağıntı sağlamak için bu üst bilgiyi kullanmanızı kesinlikle öneririz. Daha fazla bilgi için bkz. İzleme Azure Blob Depolama.
x-ms-blob-condition-maxsize İsteğe bağlı koşullu üst bilgi. Ekleme blobu için izin verilen bayt cinsinden uzunluk üst sınırını belirtir. İşlem blob'un Append Block bu sınırı aşmasına neden oluyorsa veya blob boyutu bu üst bilgide belirtilen değerden daha büyükse istek 412 (Önkoşul Başarısız Oldu) hata koduyla başarısız olur.
x-ms-blob-condition-appendpos İsteğe bağlı koşullu üst bilgi, yalnızca işlem için Append Block kullanılır. Sayı, karşılaştırılan bayt uzaklığını gösterir. Append Block yalnızca ekleme konumu bu sayıya eşitse başarılı olur. Aksi takdirde istek 412 (Önkoşul Başarısız Oldu) hata koduyla başarısız olur.

Bu işlem, API'nin yalnızca belirtilen bir koşul karşılandığında başarılı olmasını sağlamak için ek koşullu üst bilgiler kullanımını destekler. Daha fazla bilgi için bkz. Azure Blob Depolama işlemleri için koşullu üst bilgileri belirtme.

İstek üst bilgileri (müşteri tarafından sağlanan şifreleme anahtarları)

2019-02-02 sürümünden başlayarak, istekte müşteri tarafından sağlanan bir anahtarla bir blobu şifrelemek için aşağıdaki üst bilgileri belirtebilirsiniz. Müşteri tarafından sağlanan anahtarla (ve ilgili üst bilgi kümesiyle) şifreleme isteğe bağlıdır.

İstek üst bilgisi Açıklama
x-ms-encryption-key Gereklidir. Base64 kodlamalı AES-256 şifreleme anahtarı.
x-ms-encryption-key-sha256 Gereklidir. Şifreleme anahtarının Base64 kodlamalı SHA256 karması.
x-ms-encryption-algorithm: AES256 Gereklidir. Şifreleme için kullanılacak algoritmayı belirtir. Bu üst bilginin değeri olmalıdır AES256.

İstek gövdesi

İstek gövdesi, bloğun içeriğini içerir.

Örnek istek

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 üst bilgileri

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

Yanıt üst bilgisi Description
ETag tırnak ETag içinde bir değer içerir. İstemci, istek üst bilgisini kullanarak If-Match koşullu PUT işlemler gerçekleştirmek için değerini kullanabilir.
Last-Modified Blob'un son değiştirildiği tarih ve saat. Tarih biçimi RFC 1123'e göredir. Daha fazla bilgi için bkz . Üst bilgilerde tarih-saat değerlerinin gösterimi.

Blob üzerindeki herhangi bir yazma işlemi (blobun meta verileri veya özelliklerindeki güncelleştirmeler dahil) blobun son değiştirme 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 üst bilginin değeri Blob Depolama tarafından hesaplanır. İstek üst bilgilerinde belirtilen değerle aynı olmayabilir. 2019-02-02 veya sonraki sürümler için bu üst bilgi yalnızca istekte bu üst bilgi olduğunda döndürülür.
x-ms-content-crc64 İstemcinin ileti içeriği bütünlüğünü denetleyebilmesi için 2019-02-02 veya sonraki sürümler için bu üst bilgi döndürülür. Bu üst bilginin değeri Blob Depolama tarafından hesaplanır. İstek üst bilgilerinde belirtilen değerle aynı olmayabilir.

Üst bilgi istekte mevcut olmadığında Content-md5 bu üst bilgi döndürülür.
x-ms-request-id Bu üst bilgi, yapılan isteği benzersiz olarak tanımlar ve istek 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ümlerde 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ı. Daha kaç ekleme yapılabilmesini denetlemek için bunu kullanabilirsiniz.
x-ms-request-server-encrypted: true/false Sürüm 2015-12-11 veya üzeri. İsteğin içeriği belirtilen algoritma kullanılarak başarıyla şifrelenirse bu üst bilginin değeri olarak ayarlanır true . Aksi takdirde, değer olarak falseayarlanır.
x-ms-encryption-key-sha256 Sürüm 2019-02-02 veya üzeri. İstek şifreleme için müşteri tarafından sağlanan bir anahtar kullandıysa bu üst bilgi döndürülür. İstemci daha sonra sağlanan anahtarı kullanarak isteğin içeriğinin başarıyla şifrelenmesini sağlayabilir.
x-ms-encryption-scope Sürüm 2019-02-02 veya üzeri. İstek bir şifreleme kapsamı kullandıysa bu üst bilgi döndürülür. İstemci daha sonra şifreleme kapsamı kullanılarak isteğin içeriğinin başarıyla şifrelenmesini sağlayabilir.
x-ms-client-request-id İsteklerde ve karşılık gelen yanıtlarda sorun gidermek için bu üst bilgiyi kullanabilirsiniz. Bu üst bilginin değeri, istekte varsa üst bilginin değerine x-ms-client-request-id eşittir. Değer en fazla 1024 görünür ASCII karakterdir. İstekte x-ms-client-request-id üst bilgi yoksa, yanıtta bu üst bilgi yoktur.

Ö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

Yetkilendirme

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

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. Belirteç daha sonra 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.

İzinler

Aşağıda, bir Microsoft Entra kullanıcı, grup veya hizmet sorumlusunun işlemi çağırması Append Block 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. Blob verilerine erişim için Azure rolü atama.

Açıklamalar

Append Block mevcut ekleme blobunun sonuna bir blok yükler. Çağrı sunucuda başarılı olduktan sonra veri bloğu hemen kullanılabilir. Her ekleme blobu için en fazla 50.000 eklemeye izin verilir. Her blok farklı boyutta olabilir.

Aşağıdaki tabloda hizmet sürümüne göre izin verilen en fazla blok ve blob boyutu açıklanmaktadır:

Hizmet sürümü En büyük blok boyutu (aracılığıyla Append Block) En büyük blob boyutu
Sürüm 2022-11-02 ve üzeri 100 MiB (Önizleme) Yaklaşık 4,75 TiB (100 MiB × 50.000 blok)
2022-11-02'den önceki sürümler 4 MiB Yaklaşık 195 gibibayt (GiB) (4 MiB × 50.000 blok)

Append Block yalnızca blob zaten varsa başarılı olur.

kullanılarak Append Block karşıya yüklenen bloblar blok kimliklerini kullanıma sunmaz. Ekleme blobu için Get Block List çağrısı yapamazsınız. Bunun yapılması hatayla sonuçlanır.

İstekte aşağıdaki isteğe bağlı koşullu üst bilgileri belirtebilirsiniz:

  • x-ms-blob-condition-appendpos: Bu üst bilgiyi, istemcinin bloğu eklemeyi beklediği bayt uzaklığı olarak ayarlayabilirsiniz. İstek yalnızca geçerli uzaklık istemci tarafından belirtilenle eşleşiyorsa başarılı olur. Aksi takdirde istek 412 hata koduyla başarısız olur (Önkoşul Başarısız oldu).

    Tek bir yazıcı kullanan istemciler, ağ hatasına rağmen işlemin Append Block başarılı olup olmadığını belirlemek için bu üst bilgiyi kullanabilir.

  • x-ms-blob-condition-maxsize: İstemciler, ekleme işlemlerinin blob boyutunu bayt cinsinden beklenen en büyük boyutun ötesine yükseltmediğinden emin olmak için bu üst bilgiyi kullanabilir. Koşul başarısız olursa istek 412 (Önkoşul Başarısız Oldu) hata koduyla başarısız olur.

İzin verilen boyuttan daha büyük bir bloğu karşıya yüklemeye çalışırsanız, hizmet hata kodu 413 (İstek Varlığı Çok Büyük) döndürür. Hizmet ayrıca yanıttaki hata hakkında bayt cinsinden izin verilen en büyük blok boyutu da dahil olmak üzere ek bilgiler döndürür. 50.000'den fazla bloğu karşıya yüklemeye çalışırsanız, hizmet hata kodu 409 (Çakışma) döndürür.

Blob etkin bir kiraya sahipse, bloba bir blok yazmak için istemcinin istekte geçerli bir kira kimliği belirtmesi gerekir. İstemci bir kira kimliği belirtmezse veya geçersiz bir kira kimliği belirtirse, Blob Depolama 412 (Önkoşul Başarısız Oldu) hata kodunu döndürür. İstemci bir kira kimliği belirtiyorsa, ancak blob etkin bir kiraya sahip değilse, Blob Depolama da hata kodu 412'yi döndürür.

Mevcut bir blok blobunu veya sayfa blobunu çağırırsanız Append Block , hizmet bir çakışma hatası döndürür. Mevcut olmayan bir blobu çağırırsanız Append Block , hizmet bir hata da döndürür.

Yinelenen veya gecikmeli eklemelerden kaçının

Tek bir yazıcı senaryosunda istemci, geçerli uzaklığı denetlemek için koşullu üst bilgiyi kullanarak *x-ms-blob-condition-appendpos yinelenen eklemeleri veya gecikmeli yazmaları önleyebilir. İstemci ayrıca kullanarak If-Matchkoşullu olarak denetleyerek ETag yinelemeleri veya gecikmeleri önleyebilir.

Birden çok yazıcı senaryosunda, her istemci koşullu üst bilgileri kullanabilir, ancak bu performans için en uygun olmayabilir. En yüksek eşzamanlı ekleme aktarım hızı için uygulamalar, uygulama katmanındaki yedekli eklemeleri ve gecikmeli eklemeleri işlemelidir. Örneğin, uygulama eklenen verilere dönemler veya sıra numaraları ekleyebilir.

Faturalama

Fiyatlandırma istekleri, Blob Depolama API'lerini kullanan istemcilerden, doğrudan Blob Depolama REST API'si aracılığıyla veya bir Azure Depolama istemci kitaplığından kaynaklanabilir. Bu istekler işlem başına ücret tahakkuk eder. İşlem türü, hesabın nasıl ücretlendirildiğinden etkilenir. Ö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:

İşlem Depolama hesabı türü Faturalama kategorisi
Ekleme Bloğu Premium blok blobu
Standart genel amaçlı v2
Standart genel amaçlı v1		 Yazma işlemleri

Belirtilen faturalama kategorisinin fiyatlandırması hakkında bilgi edinmek için bkz. fiyatlandırma Azure Blob Depolama.