Delen via

Blok toevoegen

De Append Block operatie commit een nieuw datablok aan het einde van een bestaande append blob.

De Append Block operatie is alleen toegestaan als de blob is aangemaakt met x-ms-blob-type gezet op AppendBlob. Append Block wordt alleen ondersteund op versie 2015-02-21 of later.

Aanvraag

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

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

Wanneer je een verzoek doet aan de geëmuleerde opslagservice, geef dan de hostnaam van de emulator en de Azure Blob Storage-poort op als 127.0.0.1:10000, gevolgd door de naam van het geëmuleerde opslagaccount.

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

Zie De Azurite-emulator gebruiken voor lokale Azure Storage-ontwikkeling voor meer informatie.

URI Parameters

Kenmerk Description
timeout Optional. De timeout parameter wordt uitgedrukt in seconden. Voor meer informatie, zie Time-outs instellen voor Azure Blob Storage operaties.

Headers aanvragen

In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.

Header van het verzoek Description
Authorization Verplicht. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening op. Zie Autorize requests to Azure Storage voor meer informatie.
Date of x-ms-date Verplicht. Hiermee geeft u de Coordinated Universal Time (UTC) voor de aanvraag. Zie Aanvragen autoriseren voor Azure Storagevoor meer informatie.
x-ms-version Vereist voor alle geautoriseerde verzoeken. Hiermee geeft u de versie van de bewerking die moet worden gebruikt voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
Content-Length Verplicht. De lengte van de blokinhoud in bytes. De blokgrootte moet kleiner zijn dan of gelijk aan 100 MiB (preview) voor versie 2022-11-02 en later. Zie de sectie Opmerkingen voor limieten in oudere versies.

Wanneer de lengte niet wordt opgegeven, mislukt de bewerking met statuscode 411 (Vereiste Lengte).
Content-MD5 Optional. Een MD5-hash van de blokinhoud. Deze hash wordt gebruikt om de integriteit van het blok tijdens transport te verifiëren. Wanneer deze header wordt gespecificeerd, vergelijkt de opslagservice de hash van de inhoud die is aangekomen, met deze headerwaarde.

Let op dat deze MD5-hash niet bij de blob wordt opgeslagen.

Als de twee hashes niet overeenkomen, zal de operatie falen met foutcode 400 (Bad Request).
x-ms-content-crc64 Optional. Een CRC64-hash van de inhoud van het toegevoegde blok. Deze hash wordt gebruikt om de integriteit van het appenblok tijdens transport te verifiëren. Wanneer deze header wordt gespecificeerd, vergelijkt de opslagservice de hash van de inhoud die is aangekomen, met deze headerwaarde.

Let op: deze CRC64-hash wordt niet samen met de blob opgeslagen.

Als de twee hashes niet overeenkomen, zal de operatie falen met foutcode 400 (Bad Request).

Als beide Content-MD5 en x-ms-content-crc64 headers aanwezig zijn, zal het verzoek falen met foutcode 400.

Deze header wordt ondersteund in versies 2019-02-02 of later.
x-ms-encryption-scope Optional. Geeft het versleutelingsbereik aan dat moet worden gebruikt om de inhoud van de aanvraag te versleutelen. Deze header wordt ondersteund in versies 2019-02-02 of later.
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 Optional. Biedt een door de client gegenereerde, ondoorzichtige waarde met een tekenlimiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie wordt 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 conditionele header. Specificeert de maximale lengte in bytes die is toegestaan voor de toegevoegde blob. Als de Append Block operatie ervoor zorgt dat de blob die limiet overschrijdt, of als de blobgrootte al groter is dan de waarde die in deze header is gespecificeerd, mislukt het verzoek met foutcode 412 (Precondition Failed).
x-ms-blob-condition-appendpos Optionele conditionele header, alleen gebruikt voor de Append Block bewerking. Een getal geeft de byte-offset aan die vergelijkbaar moet worden. Append Block slaagt alleen als de toegevoegde positie gelijk is aan dit getal. Als dat niet zo is, faalt het verzoek met foutcode 412 (Precondition Failed).

Deze operatie ondersteunt het gebruik van extra conditionele headers om ervoor te zorgen dat de API alleen slaagt als aan een gespecificeerde voorwaarde wordt voldaan. Voor meer informatie, zie Specificering van conditionele headers voor Azure Blob Storage operaties.

Request-headers (door de klant verstrekte encryptiesleutels)

Vanaf versie 2019-02-02 kun je de volgende headers specificeren op het verzoek 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.

Header van het verzoek Description
x-ms-encryption-key Verplicht. De door Base64 gecodeerde AES-256 encryptiesleutel.
x-ms-encryption-key-sha256 Verplicht. De door Base64 gecodeerde SHA256-hash van de encryptiesleutel.
x-ms-encryption-algorithm: AES256 Verplicht. Specificeert het algoritme dat voor encryptie moet worden gebruikt. De waarde van deze header moet zijn AES256.

Verzoekheaders (gestructureerde body)

Vanaf versie 2025-01-05 kunnen de volgende headers op het verzoek worden gespecificeerd om gebruik te maken van het gestructureerde lichaamsformaat.

Header van het verzoek Description
Content-Length Verplicht. Moet de lengte van het gecodeerde verzoek zijn (niet alleen de lengte van de blokinhoud).

Als de waarde van de header niet overeenkomt met de verwachte lengte van het gecodeerde verzoek, faalt de bewerking met foutcode 400 (Bad Request).
x-ms-structured-body Verplicht. Moet worden opgenomen als het berichtformaat is gestructureerd. De waarde van deze header bevat de versie en eigenschappen van het berichtschema.

Momenteel wordt alleen de waarde ondersteund , XSM/1.0; properties=crc64wat aangeeft dat het verzoek crc64-checksumsegmenten gebruikt in het gecodeerde bericht. Als de waarde hier niet overeenkomt, faalt de bewerking met foutcode 400 (Bad Request). Het verzoek faalt ook als de inhoud die in het verzoek wordt verstrekt niet overeenkomt met de opgegeven checksum voor een bepaald segment.
x-ms-structured-content-length Verplicht. Moet worden opgenomen als het berichtformaat is gestructureerd. De waarde van deze header is de lengte van de blokinhoud en zal altijd kleiner zijn dan de Content-Length headerwaarde vanwege berichtcodering.

Als de waarde van de header niet overeenkomt met de lengte van de blokinhoud die in het verzoek wordt gegeven, mislukt de operatie met foutcode 400 (Bad Request).

Inhoud van het verzoek

De verzoekbody 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: 2015-02-21  
x-ms-date: <date>  
x-ms-blob-condition-appendpos: 2097152  
x-ms-blob-condition-maxsize: 4194304  
Authorization: SharedKey myaccount:J4ma1VuFnlJ7yfk/Gu1GxzbfdJloYmBPWlfhZ/xn7GI=  
Content-Length: 1048  
If-Match: "0x8CB172A360EC34B"

Reactie

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

Statuscode

Een geslaagde bewerking retourneert statuscode 201 (gemaakt).

Zie Status en foutcodesvoor meer informatie over statuscodes.

Antwoordkopteksten

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

Antwoordheader Description
ETag De ETag bevat een waarde in aanhalingstekens. De client kan de waarde gebruiken om conditionele PUT bewerkingen uit te voeren door gebruik te maken van de If-Match requestheader.
Last-Modified De datum en tijd waarop de blob voor het laatst is aangepast. Het datumformaat volgt RFC 1123. Voor meer informatie, zie Representatie van datum-tijdwaarden in headers.

Elke schrijfoperatie op de blob (inclusief updates van de metadata of eigenschappen van de blob) verandert de laatst gewijzigde tijd van de blob.
Content-MD5 Deze header wordt geretourneerd, zodat de client kan controleren op integriteit van berichtinhoud. De waarde van deze header wordt berekend door Blob Storage. Het is niet per se dezelfde waarde als gespecificeerd in de requestheaders. Voor versies 2019-02-02 of later wordt deze header alleen teruggegeven wanneer het verzoek deze header heeft.
x-ms-content-crc64 Voor versies 2019-02-02 of later wordt deze header teruggegeven zodat de client kan controleren op de integriteit van de berichtinhoud. De waarde van deze header wordt berekend door Blob Storage. Het is niet per se dezelfde waarde als gespecificeerd in de requestheaders.

Deze header wordt teruggegeven wanneer de Content-md5 header niet aanwezig is in het verzoek.
x-ms-request-id Deze header identificeert de aanvraag die is gemaakt 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 ingediend tegen versie 2009-09-19 en hoger.
Date Een UTC-datum/tijd-waarde die de tijd aangeeft waarop het antwoord is gestart. De service genereert deze waarde.
x-ms-blob-append-offset Deze antwoordheader wordt alleen geretourneerd voor toevoegbewerkingen. Hiermee wordt de offset geretourneerd waarop het blok is doorgevoerd, in bytes.
x-ms-blob-committed-block-count Het aantal vastgelegde blokken dat aanwezig is in de blob. Je kunt dit gebruiken om te bepalen hoeveel extra toevoegingen je kunt doen.
x-ms-request-server-encrypted: true/false Versie 2015-12-11 of later. De waarde van deze header wordt ingesteld op true als de inhoud van het verzoek succesvol is versleuteld met het opgegeven algoritme. Anders wordt de waarde gezet op false.
x-ms-encryption-key-sha256 Versie 2019-02-02 of later. Deze header wordt teruggegeven als het verzoek een door de klant verstrekte sleutel voor encryptie gebruikte. De client kan vervolgens zorgen dat de inhoud van het verzoek succesvol is versleuteld door gebruik te maken van de meegeleverde sleutel.
x-ms-encryption-scope Versie 2019-02-02 of later. Deze header wordt teruggegeven als het verzoek een encryptiescope gebruikte. De client kan vervolgens zorgen dat de inhoud van het verzoek succesvol is versleuteld door gebruik te maken van de encryptiescope.
x-ms-client-request-id U kunt deze header gebruiken om problemen met aanvragen en bijbehorende antwoorden op te lossen. De waarde van deze header is gelijk aan de waarde van de x-ms-client-request-id header als deze aanwezig is in het verzoek. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de x-ms-client-request-id header niet aanwezig is in het verzoek, is deze header niet aanwezig in het antwoord.
x-ms-structured-body Teruggestuurd als het verzoek als een gestructureerd body request is verwerkt. De waarde van deze header is gelijk aan de waarde die in het verzoek wordt verzonden, die momenteel moet zijn XSM/1.0; properties=crc64.

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

Authorization

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

Belangrijk

Microsoft raadt aan om 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 beveiligingsprincipaal. De beveiligingsprincipaal kan een door een gebruiker, groep, toepassingsservice-principal of door Azure beheerde identiteit zijn. De beveiligingsprincipaal wordt geverifieerd door Microsoft Entra ID om een OAuth 2.0-token terug te geven. Het token kan vervolgens worden gebruikt om een aanvraag te autoriseren voor de Blob-service.

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

Permissions

Hieronder vindt u de RBAC-actie die nodig is voor een Microsoft Entra-gebruiker, groep, beheerde identiteit of service-principal om de Append Block-bewerking aan te roepen, en de minst bevoorrechte ingebouwde Azure RBAC-rol 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 uploadt een blok aan het einde van een bestaande appende blob. Het datablok is direct beschikbaar nadat de oproep op de server succesvol is. Maximaal 50.000 appends zijn toegestaan voor elke append blob. Elke blok kan van verschillende grootte zijn.

De volgende tabel beschrijft de maximaal toegestane blok- en blobgroottes, per serviceversie:

Serviceversie Maximale blokgrootte (via Append Block) Maximale blobgrootte
Versie 2022-11-02 en later 100 MiB (Preview) Ongeveer 4,75 TiB (100 MiB × 50.000 blokken)
Versies van vóór 2022-11-02 4 MiB Ongeveer 195 gibibyte (GiB) (4 MiB × 50.000 blokken)

Append Block slaagt alleen als de blob al bestaat.

Blobs die via Append Block gebruik worden geüpload, maken geen blok-ID's zichtbaar. Je kunt Get Block List niet aanroepen tegen een append blob. Dit resulteert in een fout.

Je kunt de volgende optionele, voorwaardelijke headers op het verzoek opgeven:

  • x-ms-blob-condition-appendpos: Je kunt deze header instellen op een byte offset waarbij de client verwacht het blok toe te voegen. Het verzoek slaagt alleen als de huidige offset overeenkomt met die van de client. Anders mislukt het verzoek met foutcode 412 (Precondition Failed).

    Clients die één enkele schrijver gebruiken, kunnen deze header gebruiken om te bepalen of een Append Block operatie is geslaagd, ondanks een netwerkstoring.

  • x-ms-blob-condition-maxsize: Clients kunnen deze header gebruiken om ervoor te zorgen dat append-operaties de blobgrootte niet boven de verwachte maximale bytegrootte vergroten. Als de voorwaarde faalt, faalt het verzoek met foutcode 412 (Precondition Failed).

Als je probeert een blok te uploaden dat groter is dan de toegestane grootte, geeft de dienst foutcode 413 (Request Entity Too Large) terug. De service geeft ook aanvullende informatie terug over de fout in het antwoord, waaronder de maximaal toegestane blokgrootte in bytes. Als je probeert meer dan 50.000 blokken te uploaden, geeft de dienst foutcode 409 (Conflict) terug.

Als de blob een actieve lease heeft, moet de client een geldige lease-ID op het verzoek opgeven om een blok naar de blob te kunnen schrijven. Als de client geen lease-ID opgeeft, of een ongeldige lease-ID opgeeft, geeft Blob Storage foutcode 412 (Precondition Failed) terug. Als de client een lease-ID opgeeft, maar de blob geen actieve lease heeft, geeft Blob Storage ook foutcode 412 terug.

Als je een bestaande blok- of pagina-blob aanroept Append Block , geeft de service een conflictfout terug. Als je een niet-bestaande blob aanroept Append Block , geeft de service ook een foutmelding terug.

Vermijd dubbele of vertraagde toevoegingen

In een scenario met één schrijver kan de client dubbele toevoegingen of vertraagde schrijfacties vermijden door de *x-ms-blob-condition-appendpos conditionele header te gebruiken om de huidige offset te controleren. De client kan ook duplicaten of vertragingen vermijden door de ETag conditionally te controleren, door gebruik te maken van If-Match.

In een scenario met meerdere schrijvers kan elke client conditionele headers gebruiken, maar dit is mogelijk niet optimaal voor de prestaties. Voor de hoogste gelijktijdige append-doorvoer moeten applicaties redundante appends en vertraagde appens in de applicatielaag afhandelen. De applicatie kan bijvoorbeeld epochs of sequentienummers toevoegen aan de gegevens die worden toegevoegd.

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. Voor deze verzoeken worden kosten per transactie in rekening gebracht. Het type transactie is van invloed op de manier waarop de kosten in rekening worden gebracht op de rekening. Leestransacties worden bijvoorbeeld toegerekend aan een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor aanvragen op Append Block basis van het type opslagaccount:

Operation Type opslagaccount Facturering categorie
Blok toevoegen Premium blok-blob
Standaard algemeen gebruik v2
Standaard algemeen gebruik v1		 Schrijfbewerkingen

Append Blocks ondersteunen geen objectniveau-tiering, maar leiden hun toegangslaag af uit de standaard accounttoegangstier en worden dienovereenkomstig gefactureerd. Voor meer informatie over de standaard accounttier-instelling, zie Access-tiers voor blobdata - Azure Storage.

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

  • Last updated on