Informationen zu Cloud Storage-Objekten

Auf dieser Seite werden Objekte, eine Ressource in Cloud Storage, beschrieben. Eine allgemeine Übersicht über die Funktionsweise von Cloud Storage finden Sie in der Cloud Storage-Produktübersicht.

Objekte

Objekte sind die einzelnen Daten, die Sie in Cloud Storage speichern. Die Anzahl der Objekte, die Sie in einem Bucket erstellen können, ist nicht begrenzt.

Objekte haben zwei Komponenten: Objektdaten und Objektmetadaten. Objektdaten sind normalerweise eine Datei, die Sie in Cloud Storage speichern möchten und vollständig in Cloud Storage undurchsichtig sind. Objektmetadaten bezeichnen eine Sammlung von Name/Wert-Paaren, die verschiedene Objektqualitäten beschreiben.

Zwei wichtige Objekte für alle Objektmetadaten sind der Name und die Generierungsnummer des Objekts. Wenn Sie einem Cloud Storage-Bucket ein Objekt hinzufügen, geben Sie den Objektnamen an und Cloud Storage weist die Generierungsnummer zu. Der Name und die Generierung identifizieren das Objekt innerhalb dieses Buckets zusammen.

Sie können Zugriffssteuerungslisten (ACLs) verwenden, um den Zugriff auf einzelne Objekte zu steuern. Sie können auch das Identity and Access Management (IAM) verwenden, um den Zugriff auf alle Objekte in einem Bucket oder in einem verwalteten Ordner zu steuern.

Überlegungen zur Benennung

Bei der Benennung von Objekten in Cloud Storage müssen bestimmte Anforderungen eingehalten werden, um für Kompatibilität zu sorgen und Fehler zu vermeiden. Diese Anforderungen gelten sowohl für Buckets mit flachem Namespace als auch für Buckets mit aktiviertem hierarchischen Namespace.

Allgemeine Voraussetzungen

  • Objektnamen können eine beliebige Folge gültiger Unicode-Zeichen enthalten.
  • Objektnamen dürfen keine Zeilenumbruch- oder Zeilenvorschubzeichen enthalten.
  • Objektnamen dürfen nicht mit .well-known/acme-challenge/ beginnen.
  • Objekte können nicht . oder .. genannt werden.

Namespace-spezifische Objektgrößenbeschränkungen

Die maximale Größe eines Objektnamens variiert je nach Namespace des Buckets:

  • Größe des Objektnamens in einem Bucket mit flachem Namespace: 1–1.024 Byte bei UTF-8-Codierung.

  • Größe von Objektnamen in Buckets, für die der hierarchische Namespace aktiviert ist: Objektnamen können in zwei Teile unterteilt werden:

    • Ordnername: Der Name des Ordners, in dem sich das Objekt befindet. Die maximale Größe des Ordnernamens beträgt 512 Byte, wenn er in UTF-8 codiert ist.
    • Basisname: Der Name des Objekts, das sich im Ordner befindet. Die maximale Größe des Basisnamens beträgt 512 Byte bei UTF-8-Codierung.

    Der Pfad my-folder/my-object.txt steht beispielsweise für ein Objekt mit dem Basisnamen my-object.txt, das in einem Ordner namens my-folder/ gespeichert ist.

Empfehlungen

Es wird dringend empfohlen, folgende Zeichen in Objektnamen zu vermeiden:

  • Steuerzeichen, die in XML 1.0 nicht zulässig sind (#x7F–#x84 und #x86–#x9F): Diese Zeichen verursachen XML-Listenprobleme, wenn Sie versuchen, Objekte aufzulisten.
  • Das Zeichen #: Google Cloud CLI-Befehle interpretieren Objektnamen, die auf #<numeric string> enden, als Versionsbezeichner. Wenn Objektnamen ein # enthalten, kann es daher schwierig bis unmöglich sein, für diese versionierten Objekte Vorgänge mit der gcloud CLI auszuführen.
  • Die Zeichen [, ], * oder ?: Google Cloud CLI-Befehle interpretieren diese Zeichen als Platzhalter. Wenn sie in Objektnamen enthalten sind, kann es daher schwierig oder unmöglich sein, Platzhaltervorgänge durchzuführen. Darüber hinaus sind * und ? keine gültigen Zeichen für Dateinamen in Windows.
  • Die Zeichen :, ", <, > oder |: Dies sind keine gültigen Zeichen für Dateinamen in Windows. Daher wird versucht, ein Objekt herunterzuladen, das verwendet wird. Solche Zeichen im Namen einer Windows-Datei schlagen fehl, es sei denn, die Downloadmethode umfasst das Umbenennen der resultierenden Windows-Datei. Obwohl es in Windows kein gültiges Zeichen für Dateinamen ist, kann das Zeichen / normalerweise mit Objektnamen verwendet werden, um eine Verzeichnisstruktur nachzuahmen. Tools wie die Google Cloud CLI konvertieren das Zeichen beim Download in eine Windows-Umgebung automatisch in \.
  • Vertrauliche oder personenidentifizierbare Informationen (PII): Objektnamen sind allgemeiner sichtbar als Objektdaten. Objektnamen werden beispielsweise in URLs für das Objekt und beim Auflisten von Objekten in einem Bucket angezeigt.

Vorhandene Objekte können nicht direkt umbenannt werden. Sie können jedoch indirekt ein Objekt umbenennen. Kopieren und löschen Sie dazu das ursprüngliche Objekt.

Objekt-Namespace

Sie können Objekte in den folgenden Namespaces speichern:

Flacher Namespace

In Buckets mit einem flachen Namespace werden Objekte in einer flachen Struktur ohne Hierarchie gespeichert, d. h., es gibt keine Verzeichnisse oder Ordner.

Der Einfachheit halber werden Objekte auf verschiedene Weise so behandelt, als ob sie in einer Ordnerhierarchie gespeichert wären:

Wenn Sie beispielsweise ein Objekt mit dem Namen folder1/file.txt im Bucket your-bucket erstellen, lautet der Pfad zum Objekt your-bucket/folder1/file.txt und in Cloud Storage ist kein Ordner namens folder1 gespeichert. Aus Sicht von Cloud Storage ist der String folder1/ Teil des Objektnamens.

Da das Objekt jedoch einen / im Namen hat, implementieren einige Tools das Vorkommen von Ordnern. Bei Verwendung der Google Cloud Console würden Sie beispielsweise das Objekt folder1/file1.txt aufrufen, als sei es ein Objekt namens file1.txt in einem Ordner mit namens folder1. Ebenso können Sie einen verwalteten Ordner mit dem Namen folder1 erstellen und file1.txt unterliegt dann der Zugriffsrichtlinie, die von diesem verwalteten Ordner festgelegt wird.

Da sich Objekte in einem flachen Namespace befinden, haben tief verschachtelte, verzeichnisartige Strukturen nicht die Leistung eines nativen Dateisystems mit komplex verschachtelten Unterverzeichnissen.

Unter Best Practices für Anfrageraten finden Sie Empfehlungen zur Optimierung der Leistung, da sequenzielle Namen bei umfangreichen Uploads vermieden werden. Objekte, die mit sequenziellen Namen hochgeladen werden, erreichen wahrscheinlich denselben Backend-Server und beeinträchtigen die Leistung.

Simulierte Ordner

Damit Sie Objekte in Ihren Cloud Storage-Buckets organisieren können, simulieren einige Tools Ordner. Außerdem haben die JSON- und XML APIs Funktionen, mit denen Sie ein eigenes Benennungsschema zum Simulieren von Ordnern entwerfen können. Klicken Sie auf die folgenden Tabs, um zu sehen, wie verschiedene Tools simulierte Ordner handhaben.

Console

Die Google Cloud Console erstellt eine visuelle Darstellung von Ordnern, die einem lokalen Dateibrowser ähneln.

In der Google Cloud Console können Sie einen leeren Ordner in einem Bucket erstellen oder einen vorhandenen Ordner hochladen.

Wenn Sie einen vorhandenen Ordner hochladen, wird der Name des Ordners Teil des Pfads für alle im Ordner enthaltenen Objekte. Alle Unterordner und die darin enthaltenen Objekte werden ebenfalls in den Upload einbezogen.

So erstellen Sie einen Ordner:

  1. Wechseln Sie in der Cloud Console zur Seite Cloud Storage-Buckets.

    Buckets aufrufen

  2. Rufen Sie den Bucket auf.

  3. Klicken Sie auf Ordner erstellen, um einen leeren neuen Ordner zu erstellen, oder auf Ordner hochladen, um einen vorhandenen Ordner hochzuladen.

Befehlszeile

Cloud Storage-Befehlszeilen simulieren das typische Befehlszeilenverzeichnis unter Verwendung verschiedener Regeln.

Um die Illusion eines hierarchischen Dateibaums zu erreichen, wendet die gcloud CLI die folgenden Regeln an, um zu bestimmen, ob die Ziel-URL in einem Befehl als Objektname oder Ordner behandelt werden soll:

  1. Wenn die Ziel-URL mit einem /-Zeichen endet, behandeln gcloud CLI-Befehle die Ziel-URL als Ordner. Betrachten Sie beispielsweise den folgenden Befehl, wobei your-file der Name einer Datei ist:

    gcloud storage cp your-file gs://your-bucket/abc/

    Als Ergebnis dieses Befehls erstellt Cloud Storage ein Objekt namens abc/your-file im Bucket your-bucket.

  2. Wenn Sie mehrere Quelldateien in eine Ziel-URL kopieren, entweder mit dem Flag --recursive oder einem Wildcard wie **, behandelt die gcloud CLI die Ziel-URL als Ordner. Betrachten Sie beispielsweise den folgenden Befehl, wobei top-dir ein Ordner mit Dateien wie file1 und file2 ist:

    gcloud storage cp top-dir gs://your-bucket/abc --recursive

    Aufgrund dieses Befehls erstellt Cloud Storage die Objekte abc/top-dir/file1 und abc/top-dir/file2 im Bucket your-bucket.

  3. Wenn keine dieser Regeln zutrifft, prüft die gcloud CLI die Objekte im Bucket, um festzustellen, ob die Ziel-URL ein Objektname oder ein Ordner ist. Betrachten Sie beispielsweise den folgenden Befehl, wobei your-file der Name einer Datei ist:

    gcloud storage cp your-file gs://your-bucket/abc

    Die Befehlszeile stellt eine Anfrage zur Auflistung von Objekten für your-bucket unter Verwendung des Trennzeichens /und des Präfixes=abc, um festzustellen, ob es in your-bucket Objekte gibt, deren Pfad mit abc/ beginnt. Ist dies der Fall, behandelt die gcloud CLI abc/ als Ordnernamen und der Befehl erstellt das Objekt abc/your-file im Bucket your-bucket. Andernfalls erstellt die gcloud CLI das Objekt abc in your-bucket.

Dieser regelbasierte Ansatz unterscheidet sich von der Funktionsweise vieler Tools, die 0-Byte-Objekte erstellen, um das Vorhandensein von Ordnern zu markieren. Die gcloud CLI versteht mehrere Konventionen, die von solchen Tools verwendet werden, z. B. die Konvention, dass _$folder$ am Ende des Namens des 0-Byte-Objekts hinzugefügt wird. Solche Markierungsobjekte müssen aber kein mit UNIX-Befehlen konsistentes Benennungsverhalten implementieren.

Zusätzlich zu diesen Regeln hängt die Behandlung von Quelldateien durch die gcloud CLI davon ab, ob Sie das Flag --recursive verwenden. Wenn Sie das Flag verwenden, erstellt die gcloud CLI Objektnamen, die die Struktur des Quellverzeichnisses ab dem Punkt der rekursiven Verarbeitung widerspiegeln. Betrachten Sie beispielsweise den folgenden Befehl, wobei home/top-dir ein Ordner mit Dateien wie file1 und sub-dir/file2 ist:

gcloud storage cp home/top-dir gs://your-bucket --recursive

Aufgrund dieses Befehls erstellt Cloud Storage die Objekte top-dir/file1 und top-dir/sub-dir/file2 im Bucket your-bucket.

Beim Kopieren ohne das Flag --recursive werden Objekte mit dem Namen der letzten Pfadkomponente der Quelldateien erstellt, auch wenn aufgrund eines Platzhalters wie ** mehrere Dateien kopiert werden. Angenommen, home/top-dir ist ein Ordner mit Dateien wie file1 und sub-dir/file2, dann lautet der Befehl:

gcloud storage cp home/top-dir/** gs://your-bucket

Erstellt ein Objekt mit dem Namen file1 und ein Objekt mit dem Namen file2 im Bucket your-bucket.

Wiederholungsversuche und Benennung

Wenn die gcloud CLI eine unterbrochene Anfrage wiederholt, tritt möglicherweise ein Problem auf, bei dem beim ersten Versuch eine Teilmenge von Dateien kopiert wird und bei den nachfolgenden Versuchen ein bereits vorhandener Zielordner gefunden wird, was dazu führt, dass Ihre Objekte falsch benannt werden.

Betrachten Sie zum Beispiel den folgenden Befehl, bei dem sich unter your-dir/ Unterordner befinden, z. B. dir1 und dir2, und beide Unterordner enthalten die Datei abc:

gcloud storage cp ./your-dir gs://your-bucket/new --recursive

Wenn der Pfad gs://your-bucket/new noch nicht vorhanden ist, erstellt die gcloud CLI die folgenden Objekte beim ersten erfolgreichen Versuch:

new/dir1/abc
new/dir2/abc

Beim nächsten erfolgreichen Versuch desselben Befehls erstellt die gcloud CLI jedoch die folgenden Objekte:

new/your-dir/dir1/abc
new/your-dir/dir2/abc

Damit die gcloud CLI bei jedem Versuch konsistent funktioniert, versuchen Sie Folgendes:

  1. Fügen Sie einen Schrägstrich am Ende der Ziel-URL hinzu, damit die gcloud CLI sie immer als Ordner behandelt.

  2. Verwenden Sie gcloud storage rsync. Da rsync nicht die von Unix cp definierten Ordnerbenennungsregeln verwendet, ist die Funktionsweise konsistent, unabhängig davon, ob der Zielunterordner vorhanden ist oder nicht.

Zusätzliche Hinweise

  • Sie können kein Null-Byte-Objekt erstellen, um einen leeren Ordner mit der gcloud CLI nachzuahmen.

  • Beim Herunterladen in ein lokales Dateisystem überspringt die gcloud CLI Objekte, deren Name auf das Zeichen / endet. Das Erstellen einer Datei, die auf / endet, ist unter Linux und macOS nicht zulässig.

  • Wenn Sie Scripts verwenden, um Dateipfade durch Kombination von Unterpfaden zu erstellen, beachten Sie, dass / nur ein Zeichen ist, das zufällig im Namen des Objekts vorkommt, und die Befehlszeilen gs://your-bucket/folder/ als ein anderes Objekt interpretieren als gs://your-bucket//folder.

REST APIs

JSON API

Ordner sind in der JSON API nicht vorhanden. Sie können die Liste der Objekte eingrenzen und Ordner mit den Abfrageparametern prefix und delimiter simulieren.

Wenn Sie beispielsweise alle Objekte im Bucket my-bucket mit dem Präfix folder/subfolder/ auflisten möchten, stellen Sie eine Anfrage zur Objektauflistung unter Verwendung der folgenden URL:

"https://storage.googleapis.com/storage/v1/b/my-bucket/o?prefix=folder/subfolder/"

XML API

Ordner sind in der XML API nicht vorhanden. Sie können die Liste der Objekte eingrenzen und Ordner mit den prefix und delimiter Abfrageparameter.

Wenn Sie beispielsweise alle Objekte im Bucket my-bucket mit dem Präfix folder/subfolder/ auflisten möchten, stellen Sie eine Anfrage zur Objektauflistung unter Verwendung der folgenden URL:

"https://storage.googleapis.com/my-bucket?prefix=folder/subfolder/"

Simulierte Ordner entfernen

Da simulierte Ordner nicht wirklich existieren, können Sie sie in der Regel entfernen, indem Sie Objekte umbenennen, sodass der simulierte Ordner nicht mehr Teil des Objektnamens ist. Wenn Sie beispielsweise ein Objekt namens folder1/file haben, können Sie den simulierten Ordner folder1/ entfernen, indem Sie das Objekt in file umbenennen.

Wenn Sie jedoch ein Tool verwendet haben, das Null-Byte-Objekte als Ordner-Platzhalter erstellt, z. B. die Google Cloud Console, müssen Sie das Null-Byte-Objekt löschen, um den Ordner zu entfernen.

Hierarchischer Namespace

Mit einem hierarchischen Namespace können Sie Objekte in einem Cloud Storage-Bucket in einem Dateisystem wie einer Ordnerhierarchie organisieren. Hierarchische Namespaces verbessern die Leistung und helfen Ihnen, Ihre Daten effizient zu verwalten. Weitere Informationen zu hierarchischen Namespaces und ihrer Verwendung finden Sie unter Hierarchischer Namespace.

Unveränderlichkeit von Objekten

Objekte sind unveränderlich, d. h. ein hochgeladenes Objekt kann sich während seiner gesamten Speicherdauer nicht verändern. Die Speicherdauer eines Objekts ist die Zeit zwischen erfolgreicher Objekterstellung, wie z. B. Hochladen und erfolgreiche Objektlöschung. Das bedeutet in der Praxis, dass Sie keine inkrementellen Änderungen an Objekten vornehmen können, z. B. Anfüge- oder Kürzungsvorgänge. Es ist jedoch möglich, Objekte zu ersetzen, die in Cloud Storage gespeichert sind. Dies geschieht atomar: Bis zum Abschluss des neuen Uploads wird Lesern die alte Version des Objekts und nach Abschluss des Uploads die neue Version bereitgestellt. Ein einzelner Ersetzungsvorgang markiert also das Ende der Lebensdauer eines unveränderlichen Objekts und den Beginn der Lebensdauer eines neuen unveränderlichen Objekts.

Die Generierungsnummer für ein Objekt ändert sich jedes Mal, wenn Sie die Daten des Objekts ersetzen. Somit identifiziert die Generierungsnummer ein unveränderliches Objekt eindeutig.

Beachten Sie, dass beim schnellen Ersetzen desselben Objekts ein Limit von einem Mal pro Sekunde gilt. Wenn dasselbe Objekt öfter ersetzt wird, kann dies zu 429 Too Many Requests-Fehlern führen. Sie sollten Ihre Anwendung so konfigurieren, dass Daten für ein bestimmtes Objekt nicht öfter als einmal pro Sekunde hochgeladen werden und gelegentliche 429 Too Many Requests-Fehler mit einer exponentiellen Backoff-Wiederholungsstrategie bewältigt werden.

Nächste Schritte