Delen via

Toevoegblok

  • Artikel

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

De Append Block bewerking is alleen toegestaan als de blob is gemaakt met x-ms-blob-type ingesteld op AppendBlob. Append Block wordt alleen ondersteund in versie 2015-02-21 of hoger.

Aanvraag

U kunt de Append Block 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 indient voor de geëmuleerde opslagservice, 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 timeout parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure 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. 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 voor Azure Storage autoriseren 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. De lengte van de blokinhoud in bytes. De blokgrootte moet kleiner zijn dan of gelijk zijn aan 100 MiB (preview) voor versie 2022-11-02 en hoger. Zie de sectie Opmerkingen voor limieten in oudere versies.

Wanneer de lengte niet is opgegeven, mislukt de bewerking met de statuscode 411 (Lengte vereist).
Content-MD5 Optioneel. Een MD5-hash van de blokinhoud. Deze hash wordt gebruikt om de integriteit van het blok tijdens het transport te controleren. Wanneer deze header is opgegeven, vergelijkt de opslagservice de hash van de inhoud die is aangekomen 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-content-crc64 Optioneel. Een CRC64-hash van de inhoud van het toevoegblok. Deze hash wordt gebruikt om de integriteit van het toevoegblok tijdens het transport te controleren. Wanneer deze header is opgegeven, vergelijkt de opslagservice de hash van de inhoud die is aangekomen 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 als Content-MD5x-ms-content-crc64 headers aanwezig zijn, mislukt de aanvraag met foutcode 400.

Deze header wordt ondersteund in versies 2019-02-02 of hoger.
x-ms-encryption-scope Optioneel. 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 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. Hiermee geeft u de maximale lengte in bytes die zijn toegestaan voor de toevoeg-blob. Als de Append Block 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 foutcode 412 (voorwaarde is mislukt).
x-ms-blob-condition-appendpos Optionele voorwaardelijke header, alleen gebruikt voor de Append Block bewerking. Een getal geeft de byte offset aan die moet worden vergeleken. Append Block slaagt alleen als de toevoegpositie gelijk is aan dit getal. Als dat niet zo is, mislukt de aanvraag met foutcode 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 Azure 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 opgegeven 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: 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"

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 kan de waarde gebruiken om voorwaardelijke PUT bewerkingen uit te voeren met behulp van de If-Match aanvraagheader.
Last-Modified De datum en 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. De waarde van deze header wordt berekend door Blob Storage. Dit is niet noodzakelijkerwijs dezelfde waarde die is opgegeven in de aanvraagheaders. Voor versies 2019-02-02 of hoger wordt deze header alleen geretourneerd wanneer de aanvraag deze header heeft.
x-ms-content-crc64 Voor versies 2019-02-02 of hoger wordt deze header geretourneerd, zodat de client de integriteit van de berichtinhoud kan controleren. De waarde van deze header wordt berekend door Blob Storage. Dit is niet noodzakelijkerwijs dezelfde waarde die is opgegeven in de aanvraagheaders.

Deze header wordt geretourneerd wanneer de 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 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. 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.
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 de aanvraag. De waarde is maximaal 1024 zichtbare ASCII-tekens. Als de x-ms-client-request-id header niet aanwezig is in de aanvraag, is deze header niet aanwezig in het antwoord.

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 bewerking autoriseren zoals hieronder wordt beschreven.

Belangrijk

Microsoft raadt het gebruik van Microsoft Entra ID met beheerde identiteiten aan om aanvragen voor Azure Storage te autoriseren. Microsoft Entra ID biedt superieure beveiliging en gebruiksgemak in vergelijking met autorisatie met 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 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, beheerde identiteit of service-principal om de Append Block 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 uploadt een blok aan het einde van een bestaande toevoeg-blob. Het gegevensblok is onmiddellijk beschikbaar nadat de aanroep is geslaagd op de server. Er zijn maximaal 50.000 appends toegestaan voor elke toevoeg-blob. 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) 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)

Append Block slaagt alleen als de blob al bestaat.

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

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

  • 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 de verschuiving die is opgegeven door de client. Anders mislukt de aanvraag met foutcode 412 (Voorwaarde is mislukt).

    Clients die één writer gebruiken, kunnen deze header gebruiken om te bepalen of een Append Block bewerking is geslaagd, ondanks een netwerkfout.

  • x-ms-blob-condition-maxsize: clients kunnen deze header gebruiken om ervoor te zorgen dat toevoegbewerkingen de blobgrootte 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 foutcode 413 (Aanvraagentiteit is 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 is mislukt). Als de client een lease-id opgeeft, maar de blob geen actieve lease heeft, retourneert Blob Storage ook foutcode 412.

Als u een bestaande blok- of pagina-blob aanroept Append Block , retourneert de service een conflictfout. Als u aanroept Append Block op een niet-bestaande blob, retourneert de service ook een fout.

Dubbele of vertraagde toevoegingen voorkomen

In een scenario met één schrijver 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, maar dit is mogelijk niet optimaal voor de prestaties. Voor de hoogste gelijktijdige toevoegdoorvoer moeten toepassingen redundante toevoegingen en vertraagde toevoegingen in de toepassingslaag verwerken. De toepassing kan bijvoorbeeld tijdvakken of volgnummers 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. 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 hebben bijvoorbeeld een andere factureringscategorie dan schrijftransacties. In de volgende tabel ziet u de factureringscategorie voor Append Block aanvragen op basis van het type opslagaccount:

Bewerking Type opslagaccount Factureringscategorie
Toevoegblok Premium blok-blob
Standaard v2 voor algemeen gebruik
Standaard v1 voor algemeen gebruik		 Schrijfbewerkingen

Toevoegblokken bieden geen ondersteuning voor lagen op objectniveau, maar afleiden hun toegangslaag uit de standaardinstelling voor toegangslagen voor accounts en worden dienovereenkomstig gefactureerd. Zie Toegangslagen voor blobgegevens - Azure Storage voor meer informatie over de instelling van de standaardaccountlaag.

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