Funktionen in der App Engine-Clientbibliothek für Cloud Storage

Die App Engine-Clientbibliothek für Cloud Storage bietet folgende Funktionen:

Funktionen

  • cloudstorage.copy2() speichert die angegebene Datei mit dem neuen, angegebenen Dateinamen im selben Cloud Storage-Bucket.
  • cloudstorage.delete() löscht das angegebene Objekt aus dem Cloud Storage-Bucket.
  • cloudstorage.listbucket() listet die Objekte im Cloud Storage-Bucket auf.
  • cloudstorage.open() öffnet ein vorhandenes Objekt im Cloud Storage-Bucket zum Lesen oder Überschreiben oder erstellt abhängig vom angegebenen Modus ein neues Objekt.
  • cloudstorage.stat() liefert Metadaten zur Datei, z. B. Inhaltstyp, Größe, Zeitstempel, MD5-Digest und Cloud Storage-Header.

Sobald cloudstorage.open() zur Ausgabe des dateiähnlichen Objekts – des angegebenen Cloud Storage-Objekts – aufgerufen wird, können Sie die Standardfunktionen der Python-Datei wie write() und close() nutzen und ein Objekt in den Cloud Storage-Bucket schreiben. Mit read()können Sie ein Objekt aus dem Cloud Storage-Bucket lesen.

Kurse

Funktionen

cloudstorage.copy2 (src, dst, metadata=None, retry_params=None)

Kopiert die angegebene Datei in den neuen angegebenen Dateinamen und standardmäßig auch die Metadaten. Optional können Sie die Metadaten in der Kopie überschreiben, indem Sie den optionalen metadata-Parameter angeben.

Löst cloudstorage.NotFoundError aus, wenn das angegebene Cloud Storage-Objekt nicht existiert, oder cloudstorage.AuthorizationError, wenn die Autorisierung fehlgeschlagen ist.

Argumente

src (erforderlich)
Der vollständige Cloud Storage-Dateiname für das Objekt im Format /bucket/object_name. Muss ein vollständiger Dateiname sein und das Trennzeichen `/` enthalten.
dst (erforderlich)
Der vollständige Cloud Storage-Dateiname für die Kopie des Objekts im Format /bucket/object_name. Muss ein vollständiger Dateiname sein und das Trennzeichen `/` enthalten.
metadata= None (optional)
Metadaten-Dictionary für diese Kopie, z. B. {'x-goog-meta-foo': 'bar'}. Wenn Sie den Parameter für die Metadaten angeben, wird keine der ursprünglichen Metadaten in die neue Datei kopiert. Ohne die Angabe von Metadaten (None) werden alle Metadaten der Quelldatei kopiert.
retry_params= None (optional)
Ein RetryParams-Objekt, in dem Sie alle Änderungen angeben, die Sie an der Standardzeitüberschreitung und den Wiederholungseinstellungen dieses Aufrufs vornehmen möchten.

Beispiel

Eine Datei kopieren, aber neue Metadaten hinzufügen und den Fehler ignorieren, wenn die Quelldatei nicht existiert:
import cloudstorage

try:
  cloudstorage.copy2('/my_bucket/README', '/my_bucket/README2', metadata={'x-goog-meta-zzzzz': 'zzzzz'})
except cloudstorage.NotFoundError:
  pass

Nach oben


cloudstorage.delete (filename, retry_params=None)

Löscht die angegebene Datei aus dem Cloud Storage-Bucket.

Löst cloudstorage.NotFoundError aus, wenn das angegebene Cloud Storage-Objekt nicht existiert.

Argumente

filename (erforderlich)
Der vollständige Cloud Storage-Dateiname für das Objekt im Format /bucket/object_name. Muss ein vollständiger Dateiname sein und das Trennzeichen `/` enthalten.
retry_params= None (optional)
Ein RetryParams-Objekt, in dem Sie alle Änderungen angeben, die Sie an der Standardzeitüberschreitung und den Wiederholungseinstellungen dieses Aufrufs vornehmen möchten.

Beispiel

Eine Datei löschen, aber den Fehler ignorieren, wenn die Datei nicht existiert:
import cloudstorage

try:
  cloudstorage.delete(filename)
except cloudstorage.NotFoundError:
  pass

Nach oben


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
Gibt ein Bucket-Iterator-Objekt zurück. Dieser Iterator listet alle Objekte sortiert auf, die mit allen Filtern übereinstimmen. Beachten Sie, dass diese Funktion asynchron abläuft. Sie wird nur blockiert, wenn der Iterator aufgerufen wird, bevor der Iterator Ergebnisse erhält.

Diese Funktion wird in zwei verschiedenen Modi ausgeführt, abhängig davon, ob Sie das Argument delimiter verwenden:

  • Regulärer Modus (Standard): Listet alle Dateien im Bucket ohne Hierarchie auf. (Cloud Storage besitzt keine echten Verzeichnishierarchien.)
  • Verzeichnisemulation: Wenn Sie das Argument delimiter angeben, emuliert es als Pfadtrennzeichen eine Hierarchie aus Verzeichnissen.

Argumente

path_prefix (erforderlich)
Ein Cloud Storage-Pfad des Formats /bucket oder /bucket/prefix, z. B. /bucket/foo/2001. Es werden nur Objekte zurückgegeben, deren vollständiger Pfad mit path_prefix beginnt.
marker= None (optional)
String Ein anderes Präfix für den Pfad. Es werden nur Objekte zurückgegeben, deren vollständiger Pfad lexikographisch ausschließlich nach der Markierung startet. Die als "Markierung" verwendete Datei wird nicht zurückgegeben. Angenommen, Sie möchten, dass alle Dateien beginnend bei superduperfoo3.txt aufgelistet werden. Dazu geben Sie die Datei unmittelbar vor superduperfoo3.txt an, zum Beispiel: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
Eine Möglichkeit, diesen Parameter zu verwenden, besteht darin, ihn mit max_keys zu verwenden, um die Bucket-Dateinamen zu durchsuchen.
max_keys= None (optional)
Ganzzahl Liefert die maximale Anzahl der zurückzugebenden Objekte. Verwenden Sie diese Funktion, wenn Sie wissen, wie viele Objekte Sie möchten. (Andernfalls puffert die Cloud Storage-Clientbibliothek automatisch alle Ergebnisse und fügt Seitenzahlen hinzu.) Kann unter Verwendung von marker verwendet werden, um durch die Dateinamen in einem Bucket zu blättern. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (optional)
String Aktiviert den Verzeichnismodus. Sie können ein oder mehrere Zeichen angeben, die als Verzeichnistrennzeichen verwendet werden sollen.
retry_params= None (optional)
Ein RetryParams-Objekt, in dem Sie alle Änderungen angeben, die Sie an der Standardzeitüberschreitung und den Wiederholungseinstellungen dieses Aufrufs vornehmen möchten.

Ergebniswert

Gibt einen Iterator von GCSFileStat-Objekten für die übereinstimmenden Dateien zurück, nach Dateiname sortiert. Im regulären Modus haben die zurückgegebenen GCSFileStat-Objekte die folgenden Daten:

  • filename
  • etagetag (Die Hex-Darstellung vom MD5-Hash des Dateiinhalts)
  • st_size (Inhaltslänge der Header)
  • st_ctime
  • is_dir

Hinweis: Wenn das Attribut is_dir des Objekts GCSFileStat den Wert True hat, ist das einzige andere Attribut im Objekt filename. Wenn für is_dir der Wert False zutrifft, enthält GCSFileStat auch alle anderen Attribute.

Nach oben


cloudstorage.open(filename, mode='r', content_type=None, options=None, read_buffer_size=storage_api.ReadBuffer.DEFAULT_BUFFER_SIZE, retry_params=None)

Im Lesemodus (r) wird das angegebene Cloud Storage-Objekt zum Lesen geöffnet. Wenn die angegebene Datei im Schreibmodus w existiert, wird sie zum Überschreiben geöffnet (append wird nicht unterstützt). Existiert die Datei nicht, wird sie im angegebenen Bucket erstellt.

Wenn Sie nach dem Schreiben die Datei lesen und/oder in Cloud Storage speichern möchten, schließen Sie die Datei mit der Funktion close. Es ist kein Fehler, wenn Sie nicht close aufrufen, aber die Datei ist dann nicht lesbar oder dauerhaft in Cloud Storage gespeichert.

Ausgabe:

Argumente

filename (erforderlich)
Die zu öffnende Datei im Format /bucket/object. Beispiel: /my_bucket/lyrics/southamerica/list5.txt.
mode (optional)
String Geben Sie 'r' an, um eine Datei zum Lesen zu öffnen (Standard). Geben Sie 'w' an, um eine vorhandene Datei zu überschreiben oder eine neue Datei zu erstellen.

content_type: (optional)
String Wird nur im Schreibmodus verwendet. Sie sollten den MIME-Typ der Datei angeben (Sie können einen beliebigen gültigen MIME-Typ angeben.) Falls Sie diesen Wert nicht angeben, verwendet Cloud Storage bei der Bereitstellung des Objekts standardmäßig den Typ binary/octet-stream.
options: (optional)

Dict. Wird nur im Schreibmodus verwendet. Unterstützte Optionen sind x-goog-acl, x-goog-meta-, cache-control, content-disposition und content-encoding.

Wenn Sie die x-goog-acl-Option nicht angeben, nutzt Cloud Storage die Standard-ACL des Buckets. Die für x-goog-acl gültigen Werte sind in der Cloud Storage-Dokumentation für x-goog-acl. aufgelistet.

Sie können benutzerdefinierte Objektmetadaten mithilfe der Header x-goog-meta- festlegen. Beispiel:

gcs_file = cloudstorage.open(filename, 'w', content_type='text/plain', options={'x-goog-acl': 'private','x-goog-meta-foo': 'foo', 'x-goog-meta-bar': 'bar'})
read_buffer_size: (optional)
Ganzzahl Wird nur im Lesemodus verwendet. Wenn Sie diesen Wert nicht festlegen, wird die Standardpuffergröße verwendet (empfohlen). Bei Lesevorgängen sollten Sie für eine optimale Prefetch-Leistung nach read_buffer_size lesen.
retry_params= None (optional)
Ein RetryParams-Objekt, in dem Sie alle Änderungen angeben, die Sie an der Standardzeitüberschreitung und den Wiederholungseinstellungen dieses Aufrufs vornehmen möchten.

Ergebniswert

Gibt einen Lese- oder Schreibpuffer zurück, der eine dateiähnliche Schnittstelle unterstützt. Auf dieser können die Standardfunktionen von Python read, write und close aufgerufen werden. Dieser Puffer muss nach dem Lesen oder Schreiben geschlossen werden.

Nach oben


cloudstorage.stat(filename, retry_params=None)

Gibt ein GCSFileStat-Objekt zurück, das Dateimetadaten enthält.

Löst cloudstorage.NotFoundError aus, wenn das angegebene Cloud Storage-Objekt nicht existiert.

Argumente

filename (erforderlich)
Die zu öffnende Datei im Format /bucket/object. Beispiel: /my_bucket/lyrics/southamerica/list5.txt
retry_params= None (optional)
Ein RetryParams-Objekt, in dem Sie alle Änderungen angeben, die Sie an der Standardzeitüberschreitung und den Wiederholungseinstellungen dieses Aufrufs vornehmen möchten.

Ergebniswert

Gibt ein GCSFileStat-Objekt zurück, das Dateimetadaten enthält.

Nach oben