Put-bereik
De Put Range bewerking schrijft een bereik van bytes naar een bestand.
Protocol beschikbaarheid
| Bestandsshareprotocol ingeschakeld | Beschikbaar |
|---|---|
| SMB |
|
| NFS |
|
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:
|
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:
|
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).