Delen via

Blok toevoegen vanuit URL

  • Artikel

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 aanvraagbody 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.

Elke schrijfbewerking op de blob (inclusief updates voor de metagegevens of eigenschappen van de blob) wijzigt de laatste wijzigingstijd van de blob.
Content-MD5 Deze koptekst wordt geretourneerd, zodat de client de integriteit van de berichtinhoud kan controleren. Blob Storage berekent de waarde van deze header. Het 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. Het 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 op basis van versie 2009-09-19 en hoger.
Date Een UTC-datum/tijd-waarde die wordt gegenereerd door de service die aangeeft op welk tijdstip het antwoord is gestart.
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 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 voor versleuteling heeft gebruikt. 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 autorisatie van de kopieerbron x-ms-copy-source.

Belangrijk

Microsoft raadt aan Microsoft Entra ID met beheerde identiteiten te gebruiken om aanvragen voor Azure Storage te autoriseren. Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak in vergelijking met autorisatie van gedeelde sleutels.

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 door Azure beheerde 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 behulp van 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, beheerde identiteit of service-principal om de Append Block From URL bewerking aan te roepen, en de ingebouwde Azure RBAC-rol met de minste bevoegdheden die deze actie omvat:

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

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 (doelaccount1) Premium-blok-blob
Standard v2 voor algemeen gebruik
Standard v1 voor algemeen gebruik		 Schrijfbewerkingen
Blok van URL toevoegen (bronaccount2) Premium-blok-blob
Standard v2 voor algemeen gebruik
Standard v1 voor algemeen gebruik		 Leesbewerkingen

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