Datei kopieren

Artikel
07/26/2023

Der Copy File Vorgang kopiert ein Blob oder eine Datei in eine Zieldatei innerhalb des Speicherkontos.

Verfügbar in Version 2015-02-21 und höher.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Anforderung

Sie können die Copy File Anforderung wie folgt erstellen. Wir empfehlen HTTPS.

Ab Version 2013-08-15 können Sie eine Shared Access Signature für die Zieldatei angeben, wenn sie sich im selben Konto wie die Quelldatei befindet. Ab Version 2015-04-05 können Sie auch eine Shared Access Signature für die Zieldatei angeben, wenn sie sich in einem anderen Speicherkonto befindet.

Methode	Anforderungs-URI	HTTP-Version
`PUT`	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile`	HTTP/1.1

Ersetzen Sie die im Anforderungs-URI angezeigten Pfadkomponenten wie folgt durch Ihre eigenen Angaben:

Pfadkomponente	BESCHREIBUNG
`myaccount`	Der Name Ihres Speicherkontos.
`myshare`	Der Name der Dateifreigabe.
`mydirectorypath`	Optional. Der Pfad zum übergeordneten Verzeichnis.
`myfile`	Der Name der Datei.

Ausführliche Informationen zu Einschränkungen bei der Pfadbenennung finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

URI-Parameter

Sie können im Anforderungs-URI die folgenden zusätzlichen Parameter angeben:

Parameter	BESCHREIBUNG
`timeout`	Optional. Der timeout-Parameter wird in Sekunden angegeben. Weitere Informationen finden Sie unter Festlegen von Timeouts für Azure Files Vorgänge.

Anforderungsheader

In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben:

Anforderungsheader	BESCHREIBUNG
`Authorization`	Erforderlich. Gibt das Autorisierungsschema, den Kontonamen und die Signatur an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`Date` oder `x-ms-date`	Erforderlich. Gibt die koordinierte Weltzeit (Coordinated Universal Time, UTC) für die Anforderung an. Weitere Informationen finden Sie unter Autorisieren von Anforderungen an Azure Storage.
`x-ms-version`	Erforderlich für alle autorisierten Anforderungen. Gibt die Version des für die Anforderung zu verwendenden Vorgangs an. Dieser Vorgang ist nur in Version 2015-02-21 und höher verfügbar. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure-Speicherdienste.
`x-ms-meta-name:value`	Optional. Gibt Name-Wert-Paare an, die der Datei als Metadaten zugeordnet sind. Wenn keine Name-Wert-Paare angegeben sind, kopiert der Vorgang die Metadaten aus dem Quellblob oder der Quelldatei in die Zieldatei. Wenn mindestens ein Name-Wert-Paar angegeben ist, wird die Zieldatei mit den angegebenen Metadaten erstellt, und die Metadaten werden nicht aus dem Quellblob oder der Quelldatei kopiert. Metadatennamen müssen den Benennungsregeln für C#-Bezeichner entsprechen. Beachten Sie, dass über Azure Files angegebene Dateimetadaten nicht von einem SMB-Client aus zugänglich sind.
`x-ms-copy-source:name`	Erforderlich. Gibt die URL der Quelldatei oder des Blobs mit einer Länge von bis zu 2 Kibibyte (KiB) an. Um eine Datei in eine andere Datei innerhalb desselben Speicherkontos zu kopieren, können Sie einen freigegebenen Schlüssel verwenden, um die Quelldatei zu autorisieren. Wenn Sie eine Datei aus einem anderen Speicherkonto kopieren oder ein Blob aus demselben Speicherkonto oder einem anderen Speicherkonto kopieren, müssen Sie die Quelldatei oder das Blob mithilfe einer Shared Access Signature autorisieren. Wenn es sich bei der Quelle um ein öffentliches Blob handelt, ist keine Autorisierung erforderlich, um den Kopiervorgang auszuführen. Sie können auch eine Datei in einer Freigabe Momentaufnahme als Kopierquelle angeben. Hier sind einige Beispiele für Quellobjekt-URLs: `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>`	Erforderlich, wenn die Zieldatei über eine aktive Lease verfügt. Verfügbar für Version 2019-02-02 und höher. Die für diesen Header angegebene Lease-ID muss mit der Lease-ID der Zieldatei übereinstimmen. Wenn die Anforderung die Lease-ID nicht enthält oder die ID ungültig ist, schlägt der Vorgang mit status Code 412 (Vorbedingung fehlgeschlagen) fehl. Wenn dieser Header angegeben ist und die Zieldatei derzeit keine aktive Lease aufweist, schlägt der Vorgang mit status Code 412 (Vorbedingung fehlgeschlagen) fehl.
`x-ms-file-permission-copy-mode: { source ¦ override }`	Optional. Verfügbar für Version 2019-07-07 und höher. Bestimmt das Kopierverhalten des Sicherheitsdeskriptors der Datei: `source`: Der Sicherheitsdeskriptor für die Zieldatei wird aus der Quelldatei kopiert. `override`: Der Sicherheitsdeskriptor für die Zieldatei wird über den `x-ms-file-permission` -Header oder `x-ms-file-permission-key` bestimmt.
`x-ms-file-permission`	Erforderlich, wenn `x-ms-file-permission-copy-mode` als `override` und `x-ms-file-permission-key` nicht angegeben ist. Verfügbar für Version 2019-07-07 und höher. Diese Berechtigung ist der Sicherheitsdeskriptor für die Datei, die in der SDDL (Security Descriptor Definition Language) angegeben ist. Sie können diesen Header verwenden, wenn die Berechtigungsgröße 8 Kibibyte (KiB) oder weniger beträgt. Andernfalls können Sie verwenden `x-ms-file-permission-key`. Wenn angegeben, muss sie über einen Besitzer, eine Gruppe und eine daCL (Discretionary Access Control List) verfügen. Beachten Sie, dass nur eine von `x-ms-file-permission` oder `x-ms-file-permission-key` angegeben werden kann.
`x-ms-file-permission-key`	Erforderlich, wenn `x-ms-file-permission-copy-mode` als `override` und `x-ms-file-permission` nicht angegeben ist. Verfügbar für Version 2019-07-07 und höher. Dieser Header gibt den Schlüssel der Berechtigung an, die für die Datei festgelegt werden soll. Sie können diesen Schlüssel mithilfe des -Vorgangs `Create Permission` erstellen. Beachten Sie, dass nur eine von `x-ms-file-permission` oder `x-ms-file-permission-key` angegeben werden kann.
`x-ms-file-copy-ignore-readonly`	Optional. Verfügbar für Version 2019-07-07 und höher. Dieser boolesche Wert gibt an, ob das `ReadOnly` Attribut für eine bereits vorhandene Zieldatei berücksichtigt werden soll. Wenn der Wert ist `true`, ist der Kopiervorgang erfolgreich. Andernfalls führt eine vorherige Datei am Ziel mit festgelegtem `ReadOnly` Attribut dazu, dass der Kopiervorgang fehlschlägt.
`x-ms-file-attributes`	Optional. Verfügbar für Version 2019-07-07 und höher. Dieser Header gibt die Dateisystemattribute an, die für die Zieldatei festgelegt werden sollen. Weitere Informationen finden Sie in der Liste der verfügbaren Attribute. Sie können den Wert von `source` verwenden, um die Attribute aus der Quelldatei in die Zieldatei zu kopieren. Sie können den Wert verwenden `none` , um alle Attribute in der Zieldatei zu löschen.
`x-ms-file-creation-time`	Optional. Verfügbar für Version 2019-07-07 und höher. Dieser Header gibt die Eigenschaft für die Erstellungszeit in UTC an, die für die Zieldatei festgelegt werden soll. Sie können den Wert von `source` verwenden, um die Erstellungszeit aus der Quelldatei in die Zieldatei zu kopieren.
`x-ms-file-last-write-time`	Optional. Verfügbar für Version 2019-07-07 und höher. Dieser Header gibt die Eigenschaft für die letzte Schreibzeit in UTC an, die für die Zieldatei festgelegt werden soll. Sie können den Wert von `source` verwenden, um die letzte Schreibzeit aus der Quelldatei in die Zieldatei zu kopieren.
`x-ms-file-copy-set-archive`	Optional. Verfügbar für Version 2019-07-07 und höher. Dieser boolesche Wert gibt an, ob das `Archive` Attribut unabhängig vom `x-ms-file-attributes` Headerwert festgelegt werden soll.
`x-ms-client-request-id`	Optional. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem Zeichenlimit von 1 KiB bereit, der beim Konfigurieren der Protokollierung in den Protokollen aufgezeichnet wird. Es wird dringend empfohlen, diesen Header zu verwenden, um clientseitige Aktivitäten mit Anforderungen zu korrelieren, die der Server empfängt. Weitere Informationen finden Sie unter Überwachen Azure Blob Storage.
`x-ms-file-change-time: { <DateTime> ¦ source }`	Optional. Version 2021-06-08 und höher. Die UTC-Änderungszeiteigenschaft für die Datei, die im ISO 8601-Format formatiert ist. Der Wert von `source` kann verwendet werden, um die Änderungszeit aus der Quelldatei in die Zieldatei zu kopieren. Der Standardzeitstempel ist die Zeit der Anforderung.
`x-ms-file-request-intent`	Erforderlich, wenn `Authorization` der Header ein OAuth-Token angibt. Zulässiger Wert ist `backup`. Dieser Header gibt an, dass oder `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/actionMicrosoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` gewährt werden soll, wenn sie in der RBAC-Richtlinie enthalten sind, die der Identität zugewiesen ist, die mithilfe des `Authorization` Headers autorisiert ist. Verfügbar für Version 2022-11-02 und höher.
`x-ms-allow-trailing-dot: { <Boolean> }`	Optional. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein in der Anforderungs-URL vorhandener nachgestellter Punkt gekürzt werden soll oder nicht. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Optional. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Quell-URL gekürzt werden soll oder nicht. Dieser Header sollte nur angegeben werden, wenn es sich bei der Kopierquelle um eine Azure-Datei handelt. Dieser Header wird für keinen anderen Kopierquelltyp unterstützt. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.

Anforderungstext

Keine.

Antwort

Die Antwort enthält den HTTP-Statuscode und einen Satz von Antwortheadern.

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 202 (Akzeptiert) zurück.

Informationen zu status Codes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang umfasst die folgenden Header. Die Antwort enthält außerdem weitere HTTP-Standardheader. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	BESCHREIBUNG
`ETag`	Wenn der Kopiervorgang abgeschlossen ist, enthält den `ETag` Wert der Zieldatei. Wenn der Kopiervorgang nicht abgeschlossen ist, enthält den `ETag` Wert der leeren Datei, die zu Beginn des Vorgangs erstellt wurde.
`Last-Modified`	Gibt das Datum/die Uhrzeit zurück, an dem der Kopiervorgang in die Zieldatei abgeschlossen wurde.
`x-ms-request-id`	Identifiziert eindeutig die Anforderung, die gestellt wurde. Sie können diesen Header verwenden, um probleme mit der Anforderung zu beheben. Weitere Informationen finden Sie unter Problembehandlung bei API-Vorgängen.
`x-ms-version`	Gibt die Version von Azure Files an, die zum Ausführen der Anforderung verwendet wird.
`Date`	Ein UTC-Datums-/Uhrzeitwert, der die Uhrzeit angibt, zu der der Dienst die Antwort gesendet hat.
`x-ms-copy-id: <id>`	Stellt einen Zeichenfolgenbezeichner für diesen Kopiervorgang bereit. Verwenden Sie mit `Get File` oder`Get File Properties`, um die status dieses Kopiervorgangs zu überprüfen, oder übergeben Sie an, um `Abort Copy File` einen ausstehenden Kopiervorgang abzubrechen.
`x-ms-copy-status: <success ¦ pending>`	Gibt den Zustand des Kopiervorgangs mit den folgenden Werten an: - `success`: Der Kopiervorgang wurde erfolgreich abgeschlossen. - `pending`: Der Kopiervorgang wird noch ausgeführt.
`x-ms-client-request-id`	Kann verwendet werden, um Anforderungen und entsprechende Antworten zu behandeln. Der Wert dieses Headers ist gleich dem Wert des `x-ms-client-request-id` Headers, wenn er in der Anforderung vorhanden ist und der Wert höchstens 1.024 sichtbare ASCII-Zeichen aufweist. Wenn der `x-ms-client-request-id` Header in der Anforderung nicht vorhanden ist, ist dieser Header in der Antwort nicht vorhanden.

Antworttext

Keine

Beispiel für eine Antwort

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>

Authorization

Dieser Vorgang kann vom Kontobesitzer oder von einem Client aufgerufen werden, der über eine freigegebene Zugriffssignatur verfügt, die über die Berechtigung zum Schreiben in die Zieldatei oder deren Freigabe verfügt. Beachten Sie, dass die in der Anforderung angegebene Shared Access Signature nur für die Zieldatei gilt.

Der Zugriff auf die Quelldatei oder das Blob wird separat autorisiert, wie in den Details für den Anforderungsheader x-ms-copy-sourcebeschrieben.

In der folgenden Tabelle wird beschrieben, wie die Ziel- und Quellobjekte für einen Copy File Vorgang autorisiert werden können:

Datei	Autorisierung mit freigegebenem Schlüssel oder freigegebenem Schlüssel Lite	Autorisierung mit Shared Access Signature	Öffentliches Objekt, das keine Autorisierung erfordert
Zieldatei	Ja	Ja	Nicht zutreffend
Quelldatei im selben Konto	Ja	Ja	Nicht zutreffend
Quelldatei in einem anderen Konto	Nein	Ja	Nicht zutreffend
Quellblob im selben Konto oder einem anderen Konto	Nein	Ja	Ja

Dateisystemattribute

attribute	Win32-Dateiattribute	Definition
`ReadOnly`	`FILE_ATTRIBUTE_READONLY`	Die Datei ist schreibgeschützt. Anwendungen können die Datei lesen, aber nicht in sie schreiben oder löschen.
`Hidden`	`FILE_ATTRIBUTE_HIDDEN`	Die Datei ist ausgeblendet. Es ist nicht in einer normalen Verzeichnisliste enthalten.
`System`	`FILE_ATTRIBUTE_SYSTEM`	Das Betriebssystem verwendet einen Teil der Datei, oder es verwendet die Datei ausschließlich.
`None`	`FILE_ATTRIBUTE_NORMAL`	Für die Datei sind keine anderen Attribute festgelegt. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
`Archive`	`FILE_ATTRIBUTE_ARCHIVE`	Die Datei ist eine Archivdatei. Anwendungen verwenden dieses Attribut in der Regel, um Dateien für die Sicherung oder Entfernung zu markieren.
`Temporary`	`FILE_ATTRIBUTE_TEMPORARY`	Die Datei wird für den temporären Speicher verwendet.
`Offline`	`FILE_ATTRIBUTE_OFFLINE`	Die Daten der Datei sind nicht sofort verfügbar. Dieses Dateisystem-Attribut bietet hauptsächlich Kompatibilität mit Windows. Azure Files unterstützt dies nicht mit Offlinespeicheroptionen.
`NotContentIndexed`	`FILE_ATTRIBUTE_NOT_CONTENT_INDEXED`	Der Inhaltsindizierungsdienst indiziert die Datei nicht.
`NoScrubData`	`FILE_ATTRIBUTE_NO_SCRUB_DATA`	Der Datenintegritätsscanner im Hintergrund liest den Benutzerdatenstrom nicht. Dieses Dateisystem-Attribut bietet hauptsächlich Kompatibilität mit Windows.

Bemerkungen

Der Copy File Vorgang kann asynchron abgeschlossen werden. Sie können die vom Antwortheader zurückgegebene Kopier-ID verwenden, x-ms-copy-id um die status des Kopiervorgangs zu überprüfen oder abzubrechen. Azure Files kopiert Dateien nach bestem Aufwand.

Wenn die Zieldatei vorhanden ist, wird sie überschrieben. Sie können die Zieldatei nicht ändern, während der Kopiervorgang ausgeführt wird.

Der Copy File Vorgang kopiert immer das gesamte Quellblob oder die gesamte Quelldatei. Das Kopieren eines Bytebereichs oder einer Gruppe von Blöcken wird nicht unterstützt.

Die Quelle eines Copy File Vorgangs kann eine Datei sein, die sich in einer Freigabe Momentaufnahme befindet. Das Ziel eines Copy File Vorgangs darf keine Datei sein, die sich in einer Freigabe Momentaufnahme befindet.

Wenn die Quelle eines Kopiervorgangs Werte bereitstellt ETag und änderungen an der Quelle vorgenommen werden, während der Vorgang ausgeführt wird, tritt ein Fehler auf. Ein Versuch, die Zieldatei zu ändern, während ein Kopiervorgang ausgeführt wird, schlägt mit status Code 409 (Konflikt) fehl.

Der ETag Wert für die Zieldatei ändert sich, wenn der Copy File Vorgang gestartet wird. Sie ändert sich während des Kopiervorgangs weiterhin häufig.

Kopieren von Eigenschaften und Metadaten

Wenn ein Blob oder eine Datei kopiert wird, werden die folgenden Systemeigenschaften mit den gleichen Werten in die Zieldatei kopiert:

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

Die Zieldatei hat immer dieselbe Größe wie das Quellblob oder die Quelldatei. Der Wert des Headers Content-Length für die Zieldatei entspricht dem Wert dieses Headers für das Quellblob oder die Quelldatei.

Kopieren eines geleasten Blobs oder einer Datei in eine Datei

Der Copy File Vorgang liest nur aus dem Quellblob oder der Quelldatei, sodass sich eine Lease für das Quellobjekt nicht auf den Vorgang auswirkt. Der Copy File Vorgang speichert den ETag Wert des Quellblobs oder der Quelldatei, wenn der Vorgang gestartet wird. Wenn sich der ETag Wert ändert, bevor der Kopiervorgang abgeschlossen ist, schlägt der Vorgang fehl. Sie können Änderungen am Quellblob der Datei verhindern, indem Sie sie während des Kopiervorgangs leasen.

Wenn die Zieldatei über eine aktive unendliche Lease verfügt, müssen Sie ihre Lease-ID im Aufruf des Vorgangs Copy File angeben. Während der Kopiervorgang aussteht, schlägt jeder Leasevorgang für die Zieldatei mit status Code 409 (Konflikt) fehl. Eine unbegrenzte Lease für die Zieldatei wird während des Kopiervorgangs auf diese Weise gesperrt, unabhängig davon, ob Sie in eine Zieldatei kopieren, die einen anderen Namen als die Quelle hat, oder in eine Zieldatei mit demselben Namen wie die Quelle kopieren. Wenn der Client eine Lease-ID für eine Datei angibt, die noch nicht vorhanden ist, gibt Azure Files status Code 412 (Vorbedingung fehlgeschlagen) zurück.

Arbeiten mit einem ausstehenden Kopiervorgang

Der Copy File Vorgang kann das asynchrone Kopieren der Dateien beenden. Verwenden Sie die folgende Tabelle, um den nächsten Schritt basierend auf dem status Code zu ermitteln, Copy File der zurückgegeben wird:

Statuscode	Bedeutung
202 (Akzeptiert), x-ms-copy-status: success	Der Kopiervorgang wurde erfolgreich abgeschlossen.
202 (Akzeptiert), x-ms-copy-status: pending	Der Kopiervorgang wurde nicht abgeschlossen. Rufen Sie das Zielblob mit `Get File Properties` ab, um zu untersuchen `x-ms-copy-status` , bis der Kopiervorgang abgeschlossen ist oder fehlschlägt.
4xx, 500 oder 503	Fehler beim Kopiervorgang.

Während und nach einem Copy File Vorgang enthalten die Eigenschaften der Zieldatei die Kopier-ID des Copy File Vorgangs und die URL des Quellblobs oder der Quelldatei. Nach Abschluss des Vorgangs schreibt Azure Files den Zeit- und Ergebniswert (success, failedoder aborted) in die Eigenschaften der Zieldatei. Wenn der Vorgang ein failed Ergebnis hat, enthält der x-ms-copy-status-description Header eine Fehlerdetailseitezeichenfolge.

Ein ausstehender Copy File Vorgang weist ein Timeout von zwei Wochen auf. Bei einem Kopierversuch, der nach zwei Wochen noch nicht abgeschlossen ist, wird eine leere Datei mit dem x-ms-copy-status Feld auf failed festgelegt und das x-ms-status-description Feld auf 500 (OperationCancelled) festgelegt. Zeitweilige, nicht schwerwiegende Fehler, die während eines Kopiervorgangs auftreten können, können den Fortschritt des Vorgangs beeinträchtigen, aber nicht dazu führen, dass er fehlschlägt. In diesen Fällen werden die vorübergehenden Fehler von x-ms-copy-status-description beschrieben.

Jeder Versuch, die Zieldatei während des Kopiervorgangs zu ändern, schlägt mit status Code 409 (Konflikt), "Datei in Bearbeitung kopieren" fehl.

Wenn Sie einen Abort Copy File Vorgang aufrufen, wird ein x-ms-copy-status:aborted Header angezeigt. Die Zieldatei verfügt über intakte Metadaten und eine Dateilänge von 0 Bytes. Sie können den ursprünglichen Aufruf von Copy File wiederholen, um den Vorgang erneut zu versuchen.

Abrechnung

Das Zielkonto eines Copy File Vorgangs wird für eine Transaktion zum Starten des Vorgangs in Rechnung gestellt. Das Zielkonto verursacht außerdem eine Transaktion für jede Anforderung, um die status des Kopiervorgangs abzubrechen oder anzufordern.

Wenn sich die Quelldatei oder das Blob in einem anderen Konto befindet, fallen für das Quellkonto Transaktionskosten an. Wenn sich die Quell- und Zielkonten in verschiedenen Regionen befinden (z. B. "USA, Norden" und "USA, Süden"), wird außerdem die Bandbreite, die Sie zum Übertragen der Anforderung verwenden, dem Quellkonto als ausgehender Datenverkehr in Rechnung gestellt. Der Ausgang zwischen Konten innerhalb derselben Region ist kostenlos.