Ordner in Buckets mit aktiviertem hierarchischen Namespace

Auf dieser Seite finden Sie Informationen zu Ordnern in Buckets mit aktiviertem hierarchischen Namespace.

Übersicht

Wenn Sie einen Bucket mit aktiviertem hierarchischen Namespace erstellen, verwendet der Bucket eine echte Dateisystemstruktur im Gegensatz zu einem standardmäßigen flachen Namespace. Ordner sind in Buckets mit aktiviertem hierarchischen Namespace als Ressource vorhanden. Mit Ordnern können Sie Ihre Objekte effektiver organisieren und auf echte Verzeichnisfunktionen zugreifen, z. B. atomare Ordnerumbenennungen und effiziente Metadatenvorgänge.

Ordner in Buckets mit aktiviertem hierarchischen Namespace unterscheiden sich von simulierten Ordnern und verwalteten Ordnern. Simulierte Ordner sind in Buckets mit flachem Namespace vorhanden und verwaltete Ordner können sowohl in Buckets mit flachem Namespace als auch in Buckets mit aktiviertem hierarchischen Namespace verwendet werden. Verwaltete Ordner werden hauptsächlich verwendet, um IAM-Berechtigungen für Gruppen von Objekten zu erteilen. Weitere Informationen zu diesen anderen Ordnerarten finden Sie unter Ordnerarten.

Sie können Ordner verwalten, indem Sie Ordneraktionen ausführen. Informationen zum Erstellen, Auflisten und Löschen von Ordnern sowie zum Abrufen von Ordner Metadaten finden Sie unter Ordner erstellen und verwalten. Informationen zum Umbenennen oder Verschieben eines Ordners finden Sie unter Ordner umbenennen.

Ordner-Metadaten

Die Metadaten eines Ordners enthalten strukturierte Informationen zum Ordner. Detaillierte Informationen zu Ordner-Metadaten finden Sie in der Referenzdokumentation zur Cloud Storage JSON API unter der Ressource Folder.

Die wichtigsten Komponenten der Metadaten eines Ordners sind:

  • bucket: Der Name des Buckets, in dem sich der Ordner befindet. Beispiel: my-bucket.
  • id: Eine eindeutige ID für den Ordner im Bucket. Beispiel: hns-bucket/dir1/.
  • kind ist der Ressourcentyp. Für einen Ordner ist dieser Wert immer storage#folder.
  • name: Der Name des Ordners. Beispiel: dir1/.
  • selfLink: Eine URL, die auf den Ordner in der Cloud Storage API verweist.
  • timeCreated: Der Zeitstempel, der angibt, wann der Ordner erstellt wurde. Beispiel: 2023-05-05T16:32:08.878000+00:00.
  • updated: Der Zeitstempel, der angibt, wann die Ordner zuletzt aktualisiert wurde. Beispiel: 2024-05-06T16:32:08.878000+00:00.

Ordneraktionen

In diesem Abschnitt werden die Vorgänge beschrieben, die Sie für Ordner ausführen können. Einige Vorgänge initiieren einen Vorgang mit langer Ausführungszeit, den Sie beobachten können, um den Fortschritt und Status des Vorgangs zu verfolgen.

Ordner erstellen

Sie können Ordner explizit mit dem Vorgang zum Erstellen von Ordnern erstellen. Wenn Sie außerdem ein Objekt erstellen und einen nicht vorhandenen Ordner im Pfad angeben, wird der fehlende übergeordnete Ordner automatisch für Sie erstellt. Wenn Sie beispielsweise ein Objekt mit dem Namen dir1/foo.txt erstellen, wird automatisch der Ordner dir1/ erstellt, falls er noch nicht vorhanden ist.

Informationen zur Ordnerbenennung finden Sie unter Hinweise.

Ordner auflisten

Mit dem Vorgang zum Auflisten von Ordnern können Sie eine Liste der Ordner in Ihrem Bucket abrufen. Da Ordner in Buckets mit aktiviertem hierarchischen Namespace separate Ressourcen sind, wird bei diesem Vorgang die tatsächliche Ordnerstruktur ausgewertet, anstatt Ordner aus Objektpfaden zu simulieren.

Beim Auflisten von Ordnern können Sie die Ergebnisse mit Parametern wie prefix, delimiter, lexicographicStart und lexicographicEnd filtern. Wenn Sie beispielsweise den Parameter „delimiter“ auf / setzen, können Sie Ordner im Verzeichnismodus auflisten und nur die Ordner zurückgeben, die mit dem Präfix übereinstimmen oder sich eine Ebene darunter befinden.

Der Vorgang zum Auflisten von Ordnern gibt Ergebnisse mit Seiten zurück. Eine einzelne Antwortseite kann maximal 1.000 Ordner enthalten.

Metadaten eines Ordners abrufen

Mit dem Vorgang zum Abrufen von Ordner-Metadaten können Sie die Eigenschaften eines Ordners abrufen. Bei diesem Vorgang werden Informationen zur Ordnerressource selbst und nicht zu den darin enthaltenen Objekten abgerufen.

Dieser Vorgang gibt die Metadaten eines Ordners zurück, die strukturierte Informationen wie den Zeitstempel der Erstellung, die eindeutige ID und den Bucket enthalten, in dem sich der Ordner befindet. Eine detaillierte Liste der von diesem Vorgang zurückgegebenen Eigenschaften finden Sie unter Ordner-Metadaten.

Ordner umbenennen oder verschieben

Beim Umbenennen und Verschieben eines Ordners wird derselbe zugrunde liegende Vorgang verwendet. Der Vorgang ist eine atomare Änderung, die nur Metadaten betrifft. Dabei wird der Pfad des Ordners aktualisiert, ohne die zugrunde liegenden Objekte physisch zu kopieren oder zu löschen. Beim Umbenennen eines Ordners wird auch der Pfad des Ordners für Ressourcen im Ordner aktualisiert, z. B. für untergeordnete Ordner, Objekte und verwaltete Ordner. Dadurch ist der Vorgang schnell und es fallen keine Kosten für das Kopieren von Objekten an.

Durch das Umbenennen des Ordners wird ein Vorgang mit langer Ausführungszeit initiiert.

Während des Umbenennens eines Ordners können Sie die umzubenennenden Ordner lesen und auflisten, aber keine Schreibvorgänge für sie ausführen.

In der JSON API und der Google Cloud CLI verwenden die Vorgänge zum Umbenennen und Verschieben denselben URL-Endpunkt oder Befehl. In der Google Cloud console werden Ordner umbenennen und Ordner verschieben als zwei separate Optionen angezeigt, aber beide Optionen führen denselben Back-End-Vorgang aus.

Ordner löschen

Mit dem Vorgang zum Löschen von Ordnern können Sie einen Ordner dauerhaft löschen. Ordner können zwar automatisch bei Objektvorgängen erstellt werden, sie werden aber nicht automatisch entfernt, wenn sie leer werden. Sie müssen sie explizit löschen.

Interaktionen zwischen Ordnern und zugehörigen verwalteten Ordnern

Zugehörige verwaltete Ordner werden verwendet, um den Zugriff auf Ordner in Buckets mit aktiviertem hierarchischem Namespace zu steuern. Ordner und zugehörige verwaltete Ordner interagieren auf folgende Weise:

  • Ordner erstellen: Wenn Sie einen verwalteten Ordner in einem Bucket mit aktiviertem hierarchischen Namespace erstellen, werden alle fehlenden Ordner im Pfad automatisch erstellt, einschließlich übergeordneter Ordner und des eigentlichen Zielordners (auch als zugehöriger Ordner bezeichnet).

    Angenommen, Sie erstellen einen Bucket mit aktiviertem hierarchischen Namespace namens my-bucket. Wenn Sie im Bucket einen verwalteten Ordner namens 2025/training-data/ erstellen, erstellt Cloud Storage automatisch den übergeordneten Ordner 2025/ und den zugehörigen Zielordner training-data/ im Bucket.

  • Ordner löschen: Wenn Sie einen Ordner löschen, der einen zugehörigen verwalteten Ordner hat, löscht Cloud Storage auch den zugehörigen verwalteten Ordner. Das liegt daran, dass beim Löschen eines Ordners der gesamte Pfad gelöscht wird. Da der Pfad nicht mehr vorhanden ist, werden der zugehörige verwaltete Ordner und alle daran angehängten IAM-Richtlinien gelöscht. In Buckets mit aktiviertem hierarchischen Namespace kann ein verwalteter Ordner nicht ohne einen zugehörigen Ordner vorhanden sein.

    Wenn Sie nicht die erforderlichen Berechtigungen zum Löschen des zugehörigen verwalteten Ordners des Ordners haben, schlägt der Vorgang zum Löschen des Ordners fehl. Informationen zu den erforderlichen Berechtigungen zum Löschen verwalteter Ordner finden Sie unter Erforderliche Rollen für verwaltete Ordner abrufen.

  • Ordner umbenennen: Wenn Sie einen Ordner umbenennen, der einen zugehörigen verwalteten Ordner hat, benennt Cloud Storage auch den zugehörigen verwalteten Ordner um.

Informationen zu den Benennungsanforderungen für Ordner mit einem zugehörigen verwalteten Ordner finden Sie unter Benennung für Ordner.

Hinweise

Beachten Sie beim Erstellen von Ordnern Folgendes:

  • Objekt- und Ordnernamen: Buckets mit aktiviertem hierarchischen Namespace unterstützen alle gültigen Objektnamen, einschließlich der mit voran- oder nachgestellten Schrägstrichen (/) oder aufeinanderfolgenden Schrägstrichen. Jeder Schrägstrich (/) in einem Objektnamen stellt einen Ordner dar. Die folgende Tabelle enthält Beispiele für die Beziehung zwischen Objektnamen und deren zugehöriger Position in der Ordnerhierarchie:

    Objektname Position in der Ordnerhierarchie
    foo.txt Jeder Bucket enthält einen Stammordner. Das Objekt foo.txt befindet sich unter dem Stammordner des Buckets.
    dir1/foo.txt Das Objekt foo.txt befindet sich in einem Ordner der obersten Ebene namens dir1/. Der Ordner der obersten Ebene unterscheidet sich vom Stammordner.
    dir1/ Der nachgestellte Schrägstrich in Objektnamen wie dir1/ gibt an, dass sich das Objekt im Ordner befindet. In diesem Beispiel ist der Objektname dir1/ mit dem Namen des übergeordneten Ordners dir1/ identisch.
    dir1//foo.txt Das Objekt foo.txt befindet sich in einem Ordner der zweiten Ebene namens dir1//, einem untergeordneten Ordner von dir1/.

  • Maximale Ordnerstruktur: Buckets mit aktiviertem hierarchischem Namespace unterstützen eine maximale Ordnerstruktur von 50 Ebenen. Ordner können mit bis zu 50 gestapelten untergeordneten Ordnern erstellt werden (z. B. folder1/folder2/folder3/.../folder50/my-data.txt). Wenn ein Ordner jedoch einen zugehörigen verwalteten Ordner hat, kann er nur bis zu 15 gestapelte untergeordnete Ordner haben.

  • Maximale Größe des Ordnernamens: 512 Byte (UTF-8-kodiert).

  • Vertrauliche oder personenidentifizierbare Informationen (PII): Ordnernamen sind allgemeiner sichtbar als Ordner-Metadaten. Ordnernamen werden beispielsweise in URLs und beim Auflisten von Ordnern oder Objekten in einem Bucket angezeigt. Ordnernamen dürfen keine vertraulichen Informationen oder PII enthalten.

Nächste Schritte