Datei umbenennen

Artikel
08/07/2024

Der Rename File Vorgang benennt eine Datei um und kann optional Systemeigenschaften für die Datei festlegen. Diese API ist in Version 2021-04-10 und höher verfügbar.

Protokollverfügbarkeit

Aktiviertes Dateifreigabeprotokoll	Verfügbar
SMB
NFS

Bitten

Sie können die Rename File Anforderung wie folgt erstellen. HTTPS wird empfohlen.

Methode	Anforderungs-URI	HTTP-Version
STELLEN	`https://myaccount.file.core.windows.net/myshare/mydirectorypath/myfile?comp=rename`	HTTP/1.1

Ersetzen Sie die pfadkomponenten, die im Anforderungs-URI angezeigt werden, wie folgt:

Pfadkomponente	Beschreibung
`myaccount`	Der Name Ihres Speicherkontos.
`myshare`	Der Name Ihrer Dateifreigabe.
`mydirectorypath`	Wahlfrei. Der Pfad zum übergeordneten Zielverzeichnis.
`myfile`	Der Name der Zieldatei.

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

URI-Parameter

Sie können den folgenden zusätzlichen Parameter für den Anforderungs-URI angeben.

Parameter	Beschreibung
`timeout`	Wahlfrei. Der parameter `timeout` wird in Sekunden ausgedrückt. 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 (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 Vorgangs an, der für diese Anforderung verwendet werden soll. Weitere Informationen finden Sie unter Versionsverwaltung für die Azure Storage-Dienste.
`x-ms-file-rename-source:name`	Erforderlich. Vollständiger URI der datei, die umbenannt werden soll.
`x-ms-file-rename-replace-if-exists`	Wahlfrei. Wenn die Zieldatei bereits vorhanden ist, überschreiben Sie die Datei.
`x-ms-file-rename-ignore-readonly`	Wahlfrei. Wenn die Zieldatei mit dem attribut `readonly` vorhanden ist, überschreiben Sie die Datei. Wenn wahr, muss `x-ms-file-rename-replace-if-exists` auch wahr sein.
`x-ms-content-Type`	Wahlfrei. Legt den Inhaltstyp der Datei fest. Wenn diese Eigenschaft für die Anforderung nicht angegeben ist, wird die Eigenschaft für die Datei beibehalten.
`x-ms-file-permission: { preserve ¦ <SDDL> ¦ <binary> }`	Optional, wenn `x-ms-file-permission-key` nicht angegeben ist. Diese Berechtigung ist der Sicherheitsdeskriptor für die Datei, die in der Security Descriptor Definition Language (SDDL) oder (Version 2024-11-04 oder höher) im base64-codierten binären Sicherheitsdeskriptorformatangegeben ist. Sie können angeben, welches Format mit der `x-ms-file-permission-format` Kopfzeile verwendet werden soll. Sie können diesen Header verwenden, wenn die Berechtigungsgröße 8 Kibibyte (KiB) oder weniger beträgt. Andernfalls können Sie `x-ms-file-permission-key`verwenden. Wenn angegeben, muss diese Berechtigung über einen Besitzer, eine Gruppe und verfügen. Sie können einen Wert von `preserve` übergeben, wenn Sie einen vorhandenen Wert unverändert beibehalten möchten. Beachten Sie, dass Sie entweder `x-ms-file-permission` oder `x-ms-file-permission-key`angeben können, nicht beide.
`x-ms-file-permission-format: { sddl ¦ binary }`	Wahlfrei. Version 2024-11-04 oder höher. Gibt an, ob sich der in `x-ms-file-permission` übergebene Wert in SDDL oder im Binärformat befindet. Wenn `x-ms-file-permission-key` auf `preserve`festgelegt ist, sollte diese Kopfzeile nicht festgelegt werden. Wenn `x-ms-file-permission-key` auf einen anderen Wert als `preserve`festgelegt ist und wenn dieser Header nicht festgelegt ist, wird der Standardwert `sddl` verwendet.
`x-ms-file-permission-key`	Optional, wenn `x-ms-file-permission` nicht angegeben ist. Der Schlüssel der Berechtigung, die für die Datei festgelegt werden soll. Sie können dies mithilfe der `Create-Permission`-API erstellen. Beachten Sie, dass Sie entweder `x-ms-file-permission` oder `x-ms-file-permission-key`angeben können, nicht beide.
`x-ms-file-attributes`	Wahlfrei. Die Dateisystemattribute, die für die Datei festgelegt werden sollen. Sehen Sie sich die Liste der verfügbaren Attributean. Sie können einen Wert von `preserve` übergeben, wenn Sie einen vorhandenen Wert unverändert beibehalten möchten. Wenn Sie diese Eigenschaft für die Anforderung nicht angeben, wird die Eigenschaft für die Datei beibehalten.
`x-ms-file-creation-time`	Wahlfrei. Die UTC-Erstellungszeiteigenschaft für eine Datei. Sie können einen Wert von `preserve` übergeben, wenn Sie einen vorhandenen Wert unverändert beibehalten möchten. Wenn Sie diese Eigenschaft für die Anforderung nicht angeben, wird die Eigenschaft für die Datei beibehalten.
`x-ms-file-last-write-time`	Wahlfrei. Die UTC-Eigenschaft für die letzte Schreibzugriffseigenschaft für eine Datei. Sie können einen Wert von `preserve` übergeben, wenn Sie einen vorhandenen Wert unverändert beibehalten möchten. Wenn Sie diese Eigenschaft für die Anforderung nicht angeben, wird die Eigenschaft für die Datei beibehalten.
`x-ms-source-lease-id:<ID>`	Erforderlich, wenn die Quelldatei über eine aktive Lease verfügt.
`x-ms-destination-lease-id:<ID>`	Erforderlich, wenn die Zieldatei über eine aktive Lease verfügt.
`x-ms-client-request-id`	Wahlfrei. Stellt einen vom Client generierten, undurchsichtigen Wert mit einem 1-Kibibyte-Zeichenlimit (KiB) bereit, der in den Protokollen aufgezeichnet wird, wenn die Protokollierung konfiguriert ist. 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 von Azure Blob Storage.
`x-ms-meta-name:value`	Wahlfrei. Legt ein Name-Wert-Paar für die Datei fest. Jeder Aufruf dieses Vorgangs ersetzt alle vorhandenen Metadaten, die der Datei zugeordnet sind. Metadatennamen müssen den Benennungsregeln für C#-Bezeichnerentsprechen.
`x-ms-file-request-intent`	Erforderlich, wenn `Authorization` Header ein OAuth-Token angibt. Zulässiger Wert ist `backup`. Dieser Header gibt an, dass die `Microsoft.Storage/storageAccounts/fileServices/readFileBackupSemantics/action` oder `Microsoft.Storage/storageAccounts/fileServices/writeFileBackupSemantics/action` gewährt werden sollen, 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> }`	Wahlfrei. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Anforderungs-URL gekürzt werden soll. Weitere Informationen finden Sie unter Benennen und Verweisen auf Freigaben, Verzeichnisse, Dateien und Metadaten.
`x-ms-source-allow-trailing-dot: { <Boolean> }`	Wahlfrei. Version 2022-11-02 und höher. Der boolesche Wert gibt an, ob ein nachgestellter Punkt in der Quell-URL gekürzt werden soll. 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

Nichts.

Antwort

Die Antwort enthält einen HTTP-Statuscode und eine Reihe von Antwortheadern.

Statuscode

Ein erfolgreicher Vorgang gibt den Statuscode 200 (OK) zurück. Informationen zu Statuscodes finden Sie unter Status- und Fehlercodes.

Antwortheader

Die Antwort für diesen Vorgang enthält die folgenden Header. Die Antwort kann auch zusätzliche, standardmäßige HTTP-Header enthalten. Alle Standardheader entsprechen der HTTP/1.1-Protokollspezifikation.

Antwortheader	Beschreibung
`ETag`	Enthält einen Wert, der die Version der Datei in Anführungszeichen darstellt.
`Last-Modified`	Gibt das Datum und die Uhrzeit der letzten Änderung der Datei zurück. Weitere Informationen finden Sie unter Darstellung von Datums-/Uhrzeitwerten in Kopfzeilen. Jeder Vorgang, der das Verzeichnis oder seine Eigenschaften ändert, aktualisiert den Zeitpunkt der letzten Änderung. Vorgänge für Dateien wirken sich nicht auf die Uhrzeit der letzten Änderung des Verzeichnisses aus.
`x-ms-request-id`	Identifiziert die anforderung eindeutig und kann für die Problembehandlung der Anforderung verwendet werden. Weitere Informationen finden Sie unter Problembehandlung für API-Vorgänge.
`x-ms-version`	Gibt die Version von Azure Files an, die zum Ausführen der Anforderung verwendet wird.
`Date` oder `x-ms-date`	Ein UTC-Datums-/Uhrzeitwert, der die Uhrzeit angibt, zu der die Antwort initiiert wurde. Der Dienst generiert diesen Wert.
`x-ms-request-server-encrypted: true/false`	Der Wert dieses Headers wird auf `true` festgelegt, wenn der Inhalt der Anforderung mithilfe des angegebenen Algorithmus erfolgreich verschlüsselt wird. Andernfalls wird der Wert auf `false`festgelegt.
`x-ms-file-permission-key`	Der Schlüssel der Berechtigung der Datei.
`x-ms-file-attributes`	Die Dateisystemattribute in der Datei. Sehen Sie sich die Liste der verfügbaren Attributean.
`x-ms-file-creation-time`	Der UTC-Datums-/Uhrzeitwert, der die Erstellungszeiteigenschaft für die Datei darstellt.
`x-ms-file-last-write-time`	Der UTC-Datums-/Uhrzeitwert, der die letzte Schreibzeiteigenschaft für die Datei darstellt.
`x-ms-file-change-time`	Der UTC-Datums-/Uhrzeitwert, der die Änderungszeiteigenschaft für die Datei darstellt.
`x-ms-file-file-id`	Die Datei-ID der Datei.
`x-ms-file-parent-id`	Die übergeordnete Datei-ID der Datei.
`x-ms-client-request-id`	Kann verwendet werden, um Anfragen 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. Der Wert beträgt höchstens 1.024 sichtbare ASCII-Zeichen. Wenn der `x-ms-client-request-id`-Header in der Anforderung nicht vorhanden ist, ist er in der Antwort nicht vorhanden.

Antworttext

Nichts.

Ermächtigung

Nur der Kontobesitzer kann diesen Vorgang aufrufen.

Dateisystemattribute

Attribut	Win32-Dateiattribute	Definition
`ReadOnly`	FILE_ATTRIBUTE_READONLY	Eine Datei, die schreibgeschützt ist. Anwendungen können die Datei lesen, aber nicht in die Datei schreiben oder löschen.
`Hidden`	FILE_ATTRIBUTE_HIDDEN	Die Datei ist ausgeblendet. Sie ist nicht in einer normalen Verzeichnisauflistung enthalten.
`System`	FILE_ATTRIBUTE_SYSTEM	Eine Datei, von der das Betriebssystem ausschließlich einen Teil oder ausschließlich verwendet.
`None`	FILE_ATTRIBUTE_NORMAL	Eine Datei, die keine anderen Attribute festgelegt hat. Dieses Attribut ist nur gültig, wenn es allein verwendet wird.
`Archive`	FILE_ATTRIBUTE_ARCHIVE	Eine Datei, die eine Archivdatei ist. Anwendungen verwenden dieses Attribut in der Regel, um Dateien für die Sicherung oder Entfernung zu markieren.
`Temporary`	FILE_ATTRIBUTE_TEMPORARY	Eine Datei, die für temporären Speicher verwendet wird.
`Offline`	FILE_ATTRIBUTE_OFFLINE	Die Daten einer Datei sind nicht sofort verfügbar. Dieses Dateisystem-Attribut wird in erster Linie zur Bereitstellung der Kompatibilität mit Windows dargestellt. Azure Files unterstützt keine Offlinespeicheroptionen.
`NotContentIndexed`	FILE_ATTRIBUTE_NOT_CONTENT_INDEXED	Die Datei muss nicht vom Inhaltsindizierungsdienst indiziert werden.
`NoScrubData`	FILE_ATTRIBUTE_NO_SCRUB_DATA	Der Benutzerdatenstrom muss nicht vom Hintergrunddatenintegritätsscanner gelesen werden. Dieses Dateisystem-Attribut wird in erster Linie zur Bereitstellung der Kompatibilität mit Windows dargestellt.

Bemerkungen

Das Ziel kann kein vorhandenes Verzeichnis sein.

Wenn Sie keine Eigenschaften angeben, wird das Standardverhalten von preserve oder now festgelegt.

Anmerkung

Die vorherigen Dateieigenschaften sind von den Dateisystemeigenschaften getrennt, die für SMB-Clients verfügbar sind. SMB-Clients können diese Eigenschaftswerte nicht lesen, schreiben oder ändern.

Rename File wird für eine Freigabemomentaufnahme nicht unterstützt, bei der es sich um eine schreibgeschützte Kopie einer Freigabe handelt. Wenn Sie versuchen, diesen Vorgang für eine Freigabemomentaufnahme auszuführen, gibt der Dienst den Fehlerstatus 400 (Ungültiger Abfrageparameterwert) zurück.

Wenn die Datei über eine aktive Lease verfügt, muss der Client eine gültige Lease-ID für die Anforderung angeben, um die Datei umzubenennen. Wenn der Client keine Lease-ID angibt oder eine ungültige Lease-ID angibt, gibt Azure Files den Statuscode 412 zurück (Vorbedingung fehlgeschlagen). Wenn der Client eine Lease-ID angibt, die Datei jedoch nicht über eine aktive Lease verfügt, gibt Azure Files auch den Statuscode 412 zurück (Vorbedingung fehlgeschlagen).

Siehe auch

Vorgänge für Dateien

Freigeben über