Umbenennen von Objekten in Verzeichnis-Buckets - Amazon Simple Storage Service

Umbenennen von Objekten in Verzeichnis-Buckets

Mit dem Vorgang RenameObject können Sie ein vorhandenes Objekt in einem Verzeichnis-Bucket, das die Speicherklasse S3 Express One Zone verwendet, atomar umbenennen, ohne Daten zu bewegen. Sie können ein Objekt umbenennen, indem Sie den Namen des vorhandenen Objekts als Quelle und den neuen Namen des Objekts als Ziel innerhalb desselben Verzeichnis-Buckets angeben. Die RenameObject-API-Operation wird bei Objekten, die mit dem Trennzeichen Schrägstrich (/) enden, nicht erfolgreich sein. Weitere Informationen finden Sie unter Benennen von Amazon-S3-Objekten.

Der Vorgang RenameObject wird in der Regel in Millisekunden abgeschlossen, unabhängig von der Größe des Objekts. Diese Fähigkeit beschleunigt Anwendungen wie die Verwaltung von Protokollen, die Medienverarbeitung und die Datenanalytik. Darüber hinaus bleiben bei RenameObject alle Metadateneigenschaften des Objekts erhalten, einschließlich der Speicherklasse, des Verschlüsselungstyps, des Erstellungsdatums, des Datums der letzten Änderung und der Prüfsummeneigenschaften.

Anmerkung

RenameObject wird nur für Objekte unterstützt, die in der Speicherklasse S3 Express One Zone gespeichert sind.

Um den Zugriff auf die Operation RenameObject zu gewähren, empfehlen wir Ihnen, die Operation CreateSession für die sitzungsbasierte Autorisierung zu verwenden. Konkret gewähren Sie die Berechtigung s3express:CreateSession für den Verzeichnis-Bucket in einer Bucket-Richtlinie oder einer identitätsbasierten Richtlinie. Anschließend führen Sie den API-Aufruf CreateSession auf dem Verzeichnis-Bucket aus, um ein Sitzungs-Token zu erhalten. Mit dem Sitzungs-Token in Ihrem Anfrage-Header können Sie API-Anforderungen für diesen Vorgang stellen. Wenn das Sitzungs-Token abläuft, müssen Sie einen weiteren CreateSession API-Aufruf tätigen, um ein neues Sitzungs-Token zur Verwendung zu generieren. Die AWS CLI und AWS SDKs erstellen und verwalten Ihre Sitzung, einschließlich der automatischen Aktualisierung des Sitzungstokens, um Dienstunterbrechungen zu vermeiden, wenn eine Sitzung abläuft. Weitere Informationen finden Sie unter CreateSession in der Amazon-S3-API-Referenz. Weitere Informationen zu Zonal-Endpunkt-API-Vorgängen finden Sie unter Autorisieren von Zonal-Endpunkt-API-Vorgängen mit CreateSession.

Wenn Sie ein vorhandenes Objekt nicht überschreiben möchten, können Sie den If-None-Match bedingten Header mit dem Wert ‘*’ in der RenameObject-Anfrage hinzufügen. Amazon S3 gibt einen 412 Precondition Failed-Fehler zurück, wenn der Objektname bereits existiert. Weitere Informationen finden Sie unter RenameObject in der Amazon-S3-API-Referenz.

RenameObject ist eine API-Operation für zonale Endpunkte (Vorgang auf Objektebene oder Datenebene), bei AWS CloudTrail angemeldet ist. Sie können CloudTrail verwenden, um Informationen über die RenameObject Operation zu sammeln, die an Ihren Objekten in Verzeichnis-Buckets durchgeführt wird. Weitere Informationen finden Sie unter Protokollierung mit AWS CloudTrail für Verzeichnis-Buckets und Beispiele für CloudTrail-Protokolldateien für Verzeichnis-Buckets.

S3 Express One Zone ist die einzige Speicherklasse, die RenameObject unterstützt. Der Preis für diese Anfrage entspricht dem Preis für PUT, COPY, POST und LIST-Anfragen (pro 1.000 Anfragen) in S3 Express One Zone. Weitere Informationen finden Sie unter Amazon S3 – Preise.

Umbenennen eines Objekts

Um ein Objekt in Ihrem Verzeichnis-Bucket umzubenennen, können Sie die Amazon-S3-Konsole, AWS CLI, AWS SDKs, die REST-API oder Mountpoint für Amazon S3 (Version 1.19.0 oder höher) verwenden.

So benennen Sie ein Objekt in einem Verzeichnis-Bucket um
  1. Melden Sie sich bei der AWS-Managementkonsole an und öffnen Sie die Amazon-S3-Konsole unter https://console.aws.amazon.com/s3/.

  2. Wählen Sie im Navigationsbereich Buckets und dann die Registerkarte Verzeichnis-Buckets. Navigieren Sie zu dem Amazon S3-Verzeichnis-Bucket, das das Objekt enthält, das Sie umbenennen möchten.

  3. Aktivieren Sie das Kontrollkästchen für das Objekt, das Sie umbenennen möchten.

  4. Wählen Sie im Menü Aktionen die Option Objekt umbenennen aus.

  5. Geben Sie im Feld Neuer Objektname den neuen Namen für das Objekt ein.

    Anmerkung

    Wenn Sie denselben Objektnamen wie ein vorhandenes Objekt angeben, schlägt der Vorgang fehl und Amazon S3 gibt einen 412 Precondition Failed Fehler zurück. Die Länge des Objektschlüsselnamens darf 1.024 Bytes nicht überschreiten. Im Objektnamen enthaltene Präfixe werden auf die Gesamtlänge angerechnet.

  6. Wählen Sie Objekt umbenennen. Amazon S3 benennt Ihr Objekt um.

Die rename-object Beispiele zeigen, wie Sie die AWS CLI verwenden können, um ein Objekt umzubenennen. Um diese Befehle auszuführen, ersetzen Sie die Benutzereingabe-Platzhalter durch Ihre eigenen Informationen

Das folgende Beispiel zeigt, wie man ein Objekt mit einer bedingten Prüfung des ETag des Quellobjekts umbenennt.

aws s3api rename-object \ --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \ --key new-file.txt \ --rename-source original-file.txt \ --source-if-match "\"a1b7c3d2e5f6\""

Der Befehl hat folgende Auswirkungen:

  • Benennt ein Objekt im amzn-s3-demo-bucket--usw2-az1--x-s3 Verzeichnis-Bucket von original-file.txt in new-file.txt um.

  • Führt die Umbenennung nur durch, wenn das ETag des Quellobjekts mit „a1b7c3d4e5f6“ übereinstimmt.

Wenn der ETag nicht übereinstimmt, schlägt der Vorgang mit einem 412 Precondition Failed Fehler fehl.

Das folgende Beispiel zeigt, wie ein Objekt mit einer bedingten Prüfung auf den neu angegebenen Objektnamen umbenannt werden kann.

aws s3api rename-object \ --bucket amzn-s3-demo-bucket--usw2-az1--x-s3 \ --key new-file.txt \ --rename-source amzn-s3-demo-bucket--usw2-az1--x-s3/original-file.txt \ --destination-if-none-match "\"e5f3g7h8i9j0\""

Der Befehl hat folgende Auswirkungen:

  • Benennt ein Objekt im amzn-s3-demo-bucket--usw2-az1--x-s3 Verzeichnis-Bucket von original-file.txt in new-file.txt um.

  • Führt den Umbenennungsvorgang nur aus, wenn das Objekt existiert und das ETag des Objekts nicht mit „e5f3g7h8i9j0“ übereinstimmt.

Wenn bereits ein Objekt mit dem neu angegebenen Namen und dem passenden ETag existiert, schlägt der Vorgang mit einem 412 Precondition Failed-Fehler fehl.

SDK for Java

Sie können Ihre AWS SDK für Java-Objekte mithilfe des umbenennen. Um diese Beispiele zu verwenden, ersetzen Sie die Benutzereingabe-Platzhalter durch Ihre eigenen Informationen

Das folgende Beispiel veranschaulicht, wie Sie mit dem AWS SDK für Java ein RenameObjectRequest erstellen.

String key = "key"; String newKey = "new-key"; String expectedETag = "e5f3g7h8i9j0"; RenameObjectRequest renameRequest = RenameObjectRequest.builder() .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3) .key(newKey) .renameSource(key) .destinationIfMatch(e5f3g7h8i9j0) .build();

Dieser Code führt Folgendes aus:

  • Erstellen Sie eine Anfrage, um ein Objekt im amzn-s3-demo-bucket--usw2-az1--x-s3-Verzeichnis-Bucket von „key“ in „new-key“ umzubenennen.

  • Beinhaltet die Bedingung, dass die Umbenennung nur erfolgt, wenn das ETag des Objekts mit „e5f3g7h8i9j0“ übereinstimmt.

  • Wenn der ETag nicht übereinstimmt oder das Objekt nicht existiert, schlägt der Vorgang fehl.

Das folgende Beispiel zeigt, wie Sie RenameObjectRequest mit dem AWS SDK für Java eine Bedingung mit einer Nichtübereinstimmung erstellen.

String key = "key"; String newKey = "new-key"; String noneMatchETag = "e5f3g7h8i9j0"; RenameObjectRequest renameRequest = RenameObjectRequest.builder() .bucket(amzn-s3-demo-bucket--usw2-az1--x-s3) .key(newKey) .renameSource(key) .destinationIfNoneMatch(noneMatchETag) .build();

Dieser Code führt Folgendes aus:

  • Erzeugt eine Anforderung zum Umbenennen eines Objekts von „key“ in „new-key“ im amzn-s3-demo-bucket--usw2-az1--x-s3-Verzeichnis-Bucket.

  • Schließt eine .destinationIfNoneMatch(noneMatchETag)-Bedingung ein, die sicherstellt, dass die Umbenennung nur erfolgt, wenn das ETag des Zielobjekts nicht mit „e5f3g7h8i9j0“ übereinstimmt.

Der Vorgang schlägt mit einem 412 Precondition Failed Fehler fehl, wenn ein Objekt mit dem neu angegebenen Namen existiert und den angegebenen ETag hat.

SDK for Python

Sie können das SDK für Python verwenden, um Ihre Objekte umzubenennen. Wenn Sie dieses Beispiel verwenden möchten, ersetzen Sie die Platzhalter für Benutzereingaben durch Ihre Informationen.

Das folgende Beispiel zeigt, wie man ein Objekt mit dem AWS SDK für Python (Boto3) umbenennt.

def basic_rename(bucket, source_key, destination_key): try: s3.rename_object( Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3, Key=destination_key, RenameSource=f"{source_key}" ) print(f"Successfully renamed {source_key} to {destination_key}") except ClientError as e: print(f"Error renaming object: {e}")

Dieser Code führt Folgendes aus:

  • Benennt ein Objekt im amzn-s3-demo-bucket--usw2-az1--x-s3-Verzeichnis-Bucket von source_key in destination_key um.

  • Gibt eine Erfolgsmeldung aus, wenn die Umbenennung Ihres Objekts erfolgreich war, oder eine Fehlermeldung, wenn sie fehlgeschlagen ist.

Das folgende Beispiel zeigt, wie ein Objekt mit den SourceIfMatch- und DestinationIfNoneMatch-Bedingungen mithilfe des AWS SDK für Python (Boto3) umbenannt wird.

def rename_with_conditions(bucket, source_key, destination_key, source_etag, dest_etag): try: s3.rename_object( Bucket=amzn-s3-demo-bucket--usw2-az1--x-s3, Key=destination_key, RenameSource=f"{amzn-s3-demo-bucket--usw2-az1--x-s3}/{source_key}", SourceIfMatch=source_ETag, DestinationIfNoneMatch=dest_ETag ) print(f"Successfully renamed {source_key} to {destination_key} with conditions") except ClientError as e: print(f"Error renaming object: {e}")

Dieser Code führt Folgendes aus:

  • Führt eine bedingte Umbenennung durch und wendet zwei Bedingungen an, SourceIfMatch und DestinationIfNoneMatch. Die Kombination dieser Bedingungen stellt sicher, dass das Objekt nicht geändert wurde und dass nicht bereits ein Objekt mit dem neu angegebenen Namen existiert.

  • Benennt ein Objekt im amzn-s3-demo-bucket--usw2-az1--x-s3-Verzeichnis-Bucket von source_key in destination_key um.

  • Gibt eine Erfolgsmeldung aus, wenn die Umbenennung Ihres Objekts erfolgreich war, oder eine Fehlermeldung, wenn sie fehlschlägt oder die Bedingungen nicht erfüllt sind.

SDK for Rust

Sie können das SDK für Rust verwenden, um Ihre Objekte umzubenennen. Wenn Sie dieses Beispiel verwenden möchten, ersetzen Sie die Platzhalter für Benutzereingaben durch Ihre Informationen.

Das folgende Beispiel zeigt, wie ein Objekt im Bucket des Verzeichnisses amzn-s3-demo-bucket--usw2-az1--x-s3 unter Verwendung des SDK für Rust umbenannt werden kann.

async fn basic_rename_example(client: &Client) -> Result<(), Box<dyn Error>> { let response = client .rename_object() .bucket(" amzn-s3-demo-bucket--usw2-az1--x-s3") .key("new-name.txt") // New name/path for the object .rename_source("old-name.txt") // Original object name/path .send() .await?; Ok(()) }

Dieser Code führt Folgendes aus:

  • Erzeugt eine Anfrage zum Umbenennen eines Objekts von „old-name.tx“ in „new-name.txt“ im amzn-s3-demo-bucket--usw2-az1--x-s3-Verzeichnis-Bucket.

  • Gibt einen Result Typ zurück, um mögliche Fehler zu behandeln.

Sie können REST-Anfragen zur Umbenennung eines Objekts senden. Weitere Informationen finden Sie unter RenameObject in der Amazon-S3-API-Referenz.

Ab der Version 1.19.0 oder höher unterstützt Mountpoint für Amazon S3 das Umbenennen von Objekten in S3 Express One Zone. Weitere Informationen zu Mountpoint finden Sie unter Arbeiten mit Mountpoint.