Blok toevoegen vanuit URL

Artikel
02/13/2024

Met Append Block From URL de bewerking wordt een nieuw gegevensblok doorgevoerd aan het einde van een bestaande toevoeg-blob.

De Append Block From URL bewerking is alleen toegestaan als de blob is gemaakt met x-ms-blob-type ingesteld op AppendBlob. Append Block From URL wordt alleen ondersteund op versie 2018-11-09 of hoger.

Aanvraag

U kunt de Append Block From URL aanvraag als volgt samenstellen. HTTPS wordt aanbevolen. Vervang myaccount door de naam van uw opslagaccount.

AANVRAAG-URI voor PUT-methode	HTTP-versie
`https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock`	HTTP/1.1

Wanneer u een aanvraag voor de geëmuleerde opslagservice indient, geeft u de hostnaam van de emulator en Azure Blob Storage poort op als 127.0.0.1:10000, gevolgd door de naam van het geëmuleerde opslagaccount.

AANVRAAG-URI voor PUT-methode	HTTP-versie
`http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock`	HTTP/1.1

Zie Use the Azurite emulator for local Azure Storage development (De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling) voor meer informatie.

URI-parameters

Parameter	Beschrijving
`timeout`	Optioneel. De time-outparameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven.

Aanvraagheader	Beschrijving
`Authorization`	Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening op. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`Date` of `x-ms-date`	Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie.
`x-ms-version`	Vereist voor alle geautoriseerde aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
`Content-Length`	Vereist. Hiermee geeft u het aantal bytes dat wordt verzonden in de aanvraagbody. De waarde van deze koptekst moet worden ingesteld op nul. Als de lengte niet nul is, mislukt de bewerking met foutcode 400 (Ongeldige aanvraag).
`x-ms-copy-source:name`	Vereist. Hiermee geeft u de URL van de bron-blob op. De waarde kan een URL van maximaal 2 KiB zijn die een blob aangeeft. De waarde moet URL-gecodeerd zijn, zoals deze wordt weergegeven in een aanvraag-URI. De bron-blob moet openbaar zijn of moet worden geautoriseerd via een handtekening voor gedeelde toegang. Als de bron-blob openbaar is, is er geen autorisatie vereist om de bewerking uit te voeren. Hier volgen enkele voorbeelden van bronobject-URL's: `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>`	Optioneel. Hiermee geeft u het autorisatieschema en de handtekening voor de kopieerbron op. Zie Aanvragen autoriseren voor Azure Storage voor meer informatie. Alleen schemadrager wordt ondersteund voor Microsoft Entra ID. Deze header wordt ondersteund in versie 2020-10-02 en hoger.
`x-ms-source-range`	Optioneel. Uploadt alleen de bytes van de blob in de bron-URL in het opgegeven bereik. Als dit niet is opgegeven, wordt de volledige inhoud van de bron-blob geüpload als één toevoegblok. Zie De bereikheader opgeven voor Blob Storage-bewerkingen voor meer informatie.
`x-ms-source-content-md5`	Optioneel. Een MD5-hash van de toevoegblokinhoud van de URI. Deze hash wordt gebruikt om de integriteit van het toevoegblok te controleren tijdens het transport van de gegevens uit de URI. Wanneer u deze header opgeeft, vergelijkt de opslagservice de hash van de inhoud die afkomstig is van de copy-source met deze headerwaarde. Houd er rekening mee dat deze MD5-hash niet wordt opgeslagen met de blob. Als de twee hashes niet overeenkomen, mislukt de bewerking met foutcode 400 (ongeldige aanvraag).
`x-ms-source-content-crc64`	Optioneel. Een CRC64-hash van de toevoegblokinhoud van de URI. Deze hash wordt gebruikt om de integriteit van het toevoegblok te controleren tijdens het transport van de gegevens uit de URI. Wanneer u deze header opgeeft, vergelijkt de opslagservice de hash van de inhoud die afkomstig is van de copy-source met deze headerwaarde. Houd er rekening mee dat deze CRC64-hash niet wordt opgeslagen met de blob. Als de twee hashes niet overeenkomen, mislukt de bewerking met foutcode 400 (ongeldige aanvraag). Als zowel `x-ms-source-content-md5` als `x-ms-source-content-crc64` headers aanwezig zijn, mislukt de aanvraag met een 400 (Ongeldige aanvraag). Deze header wordt ondersteund in versie 2019-02-02 of hoger.
`x-ms-encryption-scope`	Optioneel. Geeft het versleutelingsbereik aan dat moet worden gebruikt om de broninhoud te versleutelen. Deze header wordt ondersteund in versie 2019-02-02 of hoger.
`x-ms-lease-id:<ID>`	Vereist als de blob een actieve lease heeft. Als u deze bewerking wilt uitvoeren op een blob met een actieve lease, geeft u de geldige lease-id voor deze header op.
`x-ms-client-request-id`	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Blob Storage bewaken voor meer informatie.
`x-ms-blob-condition-maxsize`	Optionele voorwaardelijke header. De maximale lengte in bytes die is toegestaan voor de toevoeg-blob. Als de `Append Block From URL` bewerking ervoor zorgt dat de blob deze limiet overschrijdt of als de blobgrootte al groter is dan de waarde die in deze header is opgegeven, mislukt de aanvraag met een 412 (voorwaarde is mislukt).
`x-ms-blob-condition-appendpos`	Optionele voorwaardelijke header, die alleen voor de `Append Block from URL` bewerking wordt gebruikt. Een getal dat de byte offset aangeeft die moet worden vergeleken. `Append Block from URL` slaagt alleen als de toevoegpositie gelijk is aan dit getal. Als dat niet zo is, mislukt de aanvraag met een 412 (voorwaarde mislukt).

Deze bewerking ondersteunt het gebruik van aanvullende, voorwaardelijke headers om ervoor te zorgen dat de API alleen slaagt als aan een opgegeven voorwaarde wordt voldaan. Zie Voorwaardelijke headers opgeven voor Blob Storage-bewerkingen voor meer informatie.

Aanvraagheaders (door de klant verstrekte versleutelingssleutels)

Vanaf versie 2019-02-02 kunt u de volgende headers opgeven voor de aanvraag om een blob te versleutelen met een door de klant verstrekte sleutel. Versleuteling met een door de klant verstrekte sleutel (en de bijbehorende set headers) is optioneel.

Aanvraagheader	Beschrijving
`x-ms-encryption-key`	Vereist. De met Base64 gecodeerde AES-256-versleutelingssleutel.
`x-ms-encryption-key-sha256`	Vereist. De Base64-gecodeerde SHA256-hash van de versleutelingssleutel.
`x-ms-encryption-algorithm: AES256`	Vereist. Hiermee geeft u het algoritme te gebruiken voor versleuteling. De waarde van deze header moet zijn `AES256`.

Aanvraagbody

De aanvraagtekst bevat de inhoud van het blok.

Voorbeeldaanvraag

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"

Antwoord

Het antwoord bevat een HTTP-statuscode en een set antwoordheaders.

Statuscode

Een geslaagde bewerking retourneert statuscode 201 (Gemaakt). Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook extra standaard-HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader	Description
`Etag`	De `ETag` bevat een waarde tussen aanhalingstekens. De client gebruikt de waarde om voorwaardelijke `PUT` bewerkingen uit te voeren met behulp van de `If-Match` aanvraagheader.
`Last-Modified`	De datum/tijd waarop de blob het laatst is gewijzigd. De datumnotatie volgt RFC 1123. Zie Weergave van datum-tijdwaarden in kopteksten voor meer informatie. Bij een schrijfbewerking op de blob (inclusief updates voor de metagegevens of eigenschappen van de blob) wordt de laatste wijzigingstijd van de blob gewijzigd.
`Content-MD5`	Deze koptekst wordt geretourneerd, zodat de client de integriteit van de berichtinhoud kan controleren. Blob Storage berekent de waarde van deze header. Dit is niet noodzakelijkerwijs dezelfde waarde die is opgegeven in de aanvraagheaders. Voor versie 2019-02-02 of hoger wordt deze header alleen geretourneerd wanneer de aanvraag deze header heeft.
`x-ms-content-crc64`	Voor versie 2019-02-02 of hoger. Deze koptekst wordt geretourneerd, zodat de client de integriteit van de berichtinhoud kan controleren. Blob Storage berekent de waarde van deze header. Dit is niet noodzakelijkerwijs dezelfde waarde die is opgegeven in de aanvraagheaders. Deze header wordt geretourneerd wanneer de `x-ms-source-content-md5` header niet aanwezig is in de aanvraag.
`x-ms-request-id`	Deze header identificeert op unieke wijze de aanvraag die is gedaan en kan worden gebruikt voor het oplossen van problemen met de aanvraag.
`x-ms-version`	Geeft de versie van Blob Storage aan die wordt gebruikt om de aanvraag uit te voeren. Deze header wordt geretourneerd voor aanvragen die zijn gedaan in versie 2009-09-19 en hoger.
`Date`	Een UTC-datum/tijd-waarde die wordt gegenereerd door de service die de tijd aangeeft waarop het antwoord is geïnitieerd.
`x-ms-blob-append-offset`	Deze antwoordheader wordt alleen geretourneerd voor toevoegbewerkingen. Het retourneert de offset waarop het blok is doorgevoerd, in bytes.
`x-ms-blob-committed-block-count`	Het aantal vastgelegde blokken dat aanwezig is in de blob. U kunt dit gebruiken om te bepalen hoeveel extra toevoegingen er kunnen worden uitgevoerd.
`x-ms-request-server-encrypted: true/false`	Versie 2015-12-11 of hoger. De waarde van deze header wordt ingesteld op `true` als de inhoud van de aanvraag is versleuteld met behulp van het opgegeven algoritme. Anders wordt de waarde ingesteld op `false`.
`x-ms-encryption-key-sha256`	Versie 2019-02-02 of hoger. Deze header wordt geretourneerd als de aanvraag een door de klant verstrekte sleutel heeft gebruikt voor versleuteling. De client kan er vervolgens voor zorgen dat de inhoud van de aanvraag is versleuteld met behulp van de opgegeven sleutel.
`x-ms-encryption-scope`	Versie 2019-02-02 of hoger. Deze header wordt geretourneerd als de aanvraag een versleutelingsbereik heeft gebruikt. De client kan er vervolgens voor zorgen dat de inhoud van de aanvraag is versleuteld met behulp van het versleutelingsbereik.

Voorbeeldantwoord

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

Autorisatie

Autorisatie is vereist bij het aanroepen van een bewerking voor gegevenstoegang in Azure Storage. U kunt de Append Block From URL bewerking autoriseren zoals hieronder wordt beschreven.

De autorisatiegegevens in deze sectie zijn van toepassing op de kopieerbestemming. Zie de details voor de aanvraagheader voor meer informatie over het kopiëren van bronautorisatie x-ms-copy-source.

Azure Storage ondersteunt het gebruik van Microsoft Entra ID om aanvragen voor blobgegevens te autoriseren. Met Microsoft Entra ID kunt u op rollen gebaseerd toegangsbeheer van Azure (Azure RBAC) gebruiken om machtigingen te verlenen aan een beveiligingsprincipal. De beveiligingsprincipal kan een gebruiker, groep, toepassingsservice-principal of beheerde Azure-identiteit zijn. De beveiligingsprincipal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token te retourneren. Het token kan vervolgens worden gebruikt om een aanvraag voor de Blob-service te autoriseren.

Zie Toegang tot blobs autoriseren met Microsoft Entra ID voor meer informatie over autorisatie met behulp van Microsoft Entra ID.

Machtigingen

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra gebruiker, groep of service-principal om de Append Block From URL bewerking aan te roepen, en de minst bevoorrechte ingebouwde Azure RBAC-rol die deze actie omvat:

Azure RBAC-actie:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/add/action of Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
Ingebouwde rol met minimale bevoegdheden:Inzender voor opslagblobgegevens

Zie Een Azure-rol toewijzen voor toegang tot blobgegevens voor meer informatie over het toewijzen van rollen met behulp van Azure RBAC.

Een Shared Access Signature (SAS) biedt beveiligde gedelegeerde toegang tot resources in een opslagaccount. Met een SAS hebt u gedetailleerde controle over hoe een client toegang heeft tot gegevens. U kunt opgeven tot welke resource de client toegang heeft, welke machtigingen ze hebben voor deze resources en hoe lang de SAS geldig is.

De Append Block From URL bewerking ondersteunt drie typen handtekeningen voor gedeelde toegang: sas voor gebruikersdelegatie, service-SAS en account-SAS.

Als best practice voor beveiliging raden we u aan Microsoft Entra referenties te gebruiken in plaats van de sleutel van het opslagaccount, die gemakkelijker kan worden aangetast. Als voor uw toepassingsontwerp handtekeningen voor gedeelde toegang zijn vereist, gebruikt u Microsoft Entra referenties om, indien mogelijk, een SAS voor gebruikersdelegatie te maken.

Wanneer gedeelde sleuteltoegang niet is toegestaan voor het opslagaccount, is een service-SAS-token of een ACCOUNT-SAS-token niet toegestaan op een aanvraag voor Blob Storage. Zie Begrijpen hoe het niet toewijzen van gedeelde sleutel van invloed is op SAS-tokens voor meer informatie.

SAS voor gebruikersdelegatie

Een SAS voor gebruikersdelegatie wordt beveiligd met Microsoft Entra referenties en ook met de machtigingen die zijn opgegeven voor de SAS.

Voor het aanroepen van de Append Block From URL bewerking met behulp van een SAS-token dat is gedelegeerd aan een container of blob-resource, is de machtiging Toevoegen (a) of Schrijven (w) vereist als onderdeel van het SAS-token voor gebruikersdelegatie:

Zie Een SAS voor gebruikersdelegatie maken voor meer informatie over de SAS voor gebruikersdelegatie.

Service-SAS

Een service-SAS wordt beveiligd met de sleutel van het opslagaccount. Een service-SAS delegeert de toegang tot een resource in één Azure Storage-service, zoals blobopslag.

Zie Een service-SAS maken voor meer informatie over de service-SAS.

Account-SAS

Een account-SAS wordt beveiligd met de sleutel van het opslagaccount. Een account-SAS delegeert toegang tot resources in een of meer van de opslagservices. Alle bewerkingen die beschikbaar zijn via een service of gebruikersdelegatie-SAS zijn ook beschikbaar via een account-SAS.

In de volgende tabel ziet u het ondertekende resourcetype en de ondertekende machtigingen die moeten worden opgegeven bij het delegeren van toegang:

Bewerking	Ondertekende service	Ondertekend resourcetype	Ondertekende machtiging
Blok toevoegen vanuit URL	Blob (b)	Object (o)	(a) of schrijven (w) toevoegen

Zie Een account-SAS maken voor meer informatie over de account-SAS.

Opmerkingen

Append Block From URL uploadt een blok naar het einde van een bestaande toevoeg-blob. Het gegevensblok is onmiddellijk beschikbaar nadat de aanroep op de server is geslaagd. Er zijn maximaal 50.000 toevoegingen toegestaan voor elke toevoeg-blob, waarbij. Elk blok kan een andere grootte hebben.

In de volgende tabel worden de maximaal toegestane blok- en blobgrootten per serviceversie beschreven:

Serviceversie	Maximale blokgrootte (via `Append Block From URL`)	Maximale blobgrootte
Versie 2022-11-02 en hoger	100 MiB (preview)	Ongeveer 4,75 TiB (100 MiB × 50.000 blokken)
Versies ouder dan 2022-11-02	4 MiB	Ongeveer 195 gibibytes (GiB) (4 MiB × 50.000 blokken)

In versie 2020-10-02 en hoger wordt Microsoft Entra ID autorisatie ondersteund voor de bron van de kopieerbewerking.

Append Block From URL slaagt alleen als de blob al bestaat.

Blobs die zijn geüpload met behulp van Append Block From URL , maken geen blok-id's beschikbaar, dus u kunt Blokkeringslijst ophalen niet aanroepen voor een toevoeg-blob. Dit resulteert in een fout.

U kunt de volgende optionele, voorwaardelijke headers opgeven voor de aanvraag:

x-ms-blob-condition-appendpos: U kunt deze header instellen op een byte-offset waarbij de client verwacht het blok toe te voegen. De aanvraag slaagt alleen als de huidige offset overeenkomt met die is opgegeven door de client. Anders mislukt de aanvraag met foutcode 412 (voorwaarde mislukt).

Clients die één writer gebruiken, kunnen deze header gebruiken om te bepalen of een Append Block From URL bewerking is geslaagd, ondanks een netwerkfout.
x-ms-blob-condition-maxsize: clients kunnen deze header gebruiken om ervoor te zorgen dat toevoegbewerkingen de blob-grootte niet groter maken dan een verwachte maximale grootte in bytes. Als de voorwaarde mislukt, mislukt de aanvraag met foutcode 412 (voorwaarde mislukt).

Als u probeert een blok te uploaden dat groter is dan de toegestane grootte, retourneert de service HTTP-foutcode 413 (Aanvraagentiteit te groot). De service retourneert ook aanvullende informatie over de fout in het antwoord, waaronder de maximale blokgrootte die is toegestaan in bytes. Als u meer dan 50.000 blokken probeert te uploaden, retourneert de service foutcode 409 (Conflict).

Als de blob een actieve lease heeft, moet de client een geldige lease-id voor de aanvraag opgeven om een blok naar de blob te schrijven. Als de client geen lease-id opgeeft of een ongeldige lease-id opgeeft, retourneert Blob Storage foutcode 412 (voorwaarde mislukt). Als de client een lease-id opgeeft, maar de blob geen actieve lease heeft, retourneert de service foutcode 412.

Als u een bestaande blok- of pagina-blob aanroept Append Block From URL , retourneert de service foutcode 409 (Conflict). Als u aanroept Append Block From URL op een niet-bestaande blob, retourneert de service foutcode 404 (Niet gevonden).

Dubbele of vertraagde toevoegingen voorkomen

In één schrijverscenario kan de client dubbele toevoegingen of vertraagde schrijfbewerkingen voorkomen door de x-ms-blob-condition-appendpos voorwaardelijke header te gebruiken om de huidige verschuiving te controleren. De client kan ook duplicaten of vertragingen voorkomen door de ETag voorwaardelijk te controleren met behulp van If-Match.

In een scenario met meerdere schrijfbewerkingen kan elke client voorwaardelijke headers gebruiken. Dit is mogelijk niet optimaal voor de prestaties. Voor de hoogste gelijktijdige toevoegdoorvoer moeten toepassingen redundante toevoegingen en vertraagde toevoegingen in hun toepassingslaag verwerken. Toepassingen kunnen bijvoorbeeld tijdvakken of reeksnummers toevoegen aan de gegevens die worden toegevoegd.

Zie prijzen voor Azure Blob Storage voor meer informatie over prijzen voor de opgegeven factureringscategorie.

Billing

Prijsaanvragen kunnen afkomstig zijn van clients die gebruikmaken van Blob Storage-API's, rechtstreeks via de Blob Storage REST API of vanuit een Azure Storage-clientbibliotheek. Met deze aanvragen worden kosten per transactie in rekening gebracht. Het type transactie is van invloed op de manier waarop de rekening in rekening wordt gebracht. Leestransacties worden bijvoorbeeld toegevoegd aan een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor Append Block From URL aanvragen op basis van het type opslagaccount:

Bewerking	Type opslagaccount	Factureringscategorie
Blok van URL toevoegen (doelaccount¹)	Premium-blok-blob Standard v2 voor algemeen gebruik Standard v1 voor algemeen gebruik	Schrijfbewerkingen
Blok van URL toevoegen (bronaccount²)	Premium-blok-blob Standard v2 voor algemeen gebruik Standard v1 voor algemeen gebruik	Leesbewerkingen

¹Het doelaccount wordt in rekening gebracht voor één transactie om de schrijfbewerking te initiëren.
²Voor het bronaccount wordt één transactie uitgevoerd voor elke leesaanvraag naar de bron.