Bestand kopiëren

Artikel
03/29/2023

Met de Copy File bewerking wordt een blob of bestand gekopieerd naar een doelbestand in het opslagaccount.

Beschikbaar in versie 2015-02-21 en hoger.

Protocol beschikbaarheid

Bestandsshareprotocol ingeschakeld	Beschikbaar
SMB
NFS

Aanvraag

U kunt de Copy File aanvraag als volgt samenstellen. We raden HTTPS aan.

Vanaf versie 2013-08-15 kunt u een shared access signature opgeven voor het doelbestand als dit zich in hetzelfde account bevindt als het bronbestand. Vanaf versie 2015-04-05 kunt u ook een Shared Access Signature opgeven voor het doelbestand als het zich in een ander opslagaccount bevinden.

Methode	Aanvraag-URI	HTTP-versie
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	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 Shares, mappen, bestanden en metagegevens een naam geven en hiernaar verwijzen voor meer informatie over beperkingen voor padnamen.

URI-parameters

U kunt de volgende aanvullende parameters opgeven voor de aanvraag-URI:

Parameter	Beschrijving
`timeout`	Optioneel. De time-outparameter wordt uitgedrukt in seconden. Zie Time-outs instellen voor Azure Files bewerkingen voor meer informatie.

Aanvraagheaders

In de volgende tabel worden vereiste en optionele aanvraagheaders beschreven:

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. Deze bewerking is alleen beschikbaar in versie 2015-02-21 en hoger. Zie Versiebeheer voor de Azure Storage-services voor meer informatie.
`x-ms-meta-name:value`	Optioneel. Hiermee geeft u naam/waarde-paren die zijn gekoppeld aan het bestand als metagegevens. Als er geen naam-waardeparen zijn opgegeven, kopieert de bewerking de metagegevens van de bron-blob of het bronbestand naar het doelbestand. Als er een of meer naam-waardeparen zijn opgegeven, wordt het doelbestand gemaakt met de opgegeven metagegevens en worden de metagegevens niet gekopieerd uit de bron-blob of het bronbestand. Namen van metagegevens moeten voldoen aan de naamgevingsregels voor C#-id's. Houd er rekening mee dat metagegevens van bestanden die zijn opgegeven via Azure Files niet toegankelijk zijn vanaf een SMB-client.
`x-ms-copy-source:name`	Vereist. Hiermee geeft u de URL van het bronbestand of de blob op, met een lengte van maximaal 2 kibibytes (KiB). Als u een bestand wilt kopiëren naar een ander bestand binnen hetzelfde opslagaccount, kunt u een gedeelde sleutel gebruiken om het bronbestand te autoriseren. Als u een bestand kopieert vanuit een ander opslagaccount of als u een blob kopieert vanuit hetzelfde opslagaccount of een ander opslagaccount, moet u het bronbestand of de blob autoriseren met behulp van een shared access signature. Als de bron een openbare blob is, is er geen autorisatie vereist om de kopieerbewerking uit te voeren. U kunt ook een bestand in een momentopname van een share opgeven als een kopiebron. Hier volgen enkele voorbeelden van bronobject-URL's: `https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile` `https://myaccount.blob.core.windows.net/mycontainer/myblob?sastoken` `http://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?sharesnapshot=<DateTime>`
`x-ms-lease-id:<ID>`	Vereist als het doelbestand een actieve lease heeft. Beschikbaar voor versie 2019-02-02 en hoger. De lease-id die voor deze header is opgegeven, moet overeenkomen met de lease-id van het doelbestand. Als de aanvraag de lease-id niet bevat of als de id niet geldig is, mislukt de bewerking met statuscode 412 (voorwaarde is mislukt). Als deze header is opgegeven en het doelbestand momenteel geen actieve lease heeft, mislukt de bewerking met statuscode 412 (voorwaarde mislukt).
`x-ms-file-permission-copy-mode: { source ¦ override }`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. Bepaalt het kopieergedrag van de beveiligingsdescriptor van het bestand: `source`: de security descriptor van het doelbestand wordt gekopieerd uit het bronbestand. `override`: de security descriptor voor het doelbestand wordt bepaald via de `x-ms-file-permission` of-header `x-ms-file-permission-key` .
`x-ms-file-permission`	Vereist als `x-ms-file-permission-copy-mode` is opgegeven als `override` en `x-ms-file-permission-key` niet is opgegeven. Beschikbaar voor versie 2019-07-07 en hoger. Deze machtiging is de beveiligingsdescriptor voor het bestand dat is opgegeven in de Security Descriptor Definition Language (SDDL). U kunt deze header gebruiken als de machtigingsgrootte 8 kibibytes (KiB) of minder is. Anders kunt u gebruiken `x-ms-file-permission-key`. Indien opgegeven, moet deze een eigenaar, groep en discretionaire toegangsbeheerlijst (DACL) hebben. Houd er rekening mee dat er slechts één van `x-ms-file-permission` of `x-ms-file-permission-key` kan worden opgegeven.
`x-ms-file-permission-key`	Vereist als `x-ms-file-permission-copy-mode` is opgegeven als `override` en `x-ms-file-permission` niet is opgegeven. Beschikbaar voor versie 2019-07-07 en hoger. Deze header geeft de sleutel op van de machtiging die moet worden ingesteld voor het bestand. U kunt deze sleutel maken met behulp van de `Create Permission` bewerking. Houd er rekening mee dat er slechts één van `x-ms-file-permission` of `x-ms-file-permission-key` kan worden opgegeven.
`x-ms-file-copy-ignore-readonly`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. Deze Booleaanse waarde geeft aan of het `ReadOnly` kenmerk van een bestaande doelbestand moet worden gerespecteerd. Als dit is `true`, slaagt de kopieerbewerking. Anders zorgt een eerder bestand op het doel met de `ReadOnly` kenmerkset ervoor dat de kopieerbewerking mislukt.
`x-ms-file-attributes`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. In deze header worden de kenmerken van het bestandssysteem opgegeven die moeten worden ingesteld voor het doelbestand. Bekijk de lijst met beschikbare kenmerken. U kunt de waarde van `source` gebruiken om de kenmerken van het bronbestand naar het doelbestand te kopiëren. U kunt de waarde van `none` gebruiken om alle kenmerken in het doelbestand te wissen.
`x-ms-file-creation-time`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. Deze header geeft de eigenschap op voor de aanmaaktijd, in UTC, die moet worden ingesteld voor het doelbestand. U kunt de waarde van `source` gebruiken om de aanmaaktijd van het bronbestand naar het doelbestand te kopiëren.
`x-ms-file-last-write-time`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. Deze header geeft de eigenschap op voor de laatste schrijftijd, in UTC, die moet worden ingesteld voor het doelbestand. U kunt de waarde van `source` gebruiken om de laatste schrijftijd van het bronbestand naar het doelbestand te kopiëren.
`x-ms-file-copy-set-archive`	Optioneel. Beschikbaar voor versie 2019-07-07 en hoger. Deze Booleaanse waarde geeft aan of het `Archive` kenmerk moet worden ingesteld, ongeacht de `x-ms-file-attributes` headerwaarde.
`x-ms-client-request-id`	Optioneel. Biedt een door de client gegenereerde, ondoorzichtige waarde met een limiet van 1 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 Blob Storage bewaken voor meer informatie.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Optioneel. Versie 2021-06-08 en hoger. De utc-wijzigingstijdeigenschap voor het bestand, opgemaakt in de ISO 8601-indeling. De waarde van `source` kan worden gebruikt om de wijzigingstijd van het bronbestand naar het doelbestand te kopiëren. Het standaardtijdstempel is de tijd van de aanvraag.
`x-ms-file-request-intent`	Vereist als `Authorization` 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 afsluitende punt die aanwezig is in de aanvraag-URL moet worden ingekort of niet. Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevens voor meer informatie.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Optioneel. Versie 2022-11-02 en hoger. De Booleaanse waarde geeft aan of een afsluitende punt in de bron-URL moet worden ingekort of niet. Deze header moet alleen worden opgegeven als de kopieerbron een Azure-bestand is. Deze header wordt niet ondersteund voor een ander type kopieerbron. Zie Naamgeving en verwijzingen naar shares, mappen, bestanden en metagegevens voor meer informatie.

Aanvraagbody

Geen.

Antwoord

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

Statuscode

Een geslaagde bewerking retourneert statuscode 202 (Geaccepteerd).

Zie Status- en foutcodes voor meer informatie over statuscodes.

Antwoordheaders

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

Antwoordheader	Beschrijving
`ETag`	Als de kopieerbewerking is voltooid, bevat deze de `ETag` waarde van het doelbestand. Als de kopieerbewerking niet is voltooid, bevat de `ETag` waarde van het lege bestand dat aan het begin van de bewerking is gemaakt.
`Last-Modified`	Retourneert de datum/tijd waarop de kopieerbewerking naar het doelbestand is voltooid.
`x-ms-request-id`	Identificeert op unieke wijze de aanvraag die is gedaan. U kunt deze header gebruiken om problemen met de aanvraag op te lossen. Zie Problemen met API-bewerkingen oplossen voor meer informatie.
`x-ms-version`	Geeft de versie van Azure Files aan die wordt gebruikt om de aanvraag uit te voeren.
`Date`	Een UTC-datum/tijd-waarde die het tijdstip aangeeft waarop de service het antwoord heeft verzonden.
`x-ms-copy-id: <id>`	Biedt een tekenreeks-id voor deze kopieerbewerking. Gebruik met `Get File` of `Get File Properties` om de status van deze kopieerbewerking te controleren of geef door aan `Abort Copy File` om een in behandeling zijnde kopieerbewerking te annuleren.
`x-ms-copy-status: <success ¦ pending>`	Geeft de status van de kopieerbewerking aan met deze waarden: - `success`: de kopieerbewerking is voltooid. - `pending`: de kopieerbewerking wordt nog uitgevoerd.
`x-ms-client-request-id`	Kan worden gebruikt om problemen met aanvragen en bijbehorende antwoorden op te lossen. 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 maximaal 1024 zichtbare ASCII-tekens is. Als de `x-ms-client-request-id` header niet aanwezig is in de aanvraag, is deze header niet aanwezig in het antwoord.

Hoofdtekst van de reactie

Geen

Voorbeeldantwoord

Response Status:  
HTTP/1.1 202 Accepted  
  
Response Headers:   
Last-Modified: <date>   
ETag: "0x8CEB669D794AFE2"  
Server: Windows-Azure-File/1.0 Microsoft-HTTPAPI/2.0  
x-ms-request-id: cc6b209a-b593-4be1-a38a-dde7c106f402  
x-ms-version: 2015-02-21  
x-ms-copy-id: 1f812371-a41d-49e6-b123-f4b542e851c5  
x-ms-copy-status: pending  
Date: <date>

Autorisatie

Deze bewerking kan worden aangeroepen door de accounteigenaar of door een client die beschikt over een shared access signature die gemachtigd is om naar het doelbestand of de bijbehorende share te schrijven. Houd er rekening mee dat de handtekening voor gedeelde toegang die is opgegeven in de aanvraag alleen van toepassing is op het doelbestand.

Toegang tot het bronbestand of de blob wordt afzonderlijk geautoriseerd, zoals beschreven in de details voor de aanvraagheader x-ms-copy-source.

In de volgende tabel wordt beschreven hoe de doel- en bronobjecten voor een Copy File bewerking kunnen worden geautoriseerd:

File	Autorisatie met gedeelde sleutel of gedeelde sleutel Lite	Autorisatie met Shared Access Signature	Openbaar object waarvoor geen autorisatie is vereist
Doelbestand	Ja	Ja	Niet van toepassing
Bronbestand in hetzelfde account	Ja	Ja	Niet van toepassing
Bronbestand in een ander account	Nee	Ja	Niet van toepassing
Bron-blob in hetzelfde account of een ander account	Nee	Ja	Ja

Bestandssysteemkenmerken

Kenmerk	Win32-bestandskenmerk	Definitie
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	Het bestand heeft het kenmerk Alleen-lezen. Toepassingen kunnen het bestand lezen, maar er niet naar schrijven of verwijderen.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	Het bestand is verborgen. Het is niet opgenomen in een gewone directory-vermelding.
`System`	`FILE_ATTRIBUTE_SYSTEM`	Het besturingssysteem gebruikt een deel van het bestand of gebruikt uitsluitend het bestand.
`None`	`FILE_ATTRIBUTE_NORMAL`	Voor het bestand zijn geen andere kenmerken ingesteld. Dit kenmerk is alleen geldig wanneer het alleen wordt gebruikt.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	Het bestand is een archiefbestand. Toepassingen gebruiken dit kenmerk meestal om bestanden te markeren voor back-up of verwijdering.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	Het bestand wordt gebruikt voor tijdelijke opslag.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	De gegevens van het bestand zijn niet onmiddellijk beschikbaar. Dit bestandssysteemkenmerk biedt voornamelijk compatibiliteit met Windows. Azure Files biedt geen ondersteuning voor offlineopslagopties.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	De service voor inhoudsindexering indexeert het bestand niet.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	De scanner voor gegevensintegriteit op de achtergrond leest de gebruikersgegevensstroom niet. Dit bestandssysteemkenmerk biedt voornamelijk compatibiliteit met Windows.

Opmerkingen

De Copy File bewerking kan asynchroon worden voltooid. U kunt de kopieer-id gebruiken die de x-ms-copy-id antwoordheader retourneert om de status van de kopieerbewerking te controleren of om deze te annuleren. Azure Files kopieert bestanden naar beste vermogen.

Als het doelbestand bestaat, wordt het overschreven. U kunt het doelbestand niet wijzigen terwijl de kopieerbewerking wordt uitgevoerd.

Met de Copy File bewerking wordt altijd de hele bron-blob of het hele bronbestand gekopieerd. Het kopiëren van een bereik van bytes of een set blokken wordt niet ondersteund.

De bron van een Copy File bewerking kan een bestand zijn dat zich in een momentopname van een share bevindt. Het doel van een Copy File bewerking mag geen bestand zijn dat zich in een momentopname van een share bevindt.

Wanneer de bron van een kopieerbewerking waarden opgeeft ETag en er wijzigingen in de bron zijn terwijl de bewerking wordt uitgevoerd, mislukt deze. Een poging om het doelbestand te wijzigen terwijl er een kopieerbewerking wordt uitgevoerd, mislukt met statuscode 409 (conflict).

De ETag waarde voor het doelbestand wordt gewijzigd wanneer de Copy File bewerking wordt gestart. Deze blijft regelmatig veranderen tijdens de kopieerbewerking.

Eigenschappen en metagegevens kopiëren

Wanneer een blob of bestand wordt gekopieerd, worden de volgende systeemeigenschappen met dezelfde waarden gekopieerd naar het doelbestand:

Content-Type
Content-Encoding
Content-Language
Content-Length
Cache-Control
Content-MD5
Content-Disposition

Het doelbestand heeft altijd dezelfde grootte als de bron-blob of het bron-bestand. De waarde van de Content-Length header voor het doelbestand komt overeen met de waarde van die header voor de bron-blob of het bronbestand.

Een geleasede blob of -bestand naar een bestand kopiëren

De Copy File bewerking leest alleen uit de bron-blob of het bronbestand, dus een lease van het bronobject heeft geen invloed op de bewerking. De Copy File bewerking slaat de ETag waarde van de bron-blob of het bronbestand op wanneer de bewerking wordt gestart. Als de ETag waarde verandert voordat de kopieerbewerking is voltooid, mislukt de bewerking. U kunt wijzigingen in de bron-blob van het bestand voorkomen door het te leasen tijdens de kopieerbewerking.

Als het doelbestand een actieve oneindige lease heeft, moet u de lease-id opgeven in de aanroep van de Copy File bewerking. Terwijl de kopieerbewerking in behandeling is, mislukt elke leasebewerking voor het doelbestand met statuscode 409 (conflict). Een oneindige lease van het doelbestand wordt op deze manier vergrendeld tijdens de kopieerbewerking, of u nu kopieert naar een doelbestand met een andere naam dan de bron of kopieert naar een doelbestand met dezelfde naam als de bron. Als de client een lease-id opgeeft voor een bestand dat nog niet bestaat, retourneert Azure Files statuscode 412 (Voorwaarde mislukt).

Werken met een kopieerbewerking die in behandeling is

De Copy File bewerking kan het asynchroon kopiëren van de bestanden voltooien. Gebruik de volgende tabel om de volgende stap te bepalen op basis van de statuscode die Copy File wordt geretourneerd:

Statuscode	Betekenis
202 (Geaccepteerd), x-ms-copy-status: geslaagd	De kopieerbewerking is voltooid.
202 (Geaccepteerd), x-ms-copy-status: in behandeling	De kopieerbewerking is niet voltooid. Controleer de doel-blob met behulp van `Get File Properties` om te onderzoeken `x-ms-copy-status` totdat de kopieerbewerking is voltooid of mislukt.
4xx, 500 of 503	De kopieerbewerking is mislukt.

Tijdens en na een Copy File bewerking bevatten de eigenschappen van het doelbestand de kopie-id van de Copy File bewerking en de URL van de bron-blob of het bronbestand. Wanneer de bewerking is voltooid, schrijft Azure Files de tijd- en resultaatwaarde (success, failedof aborted) naar de eigenschappen van het doelbestand. Als de bewerking een failed resultaat heeft, bevat de x-ms-copy-status-description header een foutdetailtekenreeks.

Een bewerking in behandeling Copy File heeft een time-out van twee weken. Een kopieerpoging die na twee weken nog niet is voltooid, treedt op en laat een leeg bestand achter met het x-ms-copy-status veld ingesteld op failed en het x-ms-status-description veld ingesteld op 500 (OperationCancelled). Onregelmatige, niet-fatale fouten die kunnen optreden tijdens een kopieerbewerking, kunnen de voortgang van de bewerking belemmeren, maar niet tot een fout leiden. In deze gevallen x-ms-copy-status-description worden de onregelmatige fouten beschreven.

Elke poging om het doelbestand tijdens de kopieerbewerking te wijzigen, mislukt met statuscode 409 (conflict), 'Bestand kopiëren wordt uitgevoerd'.

Als u een Abort Copy File bewerking aanroept, ziet u een x-ms-copy-status:aborted header. Het doelbestand heeft intacte metagegevens en een bestandslengte van 0 bytes. U kunt de oorspronkelijke aanroep naar Copy File herhalen om de bewerking opnieuw uit te voeren.

Billing

Het doelaccount van een Copy File bewerking wordt in rekening gebracht voor één transactie om de bewerking te starten. Het doelaccount maakt ook één transactie voor elke aanvraag om de kopieerbewerking te annuleren of om de status van de kopieerbewerking aan te vragen.

Wanneer het bronbestand of de blob zich in een ander account bevindt, brengt het bronaccount transactiekosten in rekening. Als de bron- en doelaccounts zich in verschillende regio's bevinden (bijvoorbeeld US - noord en US - zuid), wordt de bandbreedte die u gebruikt om de aanvraag over te dragen, in rekening gebracht bij het bronaccount als uitgaand verkeer. Uitgaand verkeer tussen accounts binnen dezelfde regio is gratis.