URL'den Blok Ekle

  • Makale

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

İşleme Append Block From URL yalnızca blob ile x-ms-blob-typeAppendBloboluşturulduysa izin verilir. Append Block From URL yalnızca 2018-11-09 veya sonraki sürümlerde desteklenir.

İstek

İsteği aşağıdaki gibi oluşturabilirsiniz Append Block From URL . 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ı. Zaman aşımı parametresi saniye cinsinden ifade edilir. Daha fazla bilgi için bkz. 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. İstek gövdesinde iletilen bayt sayısını belirtir. Bu üst bilginin değeri sıfır olarak ayarlanmalıdır. Uzunluk sıfır olmadığında işlem 400 (Hatalı İstek) hata koduyla başarısız olur.
x-ms-copy-source:name Gereklidir. Kaynak blobun URL'sini belirtir. Değer, blob belirten en fazla 2 KiB uzunluğunda bir URL olabilir. Değer, istek URI'sinde göründüğü gibi URL ile kodlanmış olmalıdır. Kaynak blob genel olmalıdır veya paylaşılan erişim imzası aracılığıyla yetkilendirilmelidir. Kaynak blob genel ise, işlemi gerçekleştirmek için yetkilendirme gerekmez. Kaynak nesne URL'lerine bazı örnekler aşağıda verilmiştir:

https://myaccount.blob.core.windows.net/mycontainer/myblob
https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> İsteğe bağlı. Kopyalama kaynağı için yetkilendirme düzenini ve imzayı belirtir. Daha fazla bilgi için bkz. Azure Depolama'ya istekleri yetkilendirme.
Microsoft Entra ID için yalnızca şema taşıyıcı desteklenir.
Bu üst bilgi 2020-10-02 ve sonraki sürümlerde desteklenir.
x-ms-source-range İsteğe bağlı. Belirtilen aralıktaki kaynak URL'deki blobun yalnızca baytlarını karşıya yükler. Bu belirtilmezse, kaynak blob içeriğinin tamamı tek bir ekleme bloğu olarak karşıya yüklenir. Daha fazla bilgi için bkz. Blob Depolama işlemleri için aralık üst bilgisini belirtme .
x-ms-source-content-md5 İsteğe bağlı. URI'den ekleme bloğu içeriğinin MD5 karması. Bu karma, verilerin URI'den taşınması sırasında ekleme bloğunun bütünlüğünü doğrulamak için kullanılır. Bu üst bilgiyi belirttiğinizde, depolama hizmeti kopyalama kaynağından gelen içeriğin karması ile bu üst bilgi değerini karşılaştırır.

Bu MD5 karması blob ile depolanmaz.

İki karma eşleşmiyorsa işlem 400 (Hatalı İstek) hata koduyla başarısız olur.
x-ms-source-content-crc64 İsteğe bağlı. URI'den ekleme bloğu içeriğinin CRC64 karması. Bu karma, verilerin URI'den taşınması sırasında ekleme bloğunun bütünlüğünü doğrulamak için kullanılır. Bu üst bilgiyi belirttiğinizde, depolama hizmeti kopyalama kaynağından gelen içeriğin karması ile bu üst bilgi değerini karşılaştırır.

Bu CRC64 karması blob ile depolanmaz.

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

Hem hem de x-ms-source-content-md5x-ms-source-content-crc64 üst bilgileri varsa, istek 400 (Hatalı İstek) ile 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ı. Kaynak içeriği ş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ı. İşlem blob'un Append Block From URL 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) ile 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 from URL kullanılır. Karşılaştırılması gereken bayt uzaklığını gösteren bir sayı. Append Block from URL yalnızca ekleme konumu bu sayıya eşitse başarılı olur. Aksi takdirde istek 412 (Önkoşul Başarısız Oldu) ile 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 bilgilerin kullanımını destekler. Daha fazla bilgi için bkz. 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: 2018-11-09  
x-ms-date: <date>  
x-ms-copy-source: https://myaccount.blob.core.windows.net/mycontainer/myblob
x-ms-source-range: bytes=0-65535
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 0 
If-Match: "0x8CB172A360EC34B"

Yanıt

Yanıt bir HTTP durum kodu ve yanıt üst bilgileri kümesi 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 kullanır.
Last-Modified Blob'un son değiştirildiği tarih/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. Blob Depolama bu üst bilginin değerini hesaplar. İstek üst bilgilerinde belirtilen değerle aynı olmayabilir. Sürüm 2019-02-02 veya üzeri için, bu üst bilgi yalnızca istekte bu üst bilgi olduğunda döndürülür.
x-ms-content-crc64 Sürüm 2019-02-02 veya üzeri için. İstemcinin ileti içerik bütünlüğünü denetleyebilmesi için bu üst bilgi döndürülür. Blob Depolama bu üst bilginin değerini hesaplar. İstek üst bilgilerinde belirtilen değerle aynı olmayabilir.

Üst bilgi istekte mevcut olmadığında bu üst bilgi döndürülür x-ms-source-content-md5 .
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ümlerde yapılan istekler için döndürülür.
Date Hizmet tarafından oluşturulan ve yanıtın başlatıldığı saati gösteren utc tarih/saat değeri.
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 kaydedilmiş 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 kullanılarak 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.

Ö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şimi işlemi çağrılırken yetkilendirme gereklidir. İşlemi aşağıda açıklandığı gibi yetki Append Block From URL verebilirsiniz.

Bu bölümdeki yetkilendirme ayrıntıları kopyalama hedefi için geçerlidir. Kaynak yetkilendirmesini kopyalama hakkında daha fazla bilgi için, istek üst bilgisinin x-ms-copy-sourceayrıntılarına bakın.

Ö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 güvenlik sorumlusuna izinler verilmektedir. Güvenlik sorumlusu bir kullanıcı, grup, uygulama hizmet sorumlusu veya Azure yönetilen kimliği olabilir. Güvenlik sorumlusunun kimliği, OAuth 2.0 belirtecini döndürmek için 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, Microsoft Entra kullanıcı, grup, yönetilen kimlik veya hizmet sorumlusunun işlemi çağırması Append Block From URL 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 From URL 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; burada. 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 From URL) 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 öncesi sürümler 4 MiB Yaklaşık 195 gibibayt (GiB) (4 MiB × 50.000 blok)

Sürüm 2020-10-02 ve sonraki sürümlerde, kopyalama işleminin kaynağı için Microsoft Entra ID yetkilendirme desteklenir.

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

kullanılarak Append Block From URL karşıya yüklenen bloblar blok kimliklerini kullanıma sunmaz, bu nedenle ekleme blobu için Get Block List çağrısını 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 ancak 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 bir Append Block From URL işlemin ne zaman başarılı olup olmadığını belirlemek için bu üst bilgiyi kullanabilir.

  • x-ms-blob-condition-maxsize: İstemciler, ekleme işlemlerinin blob boyutunu beklenen bayt cinsinden 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 HTTP hata kodu 413 (İstek Varlığı Çok Büyük) döndürür. Hizmet ayrıca bayt cinsinden izin verilen en büyük blok boyutu da dahil olmak üzere yanıttaki hata hakkında ek bilgiler döndürür. 50.000'den fazla bloğu karşıya yüklemeyi denerseniz, 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 blobda etkin bir kira yoksa, hizmet hata kodu 412'yi döndürür.

Mevcut blok blobunu veya sayfa blobunu çağırırsanız Append Block From URL hizmet 409 (Çakışma) hata kodunu döndürür. Var olmayan bir blobda çağırırsanız Append Block From URL hizmet 404 (Bulunamadı) hata kodunu 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. Bu, performans için en uygun olmayabilir. En yüksek eşzamanlı ekleme aktarım hızı için, uygulamaların uygulama katmanlarında yedekli eklemeleri ve gecikmeli eklemeleri işlemesi gerekir. Örneğin, uygulamalar eklenen verilere dönemler veya sıra numaraları ekleyebilir.

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

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 ücretlendirilmeyi 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 From URL faturalama kategorisi gösterilmektedir:

İşlem Depolama hesabı türü Faturalama kategorisi
Url'den Blok Ekle (hedef hesap1) Premium blok blobu
Standart genel amaçlı v2
Standart genel amaçlı v1		 Yazma işlemleri
Url'den Blok Ekle (kaynak hesap2) Premium blok blobu
Standart genel amaçlı v2
Standart genel amaçlı v1		 Okuma işlemleri

1Yazma işlemini başlatmak için hedef hesap bir işlem için ücretlendirilir.
2Kaynak hesap, kaynağa yapılan her okuma isteği için bir işlem oluşturur.