Fonctions de la bibliothèque cliente App Engine pour Cloud Storage

La bibliothèque cliente App Engine pour Cloud Storage fournit les fonctions suivantes :

Fonctions

  • cloudstorage.copy2 () copie le fichier spécifié vers le nouveau nom de fichier spécifié dans le même bucket Cloud Storage.
  • supprime l'objet spécifié du bucket Cloud Storage.
  • répertorie les objets du bucket Cloud Storage.
  • ouvre un objet existant dans le bucket Cloud Storage pour la lecture ou le remplacement, ou crée un nouvel objet, selon le mode spécifié.
  • cloudstorage.stat() fournit des informations de métadonnées sur le fichier, telles que le type de contenu, la taille, l'horodatage, le condensé MD5 et les en-têtes Cloud Storage.

Une fois que cloudstorage.open() est appelé pour renvoyer l'objet de type fichier représentant l'objet Cloud Storage spécifié, vous pouvez utiliser les fonctions de fichier Python standards, telles que write() et close(), pour écrire un objet dans le bucket Cloud Storage ou read() pour lire un objet à partir du bucket Cloud Storage.

Cours

Fonctions

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

Copie le fichier spécifié vers le nouveau nom de fichier spécifié, en copiant également par défaut les métadonnées. Si vous le souhaitez, vous pouvez écraser les métadonnées de la copie en indiquant le paramètre facultatif metadata.

Génère cloudstorage.NotFoundError si l'objet Cloud Storage spécifié n'existe pas ou cloudstorage.AuthorizationError si l'autorisation a échoué.

Arguments

src (obligatoire)
Nom complet du fichier Cloud Storage de l'objet, au format /bucket/object_name. Doit être un nom de fichier complet et peut inclure le délimiteur `/`.
dst (obligatoire)
Nom complet du fichier Cloud Storage pour la copie de l'objet, au format /bucket/object_name. Doit être un nom de fichier complet et peut inclure le délimiteur `/`.
metadata=None (facultatif)
Dict de métadonnées pour cette copie, par exemple {'x-goog-meta-foo': 'bar'}. Si vous fournissez le paramètre de métadonnées, aucune des métadonnées d'origine n'est copiée dans le nouveau fichier. Si aucune métadonnée n'est fournie, (None), toutes les métadonnées du fichier source sont copiées.
retry_params= None (facultatif)
Objet RetryParams dans lequel vous indiquez les modifications que vous souhaitez apporter au délai d'attente par défaut et les paramètres concernant les tentatives de nouvelle connexion pour cet appel.

Exemple

Pour copier un fichier en ajoutant de nouvelles métadonnées et en ignorant l'erreur si le fichier source n'existe pas :
import cloudstorage

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

Haut de page


cloudstorage.delete (filename, retry_params=None)

Supprime le fichier spécifié du bucket Cloud Storage.

Génère cloudstorage.NotFoundError si l'objet Cloud Storage spécifié n'existe pas.

Arguments

filename (obligatoire)
Nom complet du fichier Cloud Storage de l'objet, au format /bucket/object_name. Doit être un nom de fichier complet et peut inclure le délimiteur `/`.
retry_params= None (facultatif)
Objet RetryParams dans lequel vous indiquez les modifications que vous souhaitez apporter au délai d'attente par défaut et les paramètres concernant les tentatives de nouvelle connexion pour cet appel.

Exemple

Pour supprimer un fichier, mais ignorer l'erreur lorsque le fichier n'existe pas, procédez comme suit :
import cloudstorage

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

Haut de page


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
Renvoie un objet itérateur de bucket. Cet itérateur renvoie une liste d'objets triée correspondant à tous les filtres. Notez que cette fonction est asynchrone. Il ne bloque pas sauf si l'itérateur est appelé avant qu'il n'ait obtenu des résultats.

Cette fonction opère dans deux modes différents selon que vous utilisez ou non l'argument delimiter :

  • Mode normal (par défaut) : répertorie tous les fichiers du bucket sans aucun concept de hiérarchie. Cloud Storage n'a pas de réelle hiérarchie de répertoire.
  • Mode d'émulation de répertoire : si vous spécifiez l'argument delimiter, il sert de séparateur de chemin pour émuler une hiérarchie de répertoires.

Arguments

path_prefix (obligatoire)
Chemin Cloud Storage au format /bucket ou /bucket/prefix (par exemple, /bucket/foo/2001). Seuls les objets dont le chemin complet commence par path_prefix seront renvoyés.
marker= None (facultatif)
Chaîne. Autre préfixe de chemin. Seuls les objets dont le chemin complet commence de façon lexicographique après le marqueur exclusivement seront renvoyés. Le fichier utilisé comme `marker` n'est pas renvoyé. Par exemple, si vous souhaitez que tous les fichiers répertoriés à partir de superduperfoo3.txt soient répertoriés, spécifiez le fichier précédant immédiatement superduperfoo3.txt, par exemple : 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
Une façon d'utiliser ce paramètre consiste à l'utiliser avec max_keys pour "parcourir" les noms de fichiers du bucket.
max_keys= None (facultatif)
Entier. Spécifie le nombre maximal d'objets à renvoyer. Utilisez-le si vous savez combien d'objets vous voulez. Sinon, la bibliothèque cliente Cloud Storage met en tampon et pagine automatiquement tous les résultats. Peut être utilisé avec marker pour parcourir les noms de fichiers d'un bucket. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (facultatif)
Chaîne. Active le mode répertoire. Vous pouvez spécifier un ou plusieurs caractères à utiliser comme séparateur de répertoire.
retry_params= None (facultatif)
Objet RetryParams dans lequel vous indiquez les modifications que vous souhaitez apporter au délai d'attente par défaut et les paramètres concernant les tentatives de nouvelle connexion pour cet appel.

Result Value

Renvoie un itérateur d'objets GCSFileStat sur les fichiers correspondants, triés par nom de fichier. En mode standard, les objets GCSFileStat renvoyés contiennent les données suivantes :

  • filename
  • etag (Représentation hexadécimale du hachage MD5 du contenu du fichier)
  • st_size (longueur du contenu des en-têtes)
  • st_ctime
  • is_dir

Remarque : Si la propriété is_dir de l'objet GCSFileStat est True, la seule autre propriété de l'objet est filename. Si is_dir possède la valeur False, l'objet GCSFileStat contient également toutes les autres propriétés.

Haut de page


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

En mode lecture (r), ouvre l'objet Cloud Storage spécifié pour la lecture. En mode écriture w, si le fichier spécifié existe, il l'ouvre pour écrasement (l'ajout n'est pas pris en charge). Si le fichier n'existe pas, il est créé dans le bucket spécifié.

Une fois l'écriture terminée, si vous souhaitez lire le fichier et/ou le stocker dans Cloud Storage, fermez-le à l'aide de la fonction close. Le fait de ne pas appeler close ne constitue pas une erreur, cependant, le fichier ne sera ni lisible ni conservé dans Cloud Storage.

Déclenche :

Arguments

filename (obligatoire)
Fichier à ouvrir, au format /bucket/object. Par exemple, /my_bucket/lyrics/southamerica/list5.txt.
mode (facultatif)
Chaîne. Spécifiez 'r' pour ouvrir un fichier pour lecture (par défaut). Spécifiez 'w' pour ouvrir un fichier existant en vue de son remplacement ou pour créer un fichier.

content_type: (facultatif)
Chaîne. Utilisé uniquement en mode écriture. Vous devez spécifier le type MIME du fichier (vous pouvez spécifier n'importe quel type MIME valide.) Si vous ne fournissez pas cette valeur, Cloud Storage utilise par défaut le type binary/octet-stream lorsqu'il diffuse l'objet.
options : (facultatif)

Dict. Utilisé uniquement en mode écriture. Les options compatibles sont x-goog-acl, x-goog-meta-, cache-control, content-disposition et content-encoding.

Si vous ne définissez pas d'option x-goog-acl, Cloud Storage utilise la liste de contrôle d'accès par défaut. Les valeurs valides pour x-goog-acl sont répertoriées dans la documentation Cloud Storage pour x-goog-acl.

Vous pouvez spécifier des métadonnées d'objet personnalisées à l'aide de l'en-tête x-goog-meta-. Exemple :

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: (facultatif)
Entier. Utilisé uniquement en mode lecture. Si vous ne définissez pas cette valeur, la taille de la mémoire tampon par défaut est utilisée (recommandé). Lors de la lecture, vous devez lire par read_buffer_size pour optimiser les performances de prérécupération.
retry_params= None (facultatif)
Objet RetryParams dans lequel vous indiquez les modifications que vous souhaitez apporter au délai d'attente par défaut et les paramètres concernant les tentatives de nouvelle connexion pour cet appel.

Result Value

Renvoie un tampon de lecture ou d'écriture compatible avec une interface de type fichier sur laquelle vous pouvez appeler les fonctions read, write et close Python standards. Ce tampon doit être fermé après la lecture ou l'écriture.

Haut de page


cloudstorage.stat(filename, retry_params=None)

Renvoie un objet GCSFileStat contenant les métadonnées du fichier.

Génère cloudstorage.NotFoundError si l'objet Cloud Storage spécifié n'existe pas.

Arguments

filename (obligatoire)
Fichier à ouvrir, au format /bucket/object. Par exemple, /my_bucket/lyrics/southamerica/list5.txt.
retry_params= None (facultatif)
Objet RetryParams dans lequel vous indiquez les modifications que vous souhaitez apporter au délai d'attente par défaut et les paramètres concernant les tentatives de nouvelle connexion pour cet appel.

Result Value

Renvoie un objet GCSFileStat contenant les métadonnées du fichier.

Haut de page