Placera sida

Artikel
02/12/2024

Å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:10000fö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 på begärande-URI:n:

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

Begärandehuvuden

De obligatoriska och valfria begärandehuvudena 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 sidborttagningsåtgärd kan sidintervallet vara lika stort som värdet för blobens fulla storlek. Eftersom sidor måste justeras med gränser på 512 byte 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 enda byteintervall för `Range` rubriken 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`för . 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 gränser på 512 byte 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 enda byteintervall för `x-ms-range` rubriken 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`för . Mer information finns i Ange områdesrubriken för Blob Service-åtgärder .
`Content-Length`	Krävs. Anger antalet byte som överförs i begärandetexten. När rubriken `x-ms-page-write` är inställd `clear`på måste värdet för det här huvudet anges till `0`.
`Content-MD5`	Valfritt. En MD5-hash för sidinnehållet. Denna hash används för att verifiera sidans integritet under transporten. När det här huvudet anges jämför lagringstjänsten hashen 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. Denna hash används för att verifiera sidans integritet under transporten. När det här huvudet anges jämför lagringstjänsten hashen för det innehåll som har anlänt med det här rubrikvärdet. Obs! Denna CRC64-hash 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 de byte som anges av begärandetexten till det angivna intervallet. Huvudena `Range` och `Content-Length` måste matcha för att uppdateringen ska kunna utföras. - `Clear`: Rensar det angivna intervallet och frigör det utrymme som används i lagringen för det intervallet. Om du vill rensa ett område anger du `Content-Length` rubriken till `0`och anger `Range` 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 den med felet SequenceNumberConditionNotMet (HTTP-statuskod 412 – Förutsättningen 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 den med SequenceNumberConditionNotMet-fel (HTTP-statuskod 412 – Förutsättningen 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 den med SequenceNumberConditionNotMet-fel (HTTP-statuskod 412 – Förutsättningen misslyckades).
`If-Modified-Since`	Valfritt. Ett `DateTime` värde. Ange den här villkorliga rubriken för att endast skriva sidan om bloben har ändrats sedan det angivna datumet/tiden. Om bloben inte har ändrats returnerar Blob Storage statuskod 412 (villkoret 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 (villkoret misslyckades).
`If-Match`	Valfritt. Ett ETag-värde. Ange ett ETag-värde för det här villkorsstyrda huvudet för att endast skriva sidan om blobens ETag-värde matchar det angivna värdet. Om värdena inte matchar returnerar Blob Storage statuskod 412 (villkoret misslyckades).
`If-None-Match`	Valfritt. Ett ETag-värde. Ange ett ETag-värde för den här villkorliga rubriken för att skriva sidan endast om blobens ETag-värde inte matchar det angivna värdet. Om värdena är identiska returnerar Blob Storage statuskod 412 (villkoret 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 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.

Den här åtgärden stöder också användning av villkorsstyrda rubriker för att köra åtgärden endast 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 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 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 också innehålla ytterligare standard-HTTP-huvuden. 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` eller `If-None-Match` begärandehuvudet.
`Last-Modified`	Datum och tid då bloben senast ändrades. Datumformatet följer RFC 1123. Mer information finns i Representera datum/tid-vä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 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 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. Det här huvudet returneras för begäranden som gjordes mot version 2009-09-19 och senare.
`Date`	Ett UTC-datum/tid-värde 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 kundtilldelad nyckel 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 korrekt 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 huvudet om det finns i begäran och värdet inte innehåller fler än 1 024 synliga ASCII-tecken. `x-ms-client-request-id` Om rubriken inte finns i begäran visas 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.

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 Microsoft Entra ID.

Behörigheter

Nedan visas den RBAC-åtgärd som krävs för att en Microsoft Entra användare, grupp eller tjänstens huvudnamn ska kunna 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/blobar/write
Minst privilegierad inbyggd roll:Storage Blob Data-deltagare

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

En signatur för delad åtkomst (SAS) ger säker delegerad åtkomst till resurser i ett lagringskonto. Med en SAS har du detaljerad kontroll över hur en klient kan komma åt data. Du kan ange vilken resurs klienten kan komma åt, vilka behörigheter de har till dessa resurser och hur länge SAS är giltigt.

Åtgärden Put Page stöder tre typer av signaturer för delad åtkomst: SAS för användardelegering, sas för tjänsten och konto-SAS.

Vi rekommenderar att du använder Microsoft Entra autentiseringsuppgifter i stället för lagringskontonyckeln, vilket är enklare att kompromettera. Om din programdesign kräver signaturer för delad åtkomst använder du Microsoft Entra autentiseringsuppgifter för att skapa en SAS för användardelegering när det är möjligt.

När åtkomst med delad nyckel inte tillåts för lagringskontot tillåts inte en SAS-token för tjänsten eller en SAS-kontotoken för en begäran till Blob Storage. Mer information finns i Förstå hur nekande av delad nyckel påverkar SAS-token.

SAS för användardelegering

En SAS för användardelegering skyddas med Microsoft Entra autentiseringsuppgifter och även av de behörigheter som anges för SAS.

Put Page Att anropa åtgärden med hjälp av en SAS-token som delegerats till en container eller blobresurs kräver behörigheten Skriv (w) som en del av SAS-token för användardelegering.

Mer information om SAS för användardelegering finns i Skapa en SAS för användardelegering.

Tjänst-SAS

En tjänst-SAS skyddas med lagringskontonyckeln. En tjänst-SAS delegerar åtkomst till en resurs i en enda Azure Storage-tjänst, till exempel bloblagring.

Att anropa åtgärden Put Page med hjälp av en SAS-token som delegerats till en container eller blobresurs kräver behörigheten Skriv (w) som en del av tjänstens SAS-token.

Mer information om sas-tjänsten finns i Skapa en tjänst-SAS.

Konto-SAS

Ett SAS-konto skyddas med lagringskontonyckeln. En konto-SAS delegerar åtkomst till resurser i en eller flera av lagringstjänsterna. Alla åtgärder som är tillgängliga via en tjänst eller sas för användardelegering är också tillgängliga via ett konto-SAS.

Följande tabell anger den signerade resurstypen och signerade behörigheter som ska anges när åtkomst delegeras:

Åtgärd	Signerad tjänst	Signerad resurstyp	Signerad behörighet
Placera sida	Blob (b)	Objekt (o)	Skriva (w)

Mer information om KONTOT SAS finns i Skapa ett konto SAS.

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:

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 med if-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 till 1.
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