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å clear må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å 0 och 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:
- Azure RBAC-åtgärd:Microsoft.Storage/storageAccounts/blobServices/containers/blobs/write
- Minsta privilegierade inbyggda roll:Storage Blob Data-deltagare
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 tillPut 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örLast-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-Match
begäran ,If-None-Match
,If-Modified-Since
ochIf-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:
En
Put Page
begäran om att skriva värdet "X" till sidan 0 överskrider tidsgränsen eller returnerar inte något svar.Ett nytt försök att skriva värdet "X" till sidan 0 lyckas.
En begäran om att skriva värdet "Y" till sidan 0 lyckas.
Den ursprungliga begäran lyckas och skriver värdet "X" till sidan 0.
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:
Klienten skapar en sidblob med Put Blob och anger dess sekvensnummer till
0
.En
Put Page
begäran om att skriva värdet "X" till sidan 0 medif-sequence-number-lt
rubriken inställd på1
tidsgräns eller returnerar inte något svar.Klienten anropar
Set Blob Properties
för att uppdatera sekvensnumret till1
.En begäran om att skriva värdet "X" till sidan 0 med
if-sequence-number-lt
inställt på2
lyckades.En begäran om att skriva värdet "Y" till sidan 0 med
if-sequence-number-lt
inställt på2
lyckas.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).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