Funciones en la biblioteca cliente de App Engine para Cloud Storage

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

Funciones

  • cloudstorage.copy2() copia el archivo especificado en el nombre de archivo especificado nuevo, en el mismo depósito de Cloud Storage.
  • cloudstorage.delete() borra el objeto especificado del depósito de Cloud Storage.
  • cloudstorage.listbucket() enumera los objetos en el depósito de Cloud Storage.
  • cloudstorage.open() abre un objeto existente en el depósito de Cloud Storage para leer o reemplazar, o crea un objeto nuevo, según el modo especificado.
  • cloudstorage.stat() proporciona información de metadatos sobre el archivo, como tipo de contenido, tamaño, marca de tiempo, resumen de MD5 y encabezados de Cloud Storage.

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

Clases

Funciones

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

Copia el archivo especificado en el nuevo nombre de archivo especificado y, de manera predeterminada, también copia los metadatos. De manera opcional, puedes reemplazar los metadatos de la copia si proporcionas el parámetro metadata.

Genera cloudstorage.NotFoundError si el objeto de Cloud Storage especificado no existe o cloudstorage.AuthorizationError si falla la autorización.

Argumentos

src (obligatorio)
El nombre completo del archivo de Cloud Storage para el objeto, en el formato /bucket/object_name. Debe ser un nombre de archivo completo y puede incluir el delimitador `/`.
dst (obligatorio)
El nombre completo del archivo de Cloud Storage para la copia del objeto, en el formato /bucket/object_name. Debe ser un nombre de archivo completo y puede incluir el delimitador `/`.
metadata=None (opcional)
Un diccionario de metadatos para esta copia, por ejemplo, {'x-goog-meta-foo': 'bar'}. Si suministras el parámetro de metadatos, no se copia ninguno de los metadatos originales en el archivo nuevo. Si no se proporcionan metadatos, (None), se copian todos los metadatos del archivo de origen.
retry_params=None (opcional)
Un objeto RetryParams en el que suministras cualquier cambio que deseas realizar en la configuración predeterminada del tiempo de espera y los reintentos para esta llamada.

Ejemplo

Para copiar un archivo, pero agregando metadatos nuevos y luego ignorando el error si el archivo fuente no existe:
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)

Borra el archivo especificado del bucket de Cloud Storage.

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

Argumentos

filename (obligatorio)
El nombre completo del archivo de Cloud Storage para el objeto, en 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 suministras cualquier cambio que deseas realizar en la configuración predeterminada del tiempo de espera y los reintentos para esta llamada.

Ejemplo

Para borrar un archivo, pero ignorando el error cuando el archivo no existe:
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)
Muestra un objeto iterador del depósito. Este iterador muestra 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 obtenga los resultados.

Esta función funciona en dos modos diferentes según si usas el argumento delimiter o no:

  • Modo normal (predeterminado): Enumera todos los archivos en el bucket sin ningún concepto de jerarquía. (Cloud Storage no posee jerarquías de directorio reales).
  • Modo de emulación de directorio: 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 mostrarán los objetos cuya ruta de acceso completa comience con path_prefix.
marker=None (opcional)
String. Otro prefijo de ruta de acceso. Solo se mostrarán los objetos cuya ruta de acceso completa comienza lexicográficamente después de un marcador. El archivo usado como marcador no se muestra. Por ejemplo, si deseas que se enumeren todos los archivos a partir de superduperfoo3.txt, especifica el archivo inmediatamente anterior a superduperfoo3.txt, por ejemplo: 
stat = cloudstorage.listbucket("/my_bucket/foo", marker='/my_bucket/foo/superduperfoo2.txt')
Una forma de usar este parámetro es usarlo con max_keys para “desplazarse” por los nombres de archivo del depósito.
max_keys=None (opcional)
Número entero. Especifica el número máximo de objetos que se deben mostrar. Úsalo si sabes cuántos objetos deseas. (De lo contrario, la biblioteca cliente de Cloud Storage almacena automáticamente en búferes y pagina todos los resultados). Se puede usar con marker para desplazarse por los nombres de archivo en un depósito. 
stats = cloudstorage.listbucket(bucket + '/foo', max_keys=page_size, marker=stat.filename)
delimiter=None (opcional)
String. Activa el modo de directorio. Puedes especificar uno o varios caracteres para usar como separador de directorios.
retry_params=None (opcional)
Un objeto RetryParams en el que suministras cualquier cambio que deseas realizar en la configuración predeterminada del tiempo de espera y los reintentos para esta llamada.

Valor del resultado

Muestra un iterador de objetos GCSFileStat para los archivos con coincidencia, ordenados por nombre de archivo. En el modo regular, los objetos GCSFileStat que se muestran tienen los siguientes datos:

  • filename
  • etag (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, entonces, la única otra propiedad en el objeto es filename. Si is_dir es False, el GCSFileStat también contiene todas las otras 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 lectura. En el modo de escritura w, si el archivo especificado existe, lo abre para reemplazarlo (el anexado de datos no se admite). Si el archivo no existe, se crea en el bucket especificado.

Cuando termines de escribir, si deseas leer el archivo o almacenarlo en Cloud Storage, cierra el archivo con la función close. No es un error si no llamas a close, pero el archivo no será legible ni persistirá en Cloud Storage.

Se genera el error:

Argumentos

filename (obligatorio)
El archivo que se abrirá, en el formato /bucket/object. Por ejemplo, /my_bucket/lyrics/southamerica/list5.txt.
mode (opcional)
String. Especifica 'r' si deseas abrir un archivo para lectura (modo predeterminado). Especifica 'w' si deseas abrir un archivo existente para reemplazar o crear un archivo nuevo.

content_type: (opcional)
String. Solo se usa en el modo de escritura. Deberías especificar el tipo MIME del archivo (puedes especificar cualquier tipo MIME válido). Si no proporcionas este valor, Cloud Storage usa el tipo binary/octet-stream de forma predeterminada cuando entrega el objeto.
options: (opcional)

Diccionario. Solo se usa 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 una opción x-goog-acl, Cloud Storage usa la LCA predeterminada del depósito. Los valores válidos para x-goog-acl se enumeran en la documentación de Cloud Storage de x-goog-acl.

Puedes especificar metadatos de objeto personalizados mediante los 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. Solo se usa en el modo de lectura. Si no configuras este valor, se usa el tamaño del búfer predeterminado (recomendado). Cuando leas, deberías leer con read_buffer_size para obtener un rendimiento óptimo de la carga previa.
retry_params=None (opcional)
Un objeto RetryParams en el que suministras cualquier cambio que deseas realizar en la configuración predeterminada del tiempo de espera y los reintentos para esta llamada.

Valor del resultado

Muestra un búfer de lectura o escritura que admite una interfaz similar a un archivo en la que puedes invocar funciones read, write y close estándar de Python. Este búfer se debe cerrar una vez que terminas de leer o escribir.

Volver al principio


cloudstorage.stat(filename,retry_params=None)

Muestra un objeto GCSFileStat que contiene metadatos de archivo.

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

Argumentos

filename (obligatorio)
El archivo que se abrirá, en el formato /bucket/object. Por ejemplo, /my_bucket/lyrics/southamerica/list5.txt
retry_params=None (opcional)
Un objeto RetryParams en el que suministras cualquier cambio que deseas realizar en la configuración predeterminada del tiempo de espera y los reintentos para esta llamada.

Valor del resultado

Muestra un objeto GCSFileStat que contiene metadatos de archivo.

Volver al principio