Funciones de la biblioteca de cliente de App Engine para Cloud Storage

La biblioteca de cliente de App Engine para Cloud Storage proporciona las siguientes funciones:

Funciones

  • cloudstorage.copy2() copia el archivo especificado en el nuevo nombre de archivo especificado en el mismo segmento de Cloud Storage.
  • cloudstorage.delete() elimina el objeto especificado del segmento de Cloud Storage.
  • cloudstorage.listbucket() muestra los objetos del segmento de Cloud Storage.
  • cloudstorage.open() abre un objeto en el segmento de Cloud Storage para leerlo o sobrescribirlo, o bien crea un objeto, en función del modo especificado.
  • cloudstorage.stat() proporciona información de metadatos sobre el archivo, como el tipo de contenido, el tamaño, la marca de tiempo, el digest MD5 y los encabezados de Cloud Storage.

Una vez que se invoca cloudstorage.open() para devolver el objeto similar a un archivo que representa el objeto de Cloud Storage especificado, puede usar las funciones de archivo estándar de Python, como write() y close(), para escribir un objeto en el segmento de Cloud Storage, o read() para leer un objeto del segmento de Cloud Storage.

Clases

Functions

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

Copia el archivo especificado en el nuevo nombre de archivo especificado. De forma predeterminada, también se copian los metadatos. Si quieres, puedes sobrescribir los metadatos de la copia proporcionando el parámetro opcional metadata.

Genera cloudstorage.NotFoundError si el objeto de Cloud Storage especificado no existe o cloudstorage.AuthorizationError si se produce un error de autorización.

Argumentos

src (obligatorio)
Nombre de archivo completo de Cloud Storage del objeto, con el formato /bucket/object_name. Debe ser un nombre de archivo completo y puede incluir el delimitador `/`.
dst (obligatorio)
Nombre de archivo completo de Cloud Storage de la copia del objeto, con el formato /bucket/object_name. Debe ser un nombre de archivo completo y puede incluir el delimitador `/`.
metadata= None (Opcional)
Un diccionario de metadatos de esta copia. Por ejemplo, {'x-goog-meta-foo': 'bar'}. Si proporcionas el parámetro de metadatos, ninguno de los metadatos originales se copiará en el nuevo archivo. Si no se proporcionan metadatos (None), se copiarán todos los metadatos del archivo de origen.
retry_params= None (opcional)
Un objeto RetryParams en el que se proporcionan los cambios que quieras hacer en los ajustes predeterminados de tiempo de espera y reintentos de esta llamada.

Ejemplo

Para copiar un archivo, añadir metadatos nuevos e ignorar el error si el archivo de origen no existe, haz lo siguiente:
import cloudstorage

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

Volver al principio


cloudstorage.delete (filename, retry_params=None)

Elimina el archivo especificado del segmento de Cloud Storage.

Genera cloudstorage.NotFoundError si el objeto de Cloud Storage especificado no existe.

Argumentos

filename (obligatorio)
Nombre de archivo completo de Cloud Storage del objeto, con el formato /bucket/object_name. Debe ser un nombre de archivo completo y puede incluir el delimitador `/`.
retry_params= None (opcional)
Un objeto RetryParams en el que se proporcionan los cambios que quieras hacer en los ajustes predeterminados de tiempo de espera y reintentos de esta llamada.

Ejemplo

Para eliminar un archivo, pero ignorar el error cuando el archivo no exista:
import cloudstorage

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

Volver al principio


cloudstorage.listbucket (path_prefix, marker=None, max_keys=None, delimiter=None, retry_params=None)
devuelve un objeto iterador de contenedor. Este iterador devuelve una lista ordenada de objetos que coinciden con todos los filtros. Ten en cuenta que esta función es asíncrona. No se bloquea a menos que se llame al iterador antes de que el iterador obtenga resultados.

Esta función opera de dos formas distintas en función de si usas el argumento delimiter o no:

  • Modo normal (predeterminado): muestra todos los archivos del segmento sin ningún concepto de jerarquía. Cloud Storage no tiene jerarquías de directorios reales.
  • Modo de emulación de directorios: si especificas el argumento delimiter, se usa como separador de ruta para emular una jerarquía de directorios.

Argumentos

path_prefix (Obligatorio)
Una ruta de Cloud Storage con el formato /bucket o /bucket/prefix, por ejemplo, /bucket/foo/2001. Solo se devolverán los objetos cuya ruta completa empiece por path_prefix.
marker= None (Opcional)
Cadena. Otro prefijo de ruta. Solo se devolverán los objetos cuyo fullpath empiece lexicográficamente después del marcador (exclusivamente). No se devuelve el archivo usado como `marker`. Por ejemplo, si quieres que se muestren todos los archivos que empiezan por superduperfoo3.txt, especifica el archivo que va inmediatamente antes de superduperfoo3.txt, por ejemplo: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
 Una forma de usar este parámetro es combinarlo con max_keys para desplazarse por los nombres de los archivos del segmento.
max_keys= None (Opcional)
Número entero. Especifica el número máximo de objetos que se devolverán. Úsalo si sabes cuántos objetos quieres. De lo contrario, la biblioteca de cliente de Cloud Storage almacenará en búfer y paginará automáticamente todos los resultados. Se puede usar con marker para desplazarse por los nombres de archivo de un contenedor. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter= None (Opcional)
Cadena. Activa el modo de directorio. Puedes especificar uno o varios caracteres que se usarán como separador de directorios.
retry_params= None (opcional)
Un objeto RetryParams en el que se proporcionan los cambios que quieras hacer en los ajustes predeterminados de tiempo de espera y reintentos de esta llamada.

Valor del resultado

Devuelve un iterador de objetos GCSFileStat sobre los archivos coincidentes, ordenados por nombre de archivo. En el modo normal, los objetos GCSFileStat devueltos tienen los siguientes datos:

  • filename
  • etag (la representación hexadecimal del hash MD5 del contenido del archivo)
  • st_size (longitud del contenido de los encabezados)
  • st_ctime
  • is_dir

Nota: Si la propiedad is_dir del objeto GCSFileStat es True, la única propiedad que puede tener el objeto es filename. Si is_dir es False, GCSFileStat también contiene todas las demás propiedades.

Volver al principio


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

En el modo de lectura (r), se abre el objeto de Cloud Storage especificado para leerlo. En el modo de escritura w, si el archivo especificado existe, se abre para sobrescribirlo (no se admite la opción de añadir contenido). Si el archivo no existe, se crea en el segmento especificado.

Cuando termines de escribir, si quieres leer el archivo o almacenarlo en Cloud Storage, cierra el archivo con la función close. No se trata de un error si no llamas a close, pero el archivo no se podrá leer ni conservar en Cloud Storage.

Aumentos:

Argumentos

filename (obligatorio)
El archivo que se va a abrir, en el formato /bucket/object. Por ejemplo,/my_bucket/lyrics/southamerica/list5.txt.
mode (Opcional)
Cadena. Especifica "r" para abrir un archivo para lectura (opción predeterminada). Especifica "w" para abrir un archivo que ya tengas y sobrescribirlo, o para crear un archivo.

content_type: (opcional)
Cadena. Se usa solo en el modo de escritura. Debes especificar el tipo MIME del archivo (puedes especificar cualquier tipo MIME válido). Si no proporciona este valor, Cloud Storage usará el tipo binary/octet-stream de forma predeterminada cuando sirva el objeto.
Opciones: (opcional)

Dict. Se usa solo en el modo de escritura. Las opciones admitidas son x-goog-acl, x-goog-meta-, cache-control, content-disposition y content-encoding.

Si no proporcionas la opción x-goog-acl, Cloud Storage usará la LCA predeterminada del segmento. Los valores válidos de x-goog-acl se indican en la documentación de Cloud Storage sobre x-goog-acl.

Puede especificar metadatos de objeto personalizados mediante encabezados x-goog-meta-. Por ejemplo:

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: (opcional)
Número entero. Se usa solo en el modo de lectura. Si no define este valor, se usará el tamaño de búfer predeterminado (recomendado). Cuando leas, debes hacerlo por read_buffer_size para que el prefetch funcione de forma óptima.
retry_params= None (opcional)
Un objeto RetryParams en el que se proporcionan los cambios que quieras hacer en los ajustes predeterminados de tiempo de espera y reintentos de esta llamada.

Valor del resultado

Devuelve un búfer de lectura o escritura que admite una interfaz similar a un archivo en la que puedes invocar las funciones estándar de Python read, write y close. Este búfer debe cerrarse después de terminar de leer o escribir.

Volver al principio


cloudstorage.stat(filename, retry_params=None)

Devuelve un objeto GCSFileStat que contiene metadatos del archivo.

Genera cloudstorage.NotFoundError si el objeto de Cloud Storage especificado no existe.

Argumentos

filename (obligatorio)
El archivo que se va a abrir, en el formato /bucket/object. Por ejemplo,/my_bucket/lyrics/southamerica/list5.txt
retry_params= None (opcional)
Un objeto RetryParams en el que se proporcionan los cambios que quieras hacer en los ajustes predeterminados de tiempo de espera y reintentos de esta llamada.

Valor del resultado

Devuelve un objeto GCSFileStat que contiene metadatos del archivo.

Volver al principio