Dela via


Placera sida från URL

Åtgärden Put Page From URL skriver ett sidintervall till en sidblob där innehållet läse från en URL. Det här API:et är tillgängligt från och med version 2018-11-09.

Förfrågan

Du kan skapa begäran på Put Page From URL 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änst-URI

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 i 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 och så vidare.

Blobtjänsten 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.

Sidintervallet kan vara upp till 4 miB stort.

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 och så vidare.

Blobtjänsten 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. Värdet för det här huvudet måste vara inställt på noll. När längden inte är noll misslyckas åtgärden med statuskoden 400 (felaktig begäran).
x-ms-copy-source:name Krävs. Anger url:en för källbloben. Värdet kan vara en URL på upp till 2 KiB som anger en blob. Värdet ska vara URL-kodat eftersom det visas i en begärande-URI. Källbloben måste antingen vara offentlig eller ha behörighet via en signatur för delad åtkomst. Om källbloben är offentlig krävs ingen auktorisering för att utföra åtgärden. Här är några exempel på url:er för källobjekt:

- https://myaccount.blob.core.windows.net/mycontainer/myblob
- https://myaccount.blob.core.windows.net/mycontainer/myblob?snapshot=<DateTime>
- https://myaccount.blob.core.windows.net/mycontainer/myblob?versionid=<DateTime>
x-ms-copy-source-authorization: <scheme> <signature> Valfritt. Anger auktoriseringsschemat och signaturen för kopieringskällan. Mer information finns i Auktorisera begäranden till Azure Storage.
Endast en schemabärare stöds för Microsoft Entra.
Det här huvudet stöds i version 2020-10-02 och senare.
x-ms-source-range Laddar upp blobens byte i käll-URL:en i det angivna intervallet. Både början och slutet av intervallet måste anges. Det här huvudet definieras av HTTP/1.1-protokollspecifikationen.

Sidintervallet kan vara upp till 4 miB stort.

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

Mer information finns i Ange intervallrubriken för Blob Service-åtgärder .
x-ms-source-content-md5 Valfritt. En MD5-hash för sidinnehållet från URI:n. Den här hashen används för att verifiera sidans integritet under transporten av data från URI:n. När det här huvudet anges jämför lagringstjänsten hash-värdet för det innehåll som har kommit från kopieringskällan med det här rubrikvärdet.

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-source-content-crc64 Valfritt. En CRC64-hash för sidinnehållet från URI:n. Den här hashen används för att verifiera sidans integritet under transporten av data från URI:n. När det här huvudet anges jämför lagringstjänsten hash-värdet för det innehåll som har kommit från kopieringskällan 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 x-ms-source-content-md5 och x-ms-source-content-crc64 huvuden finns misslyckas begäran med 400 (felaktig 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 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 Service statuskod 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 Service 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 Service statuskod 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 Service statuskod 412 (förhandsvillkoret misslyckades).
x-ms-encryption-scope Valfritt. Anger krypteringsomfånget som ska användas för att kryptera källinnehållet. Det här huvudet stöds i version 2019-02-02 och senare.
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 följande huvuden anges på begäran för att kryptera en blob krypterad med en nyckel som tillhandahålls av kunden. 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

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

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 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 From URL å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 Returneras så att klienten kan söka efter meddelandets innehållsintegritet. Värdet för det här huvudet beräknas av Blob Service. Det är inte nödvändigtvis samma som värdet som anges i begärandehuvudena. För version 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 version 2019-02-02 eller senare. Returneras så att klienten kan söka efter meddelandets innehållsintegritet. Värdet för det här huvudet beräknas av Blob Service. Det är inte nödvändigtvis samma som värdet som anges i begärandehuvudena.

Det här huvudet returneras när x-ms-source-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 och false i annat fall.
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:  
Transfer-Encoding: chunked  
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 From URL 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 From URL å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 From URL skriver ett sidintervall till en sidblob. Den här åtgärden kan bara anropas på en befintlig sidblob. Den kan inte anropas för att skapa en ny sidblob och kan inte heller anropas på en blockblob. Om du anropar Put Page From URL med ett blobnamn som för närvarande inte finns returneras BlobNotFound-felet (HTTP-statuskod 404 – Hittades inte).

I version 2020-10-02 och senare stöds Microsoft Entra auktorisering för kopieringsåtgärdens källa.

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

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

Siduppdateringsåtgärder

Anropet Put Page From URL utför en skrivning på plats på den angivna sidbloben. Allt innehåll på den angivna sidan skrivs över med uppdateringen.

Viktigt

Om tidsgränsen uppnås för servern eller om anslutningen stängs under en Put Page From URLkan sidan ha uppdaterats eller inte. Därför bör du fortsätta att försöka uppdatera igen tills du får ett svar som anger att åtgärden lyckades.

Varje sidintervall som skickas med Put Page From URL 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 intervall med sidor som är större än 4 MiB returnerar tjänsten statuskod 413 (begärandeentiteten är för stor).

Hantera samtidighetsproblem

Blob-tjänsten 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 hos 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 From URL. Ordningen på svar som returneras från Blob Service 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ärandena.

  • Du kan utföra uppdateringar villkorligt baserat på blobens ETag eller senaste ändringstid 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 detta ändamål.

  • 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 återförsök av en begäran som det inte fanns något svar för inte resulterar i samtidiga uppdateringar. Den här metoden kan vara bäst för klienter som kräver högt dataflöde för sidskrivningar. det 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 From URL ö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 begäran igen, men på grund av den distribuerade typen av Azure Storage-tjänster är det möjligt att den ursprungliga begäran bearbetas när den nya begäran har slutförts. Den fördröjda ursprungliga begäran kan skriva över andra uppdateringar och ge ett oväntat resultat. Följande sekvens illustrerar hur detta kan ske:

  1. En Put Page From URL begäran om att skriva värdet "X" till sidan 0 överskrider tidsgränsen eller returnerar inget svar.

  2. Ett nytt försök att begära 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 mellan 100–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. Det gör du genom att öka sekvensnumret innan du försöker utföra den ursprungliga begäran igen. Du kan sedan använda rubrikerna för villkorsstyrda 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 From URL begäran om att skriva värdet "X" till sida 0 med if-sequence-number-lt rubriken inställd på 1 tidsgräns eller returnerar inget svar.

  3. Klienten anropar Ange blobegenskaper för att uppdatera sekvensnumret till 1.

  4. Ett nytt försök att begära att skriva värdet "X" till sidan 0 med if-sequence-number-lt inställt på 2 lyckas.

  5. En begäran om att skriva värdet "Y" till sida 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