Lägg till block

  • Artikel

Åtgärden Append Block checkar in ett nytt datablock i slutet av en befintlig tilläggsblob.

Åtgärden Append Block tillåts endast om bloben skapades med x-ms-blob-type inställd på AppendBlob. Append Block stöds endast i version 2015-02-21 eller senare.

Förfrågan

Du kan skapa begäran på Append Block följande sätt. HTTPS rekommenderas. Ersätt myaccount med namnet på ditt lagringskonto.

URI för PUT-metodbegäran HTTP-version
https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=appendblock HTTP/1.1

När du gör en begäran mot den emulerade lagringstjänsten anger du emulatorns värdnamn och Azure Blob Storage port som 127.0.0.1:10000, följt av namnet på det emulerade lagringskontot.

URI för PUT-metodbegäran HTTP-version
http://127.0.0.1:10000/devstoreaccount1/mycontainer/myblob?comp=appendblock HTTP/1.1

Mer information finns i Använda Azurite-emulatorn för lokal Azure Storage-utveckling.

URI-parametrar

Parameter Beskrivning
timeout Valfritt. Parametern timeout uttrycks i sekunder. Mer information finns i Ange tidsgränser för Azure Blob Storage åtgärder.

Begärandehuvuden

I följande tabell beskrivs obligatoriska och valfria begärandehuvuden.

Begärandehuvud Beskrivning
Authorization Krävs. Anger auktoriseringsschema, kontonamn och signatur. Mer information finns i Auktorisera begäranden till Azure Storage .
Date eller x-ms-date Krävs. Anger Coordinated Universal Time (UTC) för begäran. Mer information finns i Auktorisera begäranden till Azure Storage.
x-ms-version Krävs för alla auktoriserade begäranden. Anger vilken version av åtgärden som ska användas för den här begäran. Mer information finns i Versionshantering för Azure Storage-tjänsterna.
Content-Length Krävs. Längden på blockinnehållet i byte. Blockstorleken måste vara mindre än eller lika med 100 MiB (förhandsversion) i storlek för version 2022-11-02 och senare. Se avsnittet Kommentarer för begränsningar i äldre versioner.

När längden inte anges misslyckas åtgärden med statuskoden 411 (längd krävs).
Content-MD5 Valfritt. En MD5-hash för blockinnehållet. Den här hashen används för att verifiera blockets integritet under transporten. När det här huvudet anges jämför lagringstjänsten hash-värdet för det innehåll som har anlänt med det här rubrikvärdet.

Observera att denna MD5-hash inte lagras med bloben.

Om de två hashvärdena inte matchar misslyckas åtgärden med felkoden 400 (felaktig begäran).
x-ms-content-crc64 Valfritt. En CRC64-hash för tilläggets blockinnehåll. Den här hashen används för att verifiera integriteten för tilläggsblocket under transporten. När det här huvudet anges jämför lagringstjänsten hash-värdet för det innehåll som har anlänt med det här rubrikvärdet.

Observera att crc64-hashen inte lagras med bloben.

Om de två hashvärdena inte matchar misslyckas åtgärden med felkoden 400 (felaktig begäran).

Om både Content-MD5 och x-ms-content-crc64 huvuden finns misslyckas begäran med felkoden 400.

Det här huvudet stöds i versionerna 2019-02-02 eller senare.
x-ms-encryption-scope Valfritt. Anger krypteringsomfånget som ska användas för att kryptera innehållet i begäran. Det här huvudet stöds i versionerna 2019-02-02 eller senare.
x-ms-lease-id:<ID> Krävs om bloben har ett aktivt lån. Om du vill utföra den här åtgärden på en blob med ett aktivt lån anger du det giltiga låne-ID:t för det här huvudet.
x-ms-client-request-id Valfritt. Tillhandahåller ett klientgenererat, täckande värde med en teckengräns på 1 kibibyte (KiB) som registreras i loggarna när loggningen har konfigurerats. Vi rekommenderar starkt att du använder det här huvudet för att korrelera aktiviteter på klientsidan med begäranden som servern tar emot. Mer information finns i Övervaka Azure Blob Storage.
x-ms-blob-condition-maxsize Valfritt villkorsstyrt huvud. Anger den maximala längden i byte som tillåts för tilläggsbloben. Append Block Om åtgärden gör att bloben överskrider den gränsen, eller om blobstorleken redan är större än det värde som anges i det här huvudet, misslyckas begäran med felkoden 412 (villkoret misslyckades).
x-ms-blob-condition-appendpos Valfritt villkorshuvud som endast används för åtgärden Append Block . Ett tal anger byteförskjutningen som ska jämföras. Append Block lyckas bara om tilläggspositionen är lika med det här talet. Om det inte är det misslyckas begäran med felkoden 412 (villkoret misslyckades).

Den här åtgärden stöder användning av ytterligare villkorsstyrda rubriker för att säkerställa att API:et endast lyckas om ett angivet villkor uppfylls. Mer information finns i Ange villkorsstyrda rubriker för Azure Blob Storage åtgärder.

Begärandehuvuden (krypteringsnycklar som tillhandahålls av kunden)

Från och med version 2019-02-02 kan du ange följande rubriker på begäran för att kryptera en blob med en nyckel som tillhandahålls av kunden. Kryptering med en nyckel som tillhandahålls av kunden (och motsvarande uppsättning rubriker) är valfri.

Begärandehuvud Beskrivning
x-ms-encryption-key Krävs. Den Base64-kodade AES-256-krypteringsnyckeln.
x-ms-encryption-key-sha256 Krävs. Den Base64-kodade SHA256-hashen för krypteringsnyckeln.
x-ms-encryption-algorithm: AES256 Krävs. Anger vilken algoritm som ska användas för kryptering. Värdet för det här huvudet måste vara AES256.

Begärandetext

Begärandetexten innehåller innehållet i blocket.

Exempelbegäran

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"

Svarsåtgärder

Svaret innehåller en HTTP-statuskod och en uppsättning svarshuvuden.

Statuskod

En lyckad åtgärd returnerar statuskoden 201 (skapad).

Information om statuskoder finns i Status och felkoder.

Svarshuvuden

Svaret för den här åtgärden innehåller följande rubriker. Svaret kan också innehålla ytterligare standard-HTTP-huvuden. Alla standardhuvuden överensstämmer med HTTP/1.1-protokollspecifikationen.

Svarsrubrik Description
ETag ETag Innehåller ett värde inom citattecken. Klienten kan använda värdet för att utföra villkorsstyrda PUT åtgärder med hjälp av begärandehuvudet If-Match .
Last-Modified Datum och tid då bloben senast ändrades. Datumformatet följer RFC 1123. Mer information finns i Representation av datum-tidsvärden i rubriker.

Alla skrivåtgärder på bloben (inklusive uppdateringar av blobens metadata eller egenskaper) ändrar blobens senast ändrade tid.
Content-MD5 Det här huvudet returneras så att klienten kan söka efter meddelandeinnehållsintegritet. Värdet för det här huvudet beräknas av Blob Storage. Det är inte nödvändigtvis samma värde som anges i begärandehuvudena. För versionerna 2019-02-02 eller senare returneras det här huvudet endast när begäran har det här huvudet.
x-ms-content-crc64 För versionerna 2019-02-02 eller senare returneras det här huvudet så att klienten kan söka efter meddelandets innehållsintegritet. Värdet för det här huvudet beräknas av Blob Storage. Det är inte nödvändigtvis samma värde som anges i begärandehuvudena.

Det här huvudet returneras när Content-md5 rubriken inte finns i begäran.
x-ms-request-id Det här huvudet identifierar unikt den begäran som gjordes och kan användas för att felsöka begäran.
x-ms-version Anger vilken version av Blob Storage som används för att köra begäran. Det här huvudet returneras för begäranden mot version 2009-09-19 och senare.
Date Ett UTC-datum/tid-värde som anger den tid då svaret initierades. Tjänsten genererar det här värdet.
x-ms-blob-append-offset Det här svarshuvudet returneras endast för tilläggsåtgärder. Den returnerar förskjutningen som blocket checkades in med i byte.
x-ms-blob-committed-block-count Antalet bekräftade block som finns i bloben. Du kan använda detta för att styra hur många fler tillägg som kan göras.
x-ms-request-server-encrypted: true/false Version 2015-12-11 eller senare. Värdet för det här huvudet anges till true om innehållet i begäran har krypterats med hjälp av den angivna algoritmen. Annars är värdet inställt på false.
x-ms-encryption-key-sha256 Version 2019-02-02 eller senare. Det här huvudet returneras om begäran använde en kundtilldelad nyckel för kryptering. Klienten kan sedan se till att innehållet i begäran har krypterats med hjälp av den angivna nyckeln.
x-ms-encryption-scope Version 2019-02-02 eller senare. Det här huvudet returneras om begäran använde ett krypteringsomfång. Klienten kan sedan se till att innehållet i begäran har krypterats med hjälp av krypteringsomfånget.
x-ms-client-request-id Du kan använda det här huvudet för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet för x-ms-client-request-id huvudet om det finns i begäran. Värdet är högst 1 024 synliga ASCII-tecken. x-ms-client-request-id Om rubriken inte finns i begäran finns inte det här huvudet i svaret.

Exempelsvar

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

Auktorisering

Auktorisering krävs när du anropar en dataåtkomståtgärd i Azure Storage. Du kan auktorisera åtgärden enligt beskrivningen Append Block nedan.

Azure Storage stöder användning av Azure Active Directory (Azure AD) för att auktorisera begäranden till blobdata. Med Azure AD kan du använda rollbaserad åtkomstkontroll i Azure (Azure RBAC) för att bevilja behörigheter till ett säkerhetsobjekt. Säkerhetsobjektet kan vara en användare, grupp, programtjänstens huvudnamn eller en hanterad Azure-identitet. Säkerhetsobjektet autentiseras av Azure AD för att returnera en OAuth 2.0-token. Token kan sedan användas för att auktorisera en begäran mot Blob-tjänsten.

Mer information om auktorisering med Azure AD finns i Auktorisera åtkomst till blobar med Azure Active Directory.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Azure AD användare, grupp eller tjänstens huvudnamn ska kunna anropa Append Block åtgärden och den minst privilegierade inbyggda Azure RBAC-rollen som innehåller den här åtgärden:

Mer information om hur du tilldelar roller med Azure RBAC finns i Tilldela en Azure-roll för åtkomst till blobdata.

Kommentarer

Append Block laddar upp ett block till slutet av en befintlig tilläggsblob. Datablocket är omedelbart tillgängligt när anropet har slutförts på servern. Högst 50 000 tillägg tillåts för varje tilläggsblob. Varje block kan ha olika storlek.

I följande tabell beskrivs de högsta tillåtna block- och blobstorlekarna efter tjänstversion:

Tjänstversion Maximal blockstorlek (via Append Block) Maximal blobstorlek
Version 2022-11-02 och senare 100 MiB (förhandsversion) Cirka 4,75 TiB (100 MiB × 50 000 block)
Tidigare versioner än 2022-11-02 4 MiB Cirka 195 gibibyte (GiB) (4 MiB × 50 000 block)

Append Block lyckas bara om blobben redan finns.

Blobar som laddas upp med hjälp Append Block av exponerar inte block-ID:t. Du kan inte anropa Hämta blockeringslista mot en tilläggsblob. Detta resulterar i ett fel.

Du kan ange följande valfria villkorsstyrda rubriker för begäran:

  • x-ms-blob-condition-appendpos: Du kan ange den här rubriken till en byteförskjutning där klienten förväntar sig att lägga till blocket. Begäran lyckas endast om den aktuella förskjutningen matchar den som anges av klienten. Annars misslyckas begäran med felkoden 412 (förhandsvillkoret misslyckades).

    Klienter som använder en enskild skrivare kan använda det här huvudet för att avgöra om en Append Block åtgärd lyckades, trots ett nätverksfel.

  • x-ms-blob-condition-maxsize: Klienter kan använda det här huvudet för att säkerställa att tilläggsåtgärder inte ökar blobstorleken utöver en förväntad maximal storlek i byte. Om villkoret misslyckas misslyckas begäran med felkoden 412 (villkoret misslyckades).

Om du försöker ladda upp ett block som är större än den tillåtna storleken returnerar tjänsten felkoden 413 (begärandeentiteten är för stor). Tjänsten returnerar också ytterligare information om felet i svaret, inklusive den maximala blockstorleken som tillåts i byte. Om du försöker ladda upp fler än 50 000 block returnerar tjänsten felkoden 409 (konflikt).

Om bloben har ett aktivt lån måste klienten ange ett giltigt låne-ID för begäran för att kunna skriva ett block till bloben. Om klienten inte anger något låne-ID eller anger ett ogiltigt låne-ID returnerar Blob Storage felkoden 412 (villkoret misslyckades). Om klienten anger ett låne-ID, men bloben inte har ett aktivt lån, returnerar Blob Storage även felkod 412.

Om du anropar Append Block en befintlig blockblob eller sidblob returnerar tjänsten ett konfliktfel. Om du anropar Append Block en icke-befintlig blob returnerar tjänsten också ett fel.

Undvik duplicerade eller fördröjda tillägg

I ett scenario med en enskild skrivare kan klienten undvika duplicerade tillägg eller fördröjda skrivningar med hjälp av villkorsrubriken *x-ms-blob-condition-appendpos för att kontrollera den aktuella förskjutningen. Klienten kan också undvika dubbletter eller fördröjningar genom att kontrollera villkorsstyrt ETag med hjälp If-Matchav .

I ett scenario med flera skrivare kan varje klient använda villkorsstyrda rubriker, men detta kanske inte är optimalt för prestanda. För det högsta samtidiga tilläggsdataflödet bör program hantera redundanta tillägg och fördröjda tillägg i programlagret. Programmet kan till exempel lägga till epoker eller sekvensnummer i de data som läggs till.