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:
- 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 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 URL
kan 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 tillPut 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örLast-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-Match
begäran ,If-None-Match
,If-Modified-Since
ochIf-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:
En
Put Page From URL
begäran om att skriva värdet "X" till sidan 0 överskrider tidsgränsen eller returnerar inget svar.Ett nytt försök att begära 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 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:
Klienten skapar en sidblob med Put Blob och anger dess sekvensnummer till 0.
En
Put Page From URL
begäran om att skriva värdet "X" till sida 0 medif-sequence-number-lt
rubriken inställd på1
tidsgräns eller returnerar inget svar.Klienten anropar Ange blobegenskaper för att uppdatera sekvensnumret till 1.
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.En begäran om att skriva värdet "Y" till sida 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