Dela via


Placera sida

Åtgärden Put Page skriver ett sidintervall till en sidblob.

Förfrågan

Du kan skapa begäran på Put Page följande sätt. Vi rekommenderar att du använder HTTPS. 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=page HTTP/1.1

Emulerad lagringstjänstbegäran

När du gör en begäran mot den emulerade lagringstjänsten anger du emulatorns värdnamn och blobtjänstporten 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=page HTTP/1.1

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

URI-parametrar

Du kan ange följande ytterligare parametrar för begärande-URI:n:

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

Begärandehuvuden

De obligatoriska och valfria begäranderubrikerna beskrivs i följande tabell:

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.
Range Antingen Range eller x-ms-range krävs.

Anger det intervall med byte som ska skrivas som en sida. Både början och slutet av intervallet måste anges. Det här huvudet definieras av HTTP/1.1-protokollspecifikationen.

För en siduppdateringsåtgärd kan sidintervallet vara upp till 4 MiB. För en sidrensningsåtgärd kan sidintervallet vara lika stort som värdet för blobens fulla storlek.

Eftersom sidor måste justeras mot 512 bytes gränser måste startförskjutningen vara en modulus på 512 och slutförskjutningen måste vara en modulus på 512–1. Exempel på giltiga byteintervall är 0–511, 512–1023 och så vidare.

Blob Storage accepterar endast ett intervall med en enda byte för Range huvudet och byteintervallet måste anges i följande format: bytes=startByte-endByte.

Om både Range och x-ms-range anges använder tjänsten värdet x-ms-range. Mer information finns i Ange intervallrubriken för Blob Service-åtgärder.
x-ms-range Antingen Range eller x-ms-range krävs.

Anger det intervall med byte som ska skrivas som en sida. Både början och slutet av intervallet måste anges. Det här huvudet definieras av HTTP/1.1-protokollspecifikationen.

För en siduppdateringsåtgärd kan sidintervallet vara så stort som 4 MiB i storlek. För en sidrensningsåtgärd kan sidintervallet vara upp till värdet för blobens fulla storlek.

Eftersom sidor måste justeras med 512 bytes gränser måste startförskjutningen vara en modulus på 512 och slutförskjutningen måste vara en modulus på 512–1. Exempel på giltiga byteintervall är 0–511, 512–1023 osv.

Blob Storage accepterar endast ett intervall med en enda byte för x-ms-range huvudet och byteintervallet måste anges i följande format: bytes=startByte-endByte.

Om både Range och x-ms-range anges använder tjänsten värdet x-ms-range. Mer information finns i Ange intervallrubriken för Blob Service-åtgärder .
Content-Length Krävs. Anger antalet byte som överförs i begärandetexten. x-ms-page-write När rubriken är inställd på clearmåste värdet för det här huvudet anges till 0.
Content-MD5 Valfritt. En MD5-hash för sidinnehållet. Den här hashen används för att verifiera sidans 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.
<br/ >Obs! Den här MD5-hashen lagras inte 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 sidinnehållet. Den här hashen används för att verifiera sidans 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.

Obs! Den här CRC64-hashen lagras inte med bloben.

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

Om både huvudena Content-MD5 och x-ms-content-crc64 finns misslyckas begäran med 400 (felaktig begäran).

Det här huvudet stöds i version 2019-02-02 och senare.
x-ms-page-write: {update ¦ clear} Krävs. Du kan ange något av följande alternativ:

- Update: Skriver byte som anges av begärandetexten till det angivna intervallet. Huvudena Range och Content-Length måste matcha för att utföra uppdateringen.
- Clear: Rensar det angivna intervallet och frigör det utrymme som används i lagringen för det intervallet. Om du vill rensa ett intervall ställer du in Content-Length rubriken på 0och ställer in Range rubriken på ett värde som anger intervallet som ska rensas, upp till den maximala blobstorleken.
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 version 2019-02-02 och 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-if-sequence-number-le: <num> Valfritt. Om blobens sekvensnummer är mindre än eller lika med det angivna värdet fortsätter begäran. Annars misslyckas det med felet SequenceNumberConditionNotMet (HTTP-statuskod 412 – Villkoret misslyckades).
x-ms-if-sequence-number-lt: <num> Valfritt. Om blobens sekvensnummer är mindre än det angivna värdet fortsätter begäran. Annars misslyckas det med SequenceNumberConditionNotMet-fel (HTTP-statuskod 412 – Villkoret misslyckades).
x-ms-if-sequence-number-eq: <num> Valfritt. Om blobens sekvensnummer är lika med det angivna värdet fortsätter begäran. Annars misslyckas det med SequenceNumberConditionNotMet-fel (HTTP-statuskod 412 – Villkoret misslyckades).
If-Modified-Since Valfritt. Ett DateTime värde. Ange den här villkorliga rubriken om du bara vill skriva sidan om bloben har ändrats sedan det angivna datumet/tiden. Om bloben inte har ändrats returnerar Blob Storage statuskoden 412 (förhandsvillkoret misslyckades).
If-Unmodified-Since Valfritt. Ett DateTime värde. Ange den här villkorliga rubriken om du bara vill skriva sidan om bloben inte har ändrats sedan det angivna datumet/tiden. Om bloben har ändrats returnerar Blob Storage statuskod 412 (förhandsvillkoret misslyckades).
If-Match Valfritt. Ett ETag-värde. Ange ett ETag-värde för den här villkorliga rubriken för att endast skriva sidan om blobens ETag-värde matchar det angivna värdet. Om värdena inte matchar returnerar Blob Storage statuskoden 412 (förhandsvillkoret misslyckades).
If-None-Match Valfritt. Ett ETag-värde.

Ange ett ETag-värde för den här villkorliga rubriken för att endast skriva sidan om blobens ETag-värde inte matchar det angivna värdet. Om värdena är identiska returnerar Blob Storage statuskod 412 (förhandsvillkoret misslyckades).
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 loggning 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.

Den här åtgärden stöder även användning av villkorsstyrda rubriker för att endast köra åtgärden om ett angivet villkor uppfylls. Mer information finns i Ange villkorsstyrda rubriker för Blob Service-åtgärder.

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

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

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 på sidan.

Exempelbegäran: Uppdatera byteintervall

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
x-ms-page-write: update  
x-ms-date: Fri, 16 Sep 2011 22:15:50 GMT  
x-ms-version: 2011-08-18  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536  
  

Exempelbegäran: Rensa byteintervall

  
Request Syntax:  
PUT https://myaccount.blob.core.windows.net/mycontainer/myblob?comp=page HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-page-write: clear  
x-ms-date: Sun, 25 Sep 2011 23:37:35 GMT  
x-ms-version: 2011-08-18  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
  

Svarsåtgärder

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

Statuskod

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

Mer information om statuskoder finns i Status och felkoder.

Svarshuvuden

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

Syntax Description
ETag ETag för bloben. Om begärandeversionen är 2011-08-18 och senare omges ETag-värdet av citattecken. ETag kan användas för att utföra en villkorsstyrd Put Page åtgärd genom att ange dess värde för If-Match begärandehuvudet eller If-None-Match .
Last-Modified Datum och tid då bloben senast ändrades. Datumformatet följer RFC 1123. Mer information finns i Representera 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 meddelandets innehållsintegritet. Värdet för det här huvudet beräknas av Blob Storage. Det är inte nödvändigtvis samma som värdet som anges i begärandehuvudena. För version 2019-02-02 och senare returneras det här huvudet endast när begäran har det här huvudet.
x-ms-content-crc64 För version 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 som värdet som anges i begärandehuvudena.

Det här huvudet returneras när Content-MD5 rubriken inte finns i begäran.
x-ms-blob-sequence-number Det aktuella sekvensnumret för sidbloben.
x-ms-request-id Identifierar begäran som gjordes unikt och kan användas för att felsöka begäran. Mer information finns i Felsöka API-åtgärder.
x-ms-version Anger den Blob Service-version som användes för att köra begäran. Den här rubriken returneras för begäranden som har gjorts mot version 2009-09-19 och senare.
Date Ett DATUM-/tidsvärde för UTC som genereras av tjänsten, vilket anger den tid då svaret initierades.
x-ms-request-server-encrypted: true/false Version 2015-12-11 och 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 och senare. Returneras om begäran använde en nyckel från kunden för kryptering, så att klienten kan se till att innehållet i begäran krypteras med hjälp av den angivna nyckeln.
x-ms-encryption-scope Version 2019-02-02 och senare. Returneras om begäran använde ett krypteringsomfång, så att klienten kan se till att innehållet i begäran krypteras med hjälp av krypteringsomfånget.
x-ms-client-request-id Kan användas för att felsöka begäranden och motsvarande svar. Värdet för det här huvudet är lika med värdet x-ms-client-request-id för rubriken om det finns i begäran och värdet inte innehåller fler än 1 024 synliga ASCII-tecken. Om rubriken x-ms-client-request-id inte finns i begäran finns den inte i svaret.

Själva svaret

Inga.

Exempelsvar

Response Status:  
HTTP/1.1 201 Created  
  
Response Headers:  
x-ms-content-crc64: 77uWZTolTHU  
Date: Sun, 25 Sep 2011 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Sun, 25 Sep 2011 12:13:31 GMT  
x-ms-version: 2011-08-18  
x-ms-blob-sequence-number: 0  
Content-Length: 0  
Server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0  
  

Auktorisering

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

Viktigt

Microsoft rekommenderar att du använder Microsoft Entra ID med hanterade identiteter för att auktorisera begäranden till Azure Storage. Microsoft Entra ID ger överlägsen säkerhet och användarvänlighet jämfört med auktorisering med delad nyckel.

Azure Storage stöder användning av Microsoft Entra ID för att auktorisera begäranden till blobdata. Med Microsoft Entra ID 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 Microsoft Entra ID 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 Microsoft Entra ID finns i Auktorisera åtkomst till blobar med hjälp av Microsoft Entra ID.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Microsoft Entra användare, grupp, hanterad identitet eller tjänstens huvudnamn ska anropa Put Page å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 hjälp av Azure RBAC finns i Tilldela en Azure-roll för åtkomst till blobdata.

Kommentarer

Åtgärden Put Page skriver ett sidintervall till en sidblob. Den här åtgärden kan bara anropas på en befintlig sidblob. Det går inte att anropa för att skapa en ny sidblob och kan inte heller anropas på en blockblob. Om du anropar Put Page med ett blobnamn som för närvarande inte finns returneras HTTP-statuskod 404 (hittades inte).

Om du vill skapa en ny sidblob anropar du Put Blob och anger vilken typ av blob som ska skapas som en sidblob. En sidblob kan vara upp till 8 TiB i storlek.

Om bloben har ett aktivt lån måste klienten ange ett giltigt låne-ID för begäran om att skriva en sida.

Siduppdateringsåtgärder

Anrop Put Page med Update alternativet utför en skrivning på plats på den angivna sidbloben. Allt innehåll på den angivna sidan skrivs över med uppdateringen.

Viktigt

Om servern överskrider tidsgränsen eller om anslutningen stängs under en Put Page åtgärd kanske sidan har uppdaterats eller inte. Därför bör du fortsätta att försöka uppdatera igen tills du får ett svar som indikerar att det lyckades.

Varje sidintervall som skickas med Put Page för en uppdateringsåtgärd kan vara upp till 4 MiB i storlek. Sidans start- och slutintervall måste vara justerat med 512 bytes gränser. Om du försöker ladda upp ett antal sidor som är större än 4 MiB returnerar tjänsten statuskoden 413 (begärandeentiteten är för stor).

Sidrensningsåtgärder

När du anropar Put Page med Clear alternativet frigörs lagringsutrymmet som används av den angivna sidan. Sidor som har rensats spåras inte längre som en del av sidbloben.

Sidor som har rensats debiteras inte längre mot lagringskontot eftersom deras lagringsresurser har släppts. Det enda undantaget är om det finns befintliga ögonblicksbilder av sidbloben. Sidor i ögonblicksbilder debiteras om samma sidor inte längre finns som en del av källbloben.

Hantera samtidighetsproblem

Blob Storage hanterar samtidiga skrivningar till överlappande sidor sekventiellt. Den sista sidan som bearbetas av tjänsten avgör alltså blobens innehåll. För att säkerställa integriteten för blobens innehåll bör klienten därför hantera skrivningar till överlappande sidor med hjälp av en eller flera av följande metoder:

  • Du kan kontrollera värdet för svarshuvudet Last-Modified för varje lyckat anrop till Put Page. Ordningen på svar som returneras från Blob Storage motsvarar inte nödvändigtvis den ordning i vilken de kördes av tjänsten. Men värdet för Last-Modified anger alltid i vilken ordning tjänsten bearbetade begäranden.

  • Du kan utföra uppdateringar villkorligt baserat på blobens ETag eller senast ändrad tid med optimistisk samtidighet. Den här metoden fungerar bra om antalet samtidiga skrivningar är relativt lågt. Använd huvudena för villkorsstyrd If-Matchbegäran , If-None-Match, If-Modified-Sinceoch If-Unmodified-Since för det här ändamålet.

  • Du kan anropa Låneblob för att låsa bloben mot andra skrivningar under en minut, eller längre om lånet förnyas.

  • Du kan använda blobens sekvensnummer för att se till att omförsök görs för en begäran som det inte fanns något svar för resulterar det inte i samtidiga uppdateringar. Den här metoden kan vara bäst för klienter som kräver högt dataflöde för sidskrivningar. Detta beskrivs i detalj i följande avsnitt.

Använd sidblobsekvensnumret för att försöka begäranden igen

När ett anrop till Put Page överskrider tidsgränsen eller inte returnerar ett svar finns det inget sätt att veta säkert om begäran lyckades. Du måste därför försöka igen, men på grund av den distribuerade typen av Azure Storage-tjänster är det möjligt att den ursprungliga begäran kan bearbetas när den nya begäran har slutförts. Den försenade ursprungliga begäran kan skriva över andra uppdateringar och ge ett oväntat resultat. Följande sekvens illustrerar hur detta kan hända:

  1. En Put Page begäran om att skriva värdet "X" till sidan 0 överskrider tidsgränsen eller returnerar inte något svar.

  2. Ett nytt försök att skriva värdet "X" till sidan 0 lyckas.

  3. En begäran om att skriva värdet "Y" till sidan 0 lyckas.

  4. Den ursprungliga begäran lyckas och skriver värdet "X" till sidan 0.

  5. När du läser sidan 0 returneras värdet "X", när klienten vid den här tidpunkten förväntade sig värdet "Y".

Den här typen av konflikt kan uppstå när den ursprungliga begäran inte returnerar en statuskod från 100 till 499 eller 503 (Servern är upptagen). Om någon av dessa statuskoder returneras kan du vara säker på om begäran har lyckats eller misslyckats. Men om tjänsten returnerar en statuskod utanför det här intervallet finns det inget sätt att känna till statusen för den ursprungliga begäran.

Om du vill förhindra den här typen av konflikt kan du använda sidblobens sekvensnummer för att säkerställa att den ursprungliga begäran inte lyckas när du försöker igen. Om du vill göra det bör du öka sekvensnumret innan du försöker utföra den ursprungliga begäran igen. Du kan sedan använda rubrikerna för villkorsstyrd sekvensnummer för att säkerställa att begäran misslyckas om dess sekvensnummer inte matchar det förväntade sekvensnumret. Följande sekvens illustrerar den här metoden:

  1. Klienten skapar en sidblob med Put Blob och anger dess sekvensnummer till 0.

  2. En Put Page begäran om att skriva värdet "X" till sidan 0 med if-sequence-number-lt rubriken inställd på 1 tidsgräns eller returnerar inte något svar.

  3. Klienten anropar Set Blob Properties för att uppdatera sekvensnumret till 1.

  4. En begäran om att skriva värdet "X" till sidan 0 med if-sequence-number-lt inställt på 2 lyckades.

  5. En begäran om att skriva värdet "Y" till sidan 0 med if-sequence-number-lt inställt på 2 lyckas.

  6. Den ursprungliga begäran bearbetas slutligen, men den misslyckas eftersom den anger villkoret att sekvensnumret måste vara mindre än 1 (dvs. if-sequence-num-lt rubriken är inställd på 1). Felet är SequenceNumberConditionNotMet (HTTP-statuskod 412 – Villkoret misslyckades).

  7. Läsningssidan 0 returnerar det förväntade värdet "Y".

Se även

Auktorisera begäranden till Azure Storage
Status- och felkoder
Ange tidsgränser för blobtjänståtgärder