Blokk hozzáfűzése URL-címből

Cikk
02/12/2024

A Append Block From URL művelet egy új adatblokkot véglegesíti egy meglévő hozzáfűző blob végére.

A Append Block From URL művelet csak akkor engedélyezett, ha a blob a következő beállítással x-ms-blob-typeAppendBloblett létrehozva: . Append Block From URL csak a 2018-11-09-es vagy újabb verzióban támogatott.

Kérés

A kérést a Append Block From URL következőképpen hozhatja létre. A HTTPS használata ajánlott. Cserélje le a myaccount nevet a tárfiók nevére.

PUT metódus kérésének URI-ja	HTTP-verzió
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock`	HTTP/1.1

Amikor kérést küld az emulált tárolási szolgáltatásra, adja meg az emulátor gazdagépnevét és Azure Blob Storage portot 127.0.0.1:10000, majd az emulált tárfiók nevét.

PUT metódus kérésének URI-ja	HTTP-verzió
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock`	HTTP/1.1

További információ: Az Azurite emulátor használata helyi Azure Storage-fejlesztéshez.

URI-paraméterek

Paraméter	Leírás
`timeout`	Választható. Az időtúllépési paraméter másodpercben van kifejezve. További információ: Időtúllépések beállítása a Blob Storage-műveletekhez.

Kérésfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérelemfejléceket ismerteti.

Kérelem fejléce	Leírás
`Authorization`	Kötelező. Megadja az engedélyezési sémát, a fióknevet és az aláírást. További információ: Kérelmek engedélyezése az Azure Storage-ba .
`Date` vagy `x-ms-date`	Kötelező. Megadja a kérés egyezményes világidő (UTC) formátumban kifejezett időpontját. További információ: Kérések engedélyezése az Azure Storage-ba.
`x-ms-version`	Minden engedélyezett kéréshez szükséges. A kérelemhez használni kívánt művelet verzióját adja meg. További információ: Az Azure Storage-szolgáltatások verziószámozása.
`Content-Length`	Kötelező. A kérelem törzsében továbbított bájtok számát adja meg. Ennek a fejlécnek az értékét nullára kell állítani. Ha a hossz nem nulla, a művelet 400-ás hibakóddal (Hibás kérelem) meghiúsul.
`x-ms-copy-source:name`	Kötelező. Megadja a forrásblob URL-címét. Az érték legfeljebb 2 KiB hosszúságú URL-cím lehet, amely blobot határoz meg. Az értéknek URL-kódolásúnak kell lennie, ahogy az egy kérelem URI-jában is megjelenik. A forrásblobnak nyilvánosnak kell lennie, vagy közös hozzáférésű jogosultságkóddal kell rendelkeznie. Ha a forrásblob nyilvános, a művelet végrehajtásához nincs szükség engedélyezésre. Íme néhány példa a forrásobjektum URL-címére: `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>`	Választható. Megadja a másolási forrás engedélyezési sémáját és aláírását. További információ: Kérések engedélyezése az Azure Storage-ba. Csak a séma tulajdonosát támogatja a Microsoft Entra ID. Ez a fejléc a 2020-10-02-es és újabb verzióban támogatott.
`x-ms-source-range`	Választható. Csak a blob bájtjait tölti fel a forrás URL-címében a megadott tartományban. Ha ez nincs megadva, a teljes forrásblob tartalma egyetlen hozzáfűző blokkként lesz feltöltve. További információt a Blob Storage-műveletek tartományfejlécének megadása című témakörben talál.
`x-ms-source-content-md5`	Választható. Az URI-ból származó hozzáfűző blokk tartalmának MD5-kivonata. Ez a kivonat a hozzáfűző blokk integritásának ellenőrzésére szolgál az adatok URI-ból való átvitele során. A fejléc megadásakor a tárolási szolgáltatás összehasonlítja a másolási forrásból érkezett tartalom kivonatát ezzel a fejlécértékkel. Vegye figyelembe, hogy ez az MD5-kivonat nem a blobban van tárolva. Ha a két kivonat nem egyezik, a művelet 400-es hibakóddal (hibás kérelem) meghiúsul.
`x-ms-source-content-crc64`	Választható. A hozzáfűzési blokk URI-jának CRC64-kivonata. Ez a kivonat a hozzáfűző blokk integritásának ellenőrzésére szolgál az adatok URI-ból való átvitele során. A fejléc megadásakor a tárolási szolgáltatás összehasonlítja a másolási forrásból érkezett tartalom kivonatát ezzel a fejlécértékkel. Vegye figyelembe, hogy ez a CRC64-kivonat nem a blobban van tárolva. Ha a két kivonat nem egyezik, a művelet 400-es hibakóddal (hibás kérelem) meghiúsul. Ha mindkét `x-ms-source-content-md5` és `x-ms-source-content-crc64` fejléc is jelen van, a kérés 400-zal (hibás kéréssel) meghiúsul. Ez a fejléc a 2019-02-02-es vagy újabb verzióban támogatott.
`x-ms-encryption-scope`	Választható. A forrástartalom titkosításához használandó titkosítási hatókört jelöli. Ez a fejléc a 2019-02-02-es vagy újabb verzióban támogatott.
`x-ms-lease-id:<ID>`	Akkor szükséges, ha a blob rendelkezik aktív bérlettal. Ha ezt a műveletet aktív bérlettel rendelkező blobon szeretné végrehajtani, adja meg a fejléc érvényes bérletazonosítóját.
`x-ms-client-request-id`	Választható. Ügyfél által generált, átlátszatlan értéket biztosít egy 1 kib-os (KiB) karakterkorláttal, amelyet a naplózás konfigurálásakor rögzít a naplókban. Javasoljuk, hogy ezt a fejlécet használva korrelálja az ügyféloldali tevékenységeket a kiszolgáló által kapott kérésekkel. További információ: Monitorozási Azure Blob Storage.
`x-ms-blob-condition-maxsize`	Nem kötelező feltételes fejléc. A hozzáfűző blob megengedett maximális hossza bájtban. Ha a `Append Block From URL` művelet hatására a blob túllépi ezt a korlátot, vagy ha a blob mérete már nagyobb, mint az ebben a fejlécben megadott érték, a kérés 412-es hibával meghiúsul (az előfeltétel sikertelen).
`x-ms-blob-condition-appendpos`	Nem kötelező feltételes fejléc, amely csak a `Append Block from URL` művelethez használható. Az összehasonlítandó bájteltolást jelző szám. `Append Block from URL` csak akkor sikerül, ha a hozzáfűzési pozíció egyenlő ezzel a számmal. Ha nem, a kérés egy 412-vel meghiúsul (az előfeltétel sikertelen).

Ez a művelet további feltételes fejlécek használatát is támogatja, hogy az API csak egy adott feltétel teljesülése esetén legyen sikeres. További információ: Feltételes fejlécek megadása Blob Storage-műveletekhez.

Kérelemfejlécek (ügyfél által megadott titkosítási kulcsok)

A 2019-02-02-es verziótól kezdődően a következő fejléceket adhatja meg a kérelemben egy blob ügyfél által megadott kulccsal történő titkosítására. Az ügyfél által megadott kulccsal (és a megfelelő fejléckészlettel) történő titkosítás nem kötelező.

Kérelem fejléce	Leírás
`x-ms-encryption-key`	Kötelező. A Base64 kódolású AES-256 titkosítási kulcs.
`x-ms-encryption-key-sha256`	Kötelező. A titkosítási kulcs Base64 kódolású SHA256 kivonata.
`x-ms-encryption-algorithm: AES256`	Kötelező. Megadja a titkosításhoz használni kívánt algoritmust. A fejléc értékének a következőnek kell lennie `AES256`: .

A kérés törzse

A kérelemtörzs tartalmazza a blokk tartalmát.

Mintakérés

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"

Reagálás

A válasz tartalmaz egy HTTP-állapotkódot és egy válaszfejléceket.

Állapotkód

A sikeres művelet a 201-ben létrehozott állapotkódot adja vissza. Az állapotkódokkal kapcsolatos információkért lásd: Állapot- és hibakódok.

Válaszfejlécek

A műveletre adott válasz a következő fejléceket tartalmazza. A válasz további szabványos HTTP-fejléceket is tartalmazhat. Minden szabványos fejléc megfelel a HTTP/1.1 protokoll specifikációjának.

Válaszfejléc	Description
`Etag`	A `ETag` az idézőjelek egyik értékét tartalmazza. Az ügyfél az értéket használja feltételes `PUT` műveletek végrehajtásához a `If-Match` kérelemfejléc használatával.
`Last-Modified`	A blob utolsó módosításának dátuma/időpontja. A dátumformátum az RFC 1123-at követi. További információ: Dátum-idő értékek ábrázolása fejlécekben. A blob írási műveletei (beleértve a blob metaadatainak vagy tulajdonságainak frissítéseit) módosítják a blob utolsó módosítási időpontját.
`Content-MD5`	Ez a fejléc lesz visszaadva, hogy az ügyfél ellenőrizni tudja az üzenettartalom integritását. A Blob Storage kiszámítja ennek a fejlécnek az értékét. Nem feltétlenül ugyanaz az érték, mint a kérelemfejlécekben. A 2019-02-02-es vagy újabb verzió esetén a rendszer csak akkor adja vissza ezt a fejlécet, ha a kérelemhez tartozik ez a fejléc.
`x-ms-content-crc64`	A 2019-02-02-es vagy újabb verzióhoz. Ez a fejléc lesz visszaadva, hogy az ügyfél ellenőrizni tudja az üzenettartalom integritását. A Blob Storage kiszámítja ennek a fejlécnek az értékét. Nem feltétlenül ugyanaz az érték, mint a kérelemfejlécekben. Ez a fejléc akkor lesz visszaadva, ha a `x-ms-source-content-md5` fejléc nem szerepel a kérelemben.
`x-ms-request-id`	Ez a fejléc egyedileg azonosítja a végrehajtott kérést, és a kérés hibaelhárításához használható.
`x-ms-version`	A Blob Storage kérés futtatásához használt verzióját jelzi. A rendszer ezt a fejlécet adja vissza a 2009-09-19-es és újabb verzióval kapcsolatos kérésekhez.
`Date`	A szolgáltatás által létrehozott UTC dátum/idő érték, amely a válasz indításának időpontját jelzi.
`x-ms-blob-append-offset`	Ez a válaszfejléc csak hozzáfűzési műveletekhez lesz visszaadva. A blokk véglegesített eltolását adja vissza bájtban.
`x-ms-blob-committed-block-count`	A blobban található véglegesített blokkok száma. Ezzel szabályozhatja, hogy hány további hozzáfűzés végezhető el.
`x-ms-request-server-encrypted: true/false`	2015-12-11-es vagy újabb verzió. Ennek a fejlécnek az értéke akkor `true` van beállítva, ha a kérelem tartalma sikeresen titkosítva van a megadott algoritmussal. Ellenkező esetben az érték a következőre `false`van állítva: .
`x-ms-encryption-key-sha256`	2019-02-02-es vagy újabb verzió. Ez a fejléc akkor jelenik meg, ha a kérelem ügyfél által megadott kulcsot használt a titkosításhoz. Az ügyfél ezután meggyőződhet arról, hogy a kérelem tartalma sikeresen titkosítva van a megadott kulccsal.
`x-ms-encryption-scope`	2019-02-02-es vagy újabb verzió. Ez a fejléc akkor jelenik meg, ha a kérelem titkosítási hatókört használt. Az ügyfél ezután meggyőződhet arról, hogy a kérelem tartalma sikeresen titkosítva van a titkosítási hatókör használatával.

Mintaválasz

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

Engedélyezés

Az Azure Storage-ban bármilyen adathozzáférési művelet meghívásához engedélyezésre van szükség. A műveletet az Append Block From URL alábbiak szerint engedélyezheti.

Az ebben a szakaszban szereplő engedélyezési adatok a másolási célhelyre vonatkoznak. A másolási forrás engedélyezéséről további információt a kérelem fejlécének x-ms-copy-sourcerészleteiben talál.

Fontos

A Microsoft azt javasolja, hogy Microsoft Entra ID felügyelt identitásokkal engedélyezze az Azure Storage-ra irányuló kéréseket. Microsoft Entra ID a megosztott kulcs engedélyezéséhez képest kiváló biztonságot és könnyű használatot biztosít.

Az Azure Storage támogatja az Microsoft Entra ID használatát a blobadatokra irányuló kérések engedélyezéséhez. A Microsoft Entra ID azure-beli szerepköralapú hozzáférés-vezérléssel (Azure RBAC) adhat engedélyeket egy biztonsági tagnak. A rendszerbiztonsági tag lehet felhasználó, csoport, alkalmazásszolgáltatásnév vagy Azure-beli felügyelt identitás. A rendszerbiztonsági tagot a Microsoft Entra ID hitelesíti egy OAuth 2.0-jogkivonat visszaadásához. A jogkivonat ezután a Blob szolgáltatással szembeni kérések engedélyezésére használható.

További információ a Microsoft Entra ID használatával történő engedélyezésről: Blobok hozzáférésének engedélyezése Microsoft Entra ID használatával.

Engedélyek

Az alábbiakban felsoroljuk azt az RBAC-műveletet, amely a művelet meghívásához Append Block From URL szükséges Microsoft Entra felhasználóhoz, csoporthoz, felügyelt identitáshoz vagy szolgáltatásnévhez, valamint a legkevésbé emelt szintű beépített Azure RBAC-szerepkörhöz, amely tartalmazza ezt a műveletet:

Azure RBAC-művelet:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action vagy Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Legkevésbé emelt szintű beépített szerepkör:Storage-blobadatok közreműködője

A szerepkörök Azure RBAC-vel való hozzárendeléséről további információt az Azure-szerepkör hozzárendelése a blobadatokhoz való hozzáféréshez című témakörben talál.

A közös hozzáférésű jogosultságkód (SAS) biztonságos delegált hozzáférést biztosít a tárfiók erőforrásaihoz. Sas esetén részletes vezérléssel rendelkezik arról, hogy az ügyfél hogyan férhet hozzá az adatokhoz. Megadhatja, hogy az ügyfél milyen erőforráshoz férhet hozzá, milyen engedélyekkel rendelkezik ezekhez az erőforrásokhoz, és hogy az SAS mennyi ideig érvényes.

A Append Block From URL művelet háromféle közös hozzáférésű jogosultságkódot támogat: a felhasználói delegálási SAS-t, a szolgáltatás SAS-t és a fiók SAS-t.

Ajánlott biztonsági gyakorlatként azt javasoljuk, hogy a tárfiókkulcs helyett Microsoft Entra hitelesítő adatokat használjon, amelyek könnyebben sérülhetnek. Ha az alkalmazás kialakításához közös hozzáférésű jogosultságkódra van szükség, Microsoft Entra hitelesítő adatokkal hozzon létre egy felhasználói delegálási SAS-t, ha lehetséges.

Ha a megosztott kulcs hozzáférése nincs engedélyezve a tárfiókhoz, a Blob Storage-ra irányuló kérések esetén a szolgáltatás SAS-jogkivonata vagy a fiók SAS-jogkivonata nem lesz engedélyezve. További információ: A megosztott kulcs letiltása hogyan befolyásolja az SAS-jogkivonatokat.

Felhasználói delegálási SAS

A felhasználói delegálási SAS-t Microsoft Entra hitelesítő adatokkal és az SAS-hez megadott engedélyekkel védik.

A Append Block From URL művelet tárolóba vagy bloberőforrásba delegált SAS-jogkivonat használatával történő meghívásához a felhasználói delegálási SAS-jogkivonat részeként az Add (a) vagy Write (w) engedély szükséges:

A felhasználói delegálási SAS-ről a felhasználói delegálási SAS Létrehozás című témakörben olvashat bővebben.

Szolgáltatás SAS

A szolgáltatás SAS-t a tárfiókkulcs védi. A szolgáltatás sasa egyetlen Azure Storage-szolgáltatásban, például a blobtárolóban delegálja a hozzáférést egy erőforráshoz.

A Append Block From URL műveletet tárolóba vagy bloberőforrásba delegált SAS-jogkivonat használatával történő meghívásához a szolgáltatás SAS-jogkivonatának részeként az Add (a) vagy Write (w) engedély szükséges.

A szolgáltatás SAS-járól további információt a szolgáltatás SAS-Létrehozás című témakörben talál.

Fiók SAS-fiókja

A fiók SAS-jének biztonságát a tárfiókkulcs biztosítja. A fiókalapú SAS egy vagy több tárolószolgáltatás erőforrásaihoz nyújt hozzáférést. A szolgáltatáson vagy a felhasználói delegálási SAS-en keresztül elérhető összes művelet fiók SAS-en keresztül is elérhető.

Az alábbi táblázat az aláírt erőforrástípust és az aláírt engedélyeket jelzi, amelyet a hozzáférés delegálásakor meg kell adni:

Művelet	Aláírt szolgáltatás	Aláírt erőforrástípus	Aláírt engedély
Blokk hozzáfűzése URL-címből	Blob (b)	Objektum (o)	Hozzáadás (a) vagy Írás (w)

A fiók SAS-járól további információt a fiók SAS-Létrehozás című témakörben talál.

Megjegyzések

Append Block From URL feltölt egy blokkot egy meglévő hozzáfűző blob végére. Az adatblokk azonnal elérhető, miután a hívás sikeres volt a kiszolgálón. Minden hozzáfűző blobhoz legfeljebb 50 000 hozzáfűzés engedélyezett, ahol. Minden blokk különböző méretű lehet.

Az alábbi táblázat a maximálisan engedélyezett blokk- és blobméreteket ismerteti a szolgáltatásverzió szerint:

Szolgáltatás verziója	Maximális blokkméret (keresztül `Append Block From URL`)	Maximális blobméret
2022-11-02-es és újabb verzió	100 MiB (előzetes verzió)	Körülbelül 4,75 TiB (100 MiB × 50 000 blokk)
2022-11-02-nél korábbi verziók	4 MiB	Körülbelül 195 gibibyte (GiB) (4 MiB × 50 000 blokk)

A 2020-10-02-es és újabb verziókban Microsoft Entra ID hitelesítés támogatott a másolási művelet forrásához.

Append Block From URL csak akkor sikerül, ha a blob már létezik.

A nem közzétett blokkazonosítók használatával Append Block From URL feltöltött blobok nem hívhatók meg a blokklista lekérése hozzáfűző blobokhoz. Ha így tesz, az hibát eredményez.

A kérelemhez a következő választható feltételes fejléceket adhatja meg:

x-ms-blob-condition-appendpos: Beállíthatja ezt a fejlécet egy bájteltolásra, amelynél az ügyfél a blokk hozzáfűzését várja. A kérés csak akkor sikeres, ha az aktuális eltolás megegyezik az ügyfél által megadott eltolással. Ellenkező esetben a kérés a 412-s hibakóddal hiúsul meg (az előfeltétel sikertelen).

Az egyetlen írót használó ügyfelek ezzel a fejléccel megállapíthatják, hogy egy Append Block From URL művelet sikeres volt-e a hálózati hiba ellenére.
x-ms-blob-condition-maxsize: Az ügyfelek ezzel a fejléccel gondoskodhatnak arról, hogy a hozzáfűzési műveletek ne növeljék a blob méretét a várt maximális bájtméretnél. Ha a feltétel meghiúsul, a kérés a 412-s hibakóddal hiúsul meg (az előfeltétel sikertelen).

Ha a megengedett méretnél nagyobb blokkot próbál feltölteni, a szolgáltatás a 413-es HTTP-hibakódot adja vissza (a kérelem entitása túl nagy). A szolgáltatás további információkat is ad vissza a válaszban szereplő hibáról, beleértve a bájtokban megengedett maximális blokkméretet is. Ha több mint 50 000 blokkot próbál feltölteni, a szolgáltatás a 409-ös hibakódot (Ütközés) adja vissza.

Ha a blob rendelkezik aktív bérletmel, az ügyfélnek meg kell adnia egy érvényes bérletazonosítót a kérelemben, hogy blokkot írjon a blobnak. Ha az ügyfél nem ad meg bérletazonosítót, vagy érvénytelen bérletazonosítót ad meg, a Blob Storage a 412-s hibakódot adja vissza (az előfeltétel sikertelen). Ha az ügyfél bérletazonosítót ad meg, de a blobnak nincs aktív bérlete, a szolgáltatás a 412-ös hibakódot adja vissza.

Ha egy meglévő blokkblobot vagy lapblobot hív meg Append Block From URL , a szolgáltatás a 409-s hibakódot (Ütközés) adja vissza. Ha nem létező blobot hív meg Append Block From URL , a szolgáltatás a 404-s hibakódot adja vissza (nem található).

A duplikált vagy késleltetett hozzáfűzések elkerülése

Egyetlen írói forgatókönyvben az ügyfél elkerülheti a duplikált hozzáfűzéseket vagy a késleltetett írásokat a x-ms-blob-condition-appendpos feltételes fejléc használatával az aktuális eltolás ellenőrzéséhez. Az ügyfél a feltételes ellenőrzéssel is elkerülheti az ismétlődéseket és a késéseket a ETag használatával If-Match.

Több írós forgatókönyv esetén minden ügyfél használhat feltételes fejléceket. Lehet, hogy ez nem optimális a teljesítmény szempontjából. A legmagasabb egyidejű hozzáfűzési teljesítmény érdekében az alkalmazásoknak redundáns hozzáfűzéseket és késleltetett hozzáfűzéseket kell kezelniük az alkalmazásrétegben. Az alkalmazások például hozzáadhatnak korszakokat vagy sorszámokat a hozzáfűzött adatokhoz.

A megadott számlázási kategória díjszabásával kapcsolatos további információkért lásd: Azure Blob Storage Díjszabás.

Számlázás

A díjszabási kérések a Blob Storage API-kat használó ügyfelektől, közvetlenül a Blob Storage REST API-ból vagy egy Azure Storage-ügyfélkódtárból származhatnak. Ezek a kérések tranzakciónkénti díjakat halmoznak fel. A tranzakció típusa befolyásolja a fiók terhelését. Az olvasási tranzakciók például más számlázási kategóriába tartoznak, mint az írási tranzakciók. Az alábbi táblázat a tárfiók típusa alapján a kérelmek számlázási kategóriáját Append Block From URL mutatja be:

Művelet	Tárfiók típusa	Számlázási kategória
Blokk hozzáfűzése URL-címből (^{célfiók 1})	Prémium szintű blokkblob Standard általános célú v2 Standard általános célú v1	Írási műveletek
Blokk hozzáfűzése URL-címből (². forrásfiók)	Prémium szintű blokkblob Standard általános célú v2 Standard általános célú v1	Olvasási műveletek

¹A célfiókot egy tranzakcióra terheljük az írás kezdeményezéséhez.
²A forrásfiók minden egyes olvasási kéréshez egy tranzakciót bonyolít a forráshoz.

Megosztás a következőn keresztül: