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éig.

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

Kérés

A kérést az Append Block From URL alábbiak szerint hozhatja létre. A HTTPS használata ajánlott. Cserélje le a myaccount kifejezést a tárfiók nevére.

PUT metóduskérés 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 gazdanevét és Azure Blob Storage portot 127.0.0.1:10000, majd az emulált tárfiók nevét.

PUT metóduskérés 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 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érelmek engedélyezése az Azure Storage-ba.
`x-ms-version`	Minden engedélyezett kéréshez szükséges. A kérelemhez használandó 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. A fejléc értékét nullára kell állítani. Ha a hossz nem nulla, a művelet 400-es hibakóddal (hibás kérés) meghiúsul.
`x-ms-copy-source:name`	Kötelező. A forrásblob URL-címét adja meg. Az érték legfeljebb 2 kib hosszúságú URL-cím lehet, amely egy blobot határoz meg. Az értéknek URL-kódolásúnak kell lennie, ahogy az a 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érelmek engedélyezése az Azure Storage-ba. Csak a rendszer tulajdonosát támogatja a Microsoft Entra ID. Ez a fejléc a 2020-10-02-es és újabb verziókban támogatott.
`x-ms-source-range`	Választható. Csak a blob bájtjainak feltöltése 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ó. A hozzáfűző blokktartalom MD5-kivonata az URI-ból. 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 a 400-es hibakóddal (hibás kérelem) meghiúsul.
`x-ms-source-content-crc64`	Választható. A hozzáfűző blokk URI-ból származó tartalmá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 a 400-es hibakóddal (hibás kérelem) meghiúsul. Ha a és `x-ms-source-content-crc64` a fejléc is `x-ms-source-content-md5` 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 jelzi. 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 kibibyte (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ó: Azure Blob Storage figyelése.
`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 miatt 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 412-vel meghiúsul (az előfeltétel sikertelen).

Ez a művelet támogatja további feltételes fejlécek használatát, 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 biztosított titkosítási kulcsok)

A 2019-02-02-es verziótól kezdődően a következő fejléceket adhatja meg a blob ügyfél által megadott kulccsal történő titkosítására vonatkozó kérelemben. 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.

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 azokat az RBAC-műveletet soroljuk fel, amelyek szükségesek ahhoz, hogy egy Microsoft Entra felhasználó, csoport vagy szolgáltatásnév meghívja a Append Block From URL műveletet, valamint a legkevésbé kiemelt beépített Azure RBAC-szerepkört, 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 további információt a Felhasználói delegálási SAS létrehozása című témakörben talál.

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ása 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)

További információ a fiók SAS-járól: Fiók SAS létrehozása.

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. Legfeljebb 50 000 hozzáfűzés engedélyezett minden hozzáfűző blobhoz, 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 szolgáltatásverzió szerint:

Szolgáltatás verziója	Maximális blokkméret (a használatával `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 gibibytes (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 használatával Append Block From URL feltöltött blobok nem teszik elérhetővé a blokkazonosítókat, így nem hívhatja meg a Blokklista lekérése parancsot egy hozzáfűző blobhoz. Ha így tesz, az hibát eredményez.

A kérelemhez a következő nem kötelező feltételes fejléceket adhatja meg:

x-ms-blob-condition-appendpos: Ezt a fejlécet beállíthatja 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 meghiúsul (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 maximálisan megengedett blokkméretet bájtban. 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 érvényes bérletazonosítót kell megadnia a kérelemben ahhoz, hogy blokkot írjon a blobba. 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 megad egy bérletazonosítót, 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 -os hibakódot (Ütközés) adja vissza. Ha nem létező blobot hív Append Block From URL meg, a szolgáltatás a 404 -os hibakódot adja vissza (nem található).

Kerülje a duplikált vagy késleltetett hozzáfűzéseket

Egyetlen írói forgatókönyv esetén 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. Előfordulhat, hogy ez nem optimális a teljesítményhez. A legnagyobb 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 alapidőszakokat vagy sorszámokat a hozzáfűzött adatokhoz.

A megadott számlázási kategória díjszabásáról a Azure Blob Storage Díjszabás című témakörben talál további információt.

Számlázás

A díjszabási kérések olyan ügyfelektől származhatnak, amelyek Blob Storage API-kat használnak, közvetlenül a Blob Storage REST API-ból vagy egy Azure Storage-ügyfélkódtárból. 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
Letiltás hozzáfűzése URL-címrő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
Hozzáfűzési blokk URL-címről (². forrásfiók)	Prémium szintű blokkblob Standard általános célú v2 Standard általános célú v1	Olvasási műveletek

¹Az írás kezdeményezéséhez a célfiókot egy tranzakcióra terheljük.
²A forrásfiók minden olvasási kérelemhez egy tranzakciót von maga után.