Delen via


Put-bereik

De Put Range bewerking schrijft een bereik van bytes naar een bestand.

Protocol beschikbaarheid

Bestandsshareprotocol ingeschakeld Beschikbaar
SMB Ja
NFS Nee

Aanvraag

De Put Range aanvraag kan als volgt worden samengesteld. U wordt aangeraden HTTPS te gebruiken.

Methode Aanvraag-URI HTTP-versie
PUT https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=range HTTP/1.1

Vervang de padonderdelen die in de aanvraag-URI worden weergegeven, als volgt door uw eigen:

Padonderdeel Beschrijving
myaccount De naam van uw opslagaccount.
myshare De naam van de bestandsshare.
mydirectorypath Optioneel. Het pad naar de bovenliggende map.
myfile De naam van het bestand.

Zie Naam- en verwijzingsshares, mappen, bestanden en metagegevens voor meer informatie over beperkingen voor padnamen.

URI-parameters

De volgende aanvullende parameters kunnen worden opgegeven voor de aanvraag-URI.

Parameter Beschrijving
timeout Optioneel. De timeout parameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor bestandsservicebewerkingen voor meer informatie.

Aanvraagheaders

De vereiste en optionele aanvraagheaders worden beschreven in de volgende tabel:

Aanvraagheader Beschrijving
Authorization Vereist. Hiermee geeft u het autorisatieschema, de accountnaam en de handtekening. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
Date of x-ms-date Vereist. Geef de Coordinated Universal Time (UTC) op voor de aanvraag. Zie Aanvragen voor Azure Storage autoriseren voor meer informatie.
x-ms-version Vereist voor alle geautoriseerde aanvragen. Hiermee geeft u de versie van de bewerking te gebruiken voor deze aanvraag. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
Range of x-ms-range x-ms-range Of Range is vereist.

Hiermee geeft u het bereik van bytes moet worden geschreven. Zowel het begin als het einde van het bereik moeten worden opgegeven. Deze header wordt gedefinieerd door de http/1.1-protocolspecificatie.

Voor een updatebewerking kan het bereik maximaal 4 MiB groot zijn. Voor een duidelijke bewerking kan het bereik maximaal de waarde van de volledige grootte van het bestand zijn.

De bestandsservice accepteert slechts één bytebereik voor de Range headers en x-ms-range en het bytebereik moet worden opgegeven in de volgende indeling: bytes=startByte-endByte.

Als zowel Range als x-ms-range zijn opgegeven, gebruikt de service de waarde van x-ms-range. Zie De bereikheader opgeven voor bestandsservicebewerkingen voor meer informatie.
Content-Length Vereist. Hiermee geeft u het aantal bytes dat wordt verzonden in de aanvraagbody. Wanneer de x-ms-write header is ingesteld op clear, moet de waarde van deze header worden ingesteld op 0.
Content-MD5 Optioneel. Een MD5-hash van de inhoud. Deze hash wordt gebruikt om de integriteit van de gegevens tijdens het transport te controleren. Wanneer de Content-MD5 header is opgegeven, vergelijkt Azure Files de hash van de inhoud die is aangekomen met de headerwaarde die is verzonden. Als de twee hashes niet overeenkomen, mislukt de bewerking met foutcode 400 (Ongeldige aanvraag).

De Content-MD5 header is niet toegestaan wanneer de x-ms-write header is ingesteld op clear. Als deze is opgenomen in de aanvraag, retourneert de bestandsservice statuscode 400 (Ongeldige aanvraag).
x-ms-write: { update ¦ clear } Vereist. U moet een van de volgende opties opgeven:
  • update: schrijft de bytes die zijn opgegeven door de aanvraagbody naar het opgegeven bereik. De Range headers en Content-Length moeten overeenkomen om de update uit te voeren.
  • clear: Hiermee wordt het opgegeven bereik gewist en wordt de ruimte vrijgegeven die wordt gebruikt in de opslag voor dat bereik. Als u een bereik wilt wissen, stelt u de Content-Length header in op 0en stelt u de Range header in op een waarde die aangeeft dat het bereik moet worden gewist, tot de maximale bestandsgrootte.
x-ms-lease-id: <ID> Vereist als het bestand een actieve lease heeft. Beschikbaar voor versie 2019-02-02 en hoger.
x-ms-client-request-id Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 kibibyte (KiB) die wordt vastgelegd in de logboeken wanneer logboekregistratie is geconfigureerd. We raden u ten zeerste aan deze header te gebruiken om activiteiten aan de clientzijde te correleren met aanvragen die de server ontvangt. Zie Azure Files bewaken voor meer informatie.
x-ms-file-last-write-time: { now ¦ preserve } Optioneel. Versie 2021-06-08 en hoger. U kunt een van de volgende opties opgeven:
  • now:Standaardwaarde. Updates de tijdstempel van de laatste schrijftijd naar de tijd van de aanvraag.
  • preserve: houdt de bestaande tijdstempel van de laatste schrijfbewerking ongewijzigd.
x-ms-file-request-intent Vereist als Authorization de header een OAuth-token opgeeft. Acceptabele waarde is backup. Deze header geeft aan dat de Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action of Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action moet worden verleend als deze zijn opgenomen in het RBAC-beleid dat is toegewezen aan de identiteit die is geautoriseerd met behulp van de Authorization header. Beschikbaar voor versie 2022-11-02 en hoger.
x-ms-allow-trailing-dot: { <Boolean> } Optioneel. Versie 2022-11-02 en hoger. De Booleaanse waarde geeft aan of een volgpunt in de aanvraag-URL moet worden ingekort of niet. Zie Shares, mappen, bestanden en metagegevens een naam geven en hiernaar verwijzen voor meer informatie.

Aanvraagbody

De gegevens die het bereik vertegenwoordigen dat moet worden geüpload.

Voorbeeldaanvraag: Bytebereik bijwerken

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
x-ms-write: update  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65535  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536  

Voorbeeldaanvraag: bytebereik wissen

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  
  
Request Headers:  
Range: bytes=1024-2048  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  

Antwoord

Het antwoord bevat een HTTP-statuscode en een set antwoordheaders.

Statuscode

Een geslaagde bewerking retourneert statuscode 201 (Gemaakt).

Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

Het antwoord voor deze bewerking bevat de volgende headers. Het antwoord kan ook aanvullende standaard-HTTP-headers bevatten. Alle standaardheaders voldoen aan de HTTP/1.1-protocolspecificatie.

Antwoordheader Beschrijving
ETag De ETag bevat een waarde die de versie van het bestand vertegenwoordigt. De waarde staat tussen aanhalingstekens.
Last-Modified Retourneert de datum en tijd waarop de map voor het laatst is gewijzigd. De datumnotatie volgt RFC 1123. Zie Datum/tijdwaarden weergeven in kopteksten voor meer informatie. Elke bewerking die de share of de eigenschappen of metagegevens wijzigt, wordt de laatste wijzigingstijd bijgewerkt. Bewerkingen op bestanden hebben geen invloed op de laatste wijzigingstijd van de share.
Content-MD5 Deze koptekst wordt geretourneerd, zodat de client de integriteit van de berichtinhoud kan controleren. De waarde van deze header wordt berekend door de bestandsservice. Dit is niet noodzakelijkerwijs hetzelfde als de waarde die is opgegeven in de aanvraagheaders.
x-ms-request-id Identificeert op unieke wijze de aanvraag die is gedaan en kan worden gebruikt om problemen met de aanvraag op te lossen. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
x-ms-version Geeft de versie van de bestandsservice aan die is gebruikt om de aanvraag uit te voeren.
Date Een UTC-datum/tijd-waarde die wordt gegenereerd door de service, die de tijd aangeeft waarop het antwoord is geïnitieerd.
x-ms-request-server-encrypted: { true ¦ false } Versie 2017-04-17 en hoger. De waarde van deze header wordt ingesteld op true als de inhoud van de aanvraag is versleuteld met behulp van het opgegeven algoritme. Anders wordt de waarde ingesteld op false.
x-ms-client-request-id Deze header kan worden gebruikt voor het oplossen van problemen met aanvragen en bijbehorende antwoorden. De waarde van deze header is gelijk aan de waarde van de x-ms-client-request-id header als deze aanwezig is in de aanvraag en de waarde niet meer dan 1024 zichtbare ASCII-tekens bevat. Als de x-ms-client-request-id header niet aanwezig is in de aanvraag, is deze niet aanwezig in het antwoord.
x-ms-file-last-write-time Versie 2021-06-08 en hoger. De laatste schrijftijd voor het bestand, in de ISO 8601-indeling. Bijvoorbeeld: 2017-05-10T17:52:33.9551861Z.

Hoofdtekst van de reactie

Geen.

Voorbeeldantwoord

Response Status:  
HTTP/1.1 201 Created  

Response Headers:  
Transfer-Encoding: chunked  
Content-MD5: sQqNsWTgdUEFt6mb5y4/5Q==  
Date:Mon, 27 Jan 2014 22:33:35 GMT  
ETag: "0x8CB171BA9E94B0B"  
Last-Modified: Mon, 27 Jan 2014 12:13:31 GMT  
x-ms-version: 2014-02-14  
Content-Length: 0  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  

Autorisatie

Alleen de accounteigenaar kan deze bewerking aanroepen.

Opmerkingen

Met de Put Range bewerking wordt een bereik van bytes naar een bestand geschreven. Deze bewerking kan alleen worden aangeroepen voor een bestaand bestand. Het kan niet worden aangeroepen om een nieuw bestand te maken. Als u aanroept Put Range met een bestandsnaam die momenteel niet bestaat, wordt statuscode 404 (Niet gevonden) geretourneerd.

Als u een nieuw bestand wilt maken, roept u Bestand maken aan. Een bestand kan maximaal 4 TiB groot zijn.

Een Put Range bewerking mag 10 minuten per MiB worden voltooid. Als de bewerking gemiddeld langer dan 10 minuten per MiB duurt, treedt er een time-out op.

Als het bestand een actieve lease heeft, moet de client een geldige lease-id opgeven voor de aanvraag om een bereik te schrijven.

Bereikupdatebewerkingen

Aanroepen Put Range met de Update optie voert een in-place schrijfbewerking uit op het opgegeven bestand. Alle inhoud in het opgegeven bereik wordt overschreven met de update. Elk bereik dat wordt verzonden met Put Range voor een updatebewerking, kan maximaal 4 MiB groot zijn. Als u probeert een bereik te uploaden dat groter is dan 4 MiB, retourneert de service statuscode 413 (Aanvraagentiteit te groot).

Bewerkingen voor bereik wissen

Als u met de Clear optie aanroeptPut Range, wordt de ruimte in de opslag vrijgemaakt zolang het opgegeven bereik 512 bytes is uitgelijnd. Bereiken die zijn gewist, worden niet meer bijgehouden als onderdeel van het bestand en worden niet geretourneerd in het antwoord Lijstbereik . Als het opgegeven bereik niet 512 bytes is uitgelijnd, schrijft de bewerking nullen naar het begin of einde van het bereik dat niet is uitgelijnd met 512 bytes en wordt de rest van het bereik dat 512 bytes uitgelijnd is, vrijgemaakt.

Bereiken die niet zijn gewist, worden geretourneerd in het antwoord Lijstbereiken . Zie voor een voorbeeld de sectie 'Voorbeeld van niet-uitgelijnd leeg bereik' die volgt.

Bestandslease
U kunt leasebestand aanroepen om een exclusieve schrijfvergrendeling voor het bestand te verkrijgen voor andere schrijfbewerkingen voor een oneindige duur.

SMB-client bytebereikvergrendelingen

Het SMB-protocol staat bytebereikvergrendelingen toe om lees- en schrijftoegang tot regio's van een bestand te beheren. Dit betekent dat Put Range mislukt als een SMB-client een vergrendeling heeft die overlapt met het bereik dat is opgegeven door de Put Range bewerking met .x-ms-range Zie Bestandsvergrendelingen beheren voor meer informatie.

Wijzigingsmeldingen voor SMB-clientmap

Het SMB-protocol ondersteunt de API-functie FindFirstChangeNotification waarmee toepassingen kunnen detecteren wanneer wijzigingen in het bestandssysteem plaatsvinden. Het kan detecteren wanneer een bestand of map wordt toegevoegd, gewijzigd of verwijderd, en wanneer de grootte, kenmerken of beveiligingsdescriptors van een bestand veranderen. SMB-clients die deze API gebruiken, ontvangen geen meldingen wanneer een bestands- of mapwijziging plaatsvindt via de Azure Files REST API. Wijzigingen die worden veroorzaakt door andere SMB-clients, worden echter meldingen doorgegeven.

Voorbeeld van niet-uitgelijnd, leeg bereik

Stel dat een bestand wordt gemaakt met Bestand maken en dat één bereik als volgt wordt geschreven met Put Range:

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
x-ms-write: updte  
x-ms-date: Mon, 27 Jan 2014 22:15:50 GMT  
x-ms-version: 2014-02-14  
x-ms-range: bytes=0-65536  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  
Content-Length: 65536  

Als u een lijstbereikbewerking uitvoert op het bestand, wordt de volgende antwoordtekst geretourneerd:

<?xml version="1.0" ecoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>65536</End>  
</Range>  
</Ranges>  

Stel nu dat er een niet-uitgelijnde bytebereikbewerking wordt uitgevoerd:

Request Syntax:  
PUT https://myaccount.file.core.windows.net/myshare/myfile?comp=range HTTP/1.1  

Request Headers:  
Range: bytes=768-2304  
x-ms-write: clear  
x-ms-date: Mon, 27 Jan 2014 23:37:35 GMT  
x-ms-version: 2014-02-14  
Authorization: SharedKey myaccount:4KdWDiTdA9HmIF9+WF/8WfYOpUrFhieGIT7f0av+GEI=  

Een volgende lijstbereikbewerking voor het bestand retourneert de volgende antwoordtekst:

<?xml version="1.0" encoding="utf-8"?>  
<Ranges>  
<Range>  
<Start>0</Start>  
<End>1024</End>  
</Range>  
<Range>  
<Start>2048</Start>  
<End>65535</End>  
</Range>  
</Ranges>  

Houd er rekening mee dat nullen zijn geschreven naar de niet-uitgelijnde ruimte van 768-1024 en 2048-2304.

Put Range wordt niet ondersteund op een momentopname van een share, die een alleen-lezen kopie van een share is. Een poging om deze bewerking uit te voeren op een momentopname van een share mislukt met 400 (InvalidQueryParameterValue).

Zie ook