Complemento de la biblioteca cliente de Boto

En este instructivo, se muestra cómo escribir un programa de Python simple que realiza operaciones básicas de Cloud Storage con la API de XML. En este documento, se supone que estás familiarizado con Python y los conceptos y operaciones de Cloud Storage presentados en la Guía de inicio rápido de Console.

¿Deberías usar las bibliotecas cliente de Cloud Storage en su lugar?

En general, debes usar la Biblioteca de cliente de Cloud Storage para Python a fin de trabajar con los objetos y depósitos de Cloud Storage. Los ejemplos de código de las guías de Cloud Storage usan las Bibliotecas cliente de Cloud Storage, que proporcionan más flexibilidad. Usa esta guía si deseas interactuar de forma específica con Cloud Storage a través de la API de XML y la biblioteca de boto.

Configura tu entorno

Antes de comenzar este instructivo, debes hacer lo siguiente:

  1. Instala una versión independiente de gsutil en tu computadora.
  2. Instala la biblioteca de boto y gcs-oauth2-boto-plugin.

    boto es una biblioteca de código abierto de Python que se usa como interfaz para Cloud Storage. gcs-oauth2-boto-plugin es un complemento de autenticación para el marco de trabajo del complemento de autenticación boto. Proporciona credenciales de OAuth 2.0 que se pueden usar con Cloud Storage.

    La configuración para usar la biblioteca boto y el complemento oauth2 dependerá del sistema que uses. Usa los ejemplos de configuración siguientes como guía. Estos comandos instalan pip y, luego, lo usan para instalar otros paquetes. Los últimos tres comandos muestran cómo probar la importación de los dos módulos para verificar la instalación.

    Debian y Ubuntu

    wget https://bootstrap.pypa.io/get-pip.py
    sudo python get-pip.py
    sudo apt-get update
    sudo apt-get upgrade
    sudo apt-get install gcc python-dev python-setuptools libffi-dev libssl-dev
    sudo pip install virtualenv
    virtualenv venv
    source ./venv/bin/activate
    (venv)pip install gcs-oauth2-boto-plugin
    (venv)python
    >>>import boto
    >>>import gcs_oauth2_boto_plugin
    

    CentOS, RHEL y Fedora

    wget https://bootstrap.pypa.io/get-pip.py
    sudo python get-pip.py
    sudo yum install gcc openssl-devel python-devel python-setuptools libffi-devel
    sudo pip install virtualenv
    virtualenv venv
    source ./venv/bin/activate
    (venv)pip install gcs-oauth2-boto-plugin
    (venv)python
    >>>import boto
    >>>import gcs_oauth2_boto_plugin
    
  3. Configura tu archivo de configuración boto para que use OAuth2.0.

    Puedes configurar tu archivo de configuración boto para que use credenciales de cuenta de servicio o cuenta de usuario. Es preferible usar credenciales de cuenta de servicio cuando se realiza la autenticación en nombre de un servicio o aplicación, y credenciales de cuenta de usuario cuando se realiza en nombre de un usuario específico (es decir, una persona). Para obtener más información sobre estos dos tipos de credenciales, consulta Tipos de credenciales compatibles.

    Cuentas de servicio

    Para usar credenciales de cuenta de servicio, haz lo siguiente:

    1. Usa una cuenta de servicio existente o crea una nueva y descarga la clave privada asociada. Asegúrate de obtener la clave privada en formato PKCS12: de forma predeterminada, cuando se crea una nueva clave, se descarga en formato JSON.
    2. Configura el archivo .boto con la cuenta de servicio. Puedes hacer esto con gsutil:
      gsutil config -e

      El comando te solicitará la dirección de correo electrónico de la cuenta de servicio y la ubicación de su clave privada (.p12). Asegúrate de tener la clave privada en la computadora en la que ejecutas el comando gsutil.

    Cuentas de usuario

    Para usar credenciales de cuenta de usuario, haz lo siguiente:

    1. Si aún no tienes un archivo .boto, crea uno. Puedes hacer esto con gsutil.

      gsutil config
    2. Usa un ID de cliente existente para una aplicación o crea uno nuevo.

    3. Edita el archivo .boto. En la sección [OAuth2], usa los valores que creaste para especificar client_id y client_secret.

    4. Ejecuta el comando gsutil config de nuevo para generar un token de actualización basado en el ID de cliente y el secreto que ingresaste.

      Si recibes un mensaje de error que indica que no se puede crear una copia de seguridad del archivo .boto, quita o cambia el nombre del archivo de configuración de copia de seguridad .boto.bak.

    5. Configura la lógica de resguardo del token de actualización.

      gcs-oauth2-boto-plugin requiere una lógica de resguardo para generar tokens de autenticación cuando usas credenciales de aplicación. La lógica alternativa no es necesaria cuando usas una cuenta de servicio.

      Tienes las siguientes opciones para habilitar el resguardo:

      1. Configura client_id y client_secret en el archivo de configuración .boto. Esta es la opción recomendada, y es necesaria para usar gsutil con tu nuevo archivo de configuración .boto.
      2. Configura las variables de entorno OAUTH2_CLIENT_ID y OAUTH2_CLIENT_SECRET.
      3. Usa la función SetFallbackClientIdAndSecret como se muestra en los ejemplos a continuación.

Trabaja con Cloud Storage

Configura tu archivo fuente de Python

Para comenzar este instructivo, usa tu editor de texto favorito a fin de crear un nuevo archivo de Python. Luego, agrega las siguientes directivas, instrucciones de importación, configuración y asignaciones constantes.

Ten en cuenta que, en este código, usamos la función SetFallbackClientIdAndSecret como un resguardo para generar tokens de actualización. Consulta Usa credenciales de aplicación para conocer otras formas de especificar un resguardo. Si usas una cuenta de servicio para la autenticación, no necesitas incluir la lógica de resguardo.

#!/usr/bin/python

import boto
import gcs_oauth2_boto_plugin
import os
import shutil
import StringIO
import tempfile
import time

# URI scheme for Cloud Storage.
GOOGLE_STORAGE = 'gs'
# URI scheme for accessing local files.
LOCAL_FILE = 'file'

# Fallback logic. In https://console.cloud.google.com/
# under Credentials, create a new client ID for an installed application.
# Required only if you have not configured client ID/secret in
# the .boto file or as environment variables.
CLIENT_ID = 'your client id'
CLIENT_SECRET = 'your client secret'
gcs_oauth2_boto_plugin.SetFallbackClientIdAndSecret(CLIENT_ID, CLIENT_SECRET)

Crea depósitos

El código siguiente crea dos depósitos. Debido a que los nombres de los depósitos deben ser únicos a nivel global (consulta los lineamientos de nomenclatura), se adjunta una marca de tiempo a cada nombre de depósito para garantizar que sea único.

Si estos nombres de depósito ya están en uso, deberás modificar el código para generar nombres de depósito únicos.

now = time.time()
CATS_BUCKET = 'cats-%d' % now
DOGS_BUCKET = 'dogs-%d' % now

# Your project ID can be found at https://console.cloud.google.com/
# If there is no domain for your project, then project_id = 'YOUR_PROJECT'
project_id = 'YOUR_DOMAIN:YOUR_PROJECT'

for name in (CATS_BUCKET, DOGS_BUCKET):
  # Instantiate a BucketStorageUri object.
  uri = boto.storage_uri(name, GOOGLE_STORAGE)
  # Try to create the bucket.
  try:
    # If the default project is defined,
    # you do not need the headers.
    # Just call: uri.create_bucket()
    header_values = {"x-goog-project-id": project_id}
    uri.create_bucket(headers=header_values)

    print 'Successfully created bucket "%s"' % name
  except boto.exception.StorageCreateError, e:
    print 'Failed to create bucket:', e

Enumera depósitos

Si deseas recuperar una lista de todos los depósitos, llama a storage_uri() para crear una instancia de un objeto BucketStorageUri y especifica la string vacía como el URI. Luego, llama al método de instancia get_all_buckets().

uri = boto.storage_uri('', GOOGLE_STORAGE)
# If the default project is defined, call get_all_buckets() without arguments.
for bucket in uri.get_all_buckets(headers=header_values):
  print bucket.name

Sube objetos

Si deseas subir objetos, crea un objeto de archivo (abierto para lectura) que apunte a tu archivo local y un objeto de URI de almacenamiento que apunte al objeto de destino en Cloud Storage. Llama al método de instancia set_file_from_contents() y especifica el identificador del archivo como argumento.

# Make some temporary files.
temp_dir = tempfile.mkdtemp(prefix='googlestorage')
tempfiles = {
    'labrador.txt': 'Who wants to play fetch? Me!',
    'collie.txt': 'Timmy fell down the well!'}
for filename, contents in tempfiles.iteritems():
  with open(os.path.join(temp_dir, filename), 'w') as fh:
    fh.write(contents)

# Upload these files to DOGS_BUCKET.
for filename in tempfiles:
  with open(os.path.join(temp_dir, filename), 'r') as localfile:

    dst_uri = boto.storage_uri(
        DOGS_BUCKET + '/' + filename, GOOGLE_STORAGE)
    # The key-related functions are a consequence of boto's
    # interoperability with Amazon S3 (which employs the
    # concept of a key mapping to localfile).
    dst_uri.new_key().set_contents_from_file(localfile)
  print 'Successfully created "%s/%s"' % (
      dst_uri.bucket_name, dst_uri.object_name)

shutil.rmtree(temp_dir)  # Don't forget to clean up!

Enumera objetos

Para enumerar todos los objetos de un depósito, llama a storage_uri() y especifica el URI del depósito y el esquema de URI de Cloud Storage como argumentos. Luego, recupera una lista de objetos mediante el método de instancia get_bucket().

uri = boto.storage_uri(DOGS_BUCKET, GOOGLE_STORAGE)
for obj in uri.get_bucket():
  print '%s://%s/%s' % (uri.scheme, uri.bucket_name, obj.name)
  print '  "%s"' % obj.get_contents_as_string()

Descarga y copia objetos

El siguiente código lee los objetos de DOGS_BUCKET y los copia en el directorio principal y en CATS_BUCKET. También demuestra que puedes usar la biblioteca de boto para operar con archivos locales y con objetos de Cloud Storage mediante la misma interfaz.

dest_dir = os.getenv('HOME')
for filename in ('collie.txt', 'labrador.txt'):
  src_uri = boto.storage_uri(
      DOGS_BUCKET + '/' + filename, GOOGLE_STORAGE)

  # Create a file-like object for holding the object contents.
  object_contents = StringIO.StringIO()

  # The unintuitively-named get_file() doesn't return the object
  # contents; instead, it actually writes the contents to
  # object_contents.
  src_uri.get_key().get_file(object_contents)

  local_dst_uri = boto.storage_uri(
      os.path.join(dest_dir, filename), LOCAL_FILE)

  bucket_dst_uri = boto.storage_uri(
      CATS_BUCKET + '/' + filename, GOOGLE_STORAGE)

  for dst_uri in (local_dst_uri, bucket_dst_uri):
    object_contents.seek(0)
    dst_uri.new_key().set_contents_from_file(object_contents)

  object_contents.close()

Realiza transferencias

Para realizar una carga de transmisión, usa el siguiente código:

dst_uri = boto.storage_uri(<bucket> + '/' + <object>, 'gs')
dst_uri.new_key().set_contents_from_stream(<stream object>)

Por ejemplo, el siguiente código realiza una carga de transmisión de un archivo llamado data_file a un objeto con el mismo nombre:

filename = 'data_file'
MY_BUCKET = 'my_app_bucket'
my_stream = open(filename, 'rb')
dst_uri = boto.storage_uri(MY_BUCKET + '/' + filename, 'gs')
dst_uri.new_key().set_contents_from_stream(my_stream)

Para realizar una descarga de transmisión, usa el siguiente código:

import sys

src_uri = boto.storage_uri(<bucket> + '/' + <object>, 'gs')
src_uri.get_key().get_file(sys.stdout)

Por ejemplo, el siguiente código realiza una descarga de transmisión de un objeto llamado data_file:

downloaded_file = 'saved_data_file'
MY_BUCKET = 'my_app_bucket'
object_name = 'data_file'
src_uri = boto.storage_uri(MY_BUCKET + '/' + object_name, 'gs')
src_uri.get_key().get_file(sys.stdout)

Cambia los LCA de los objetos

El siguiente código otorga los permisos especificados de FULL_CONTROL de Cuenta de Google para labrador.txt. Recuerda reemplazar valid-email-address por una dirección de correo electrónico válida de Cuenta de Google.

uri = boto.storage_uri(DOGS_BUCKET + '/labrador.txt', GOOGLE_STORAGE)
print str(uri.get_acl())
uri.add_email_grant('FULL_CONTROL', 'valid-email-address')
print str(uri.get_acl())

Lee metadatos de depósitos y objetos

Este código recupera y, luego, imprime los metadatos asociados con un depósito y un objeto.

# Print ACL entries for DOGS_BUCKET.
bucket_uri = boto.storage_uri(DOGS_BUCKET, GOOGLE_STORAGE)
for entry in bucket_uri.get_bucket().get_acl().entries.entry_list:
  entry_id = entry.scope.id
  if not entry_id:
    entry_id = entry.scope.email_address
  print 'SCOPE: %s' % entry_id
  print 'PERMISSION: %s\n' % entry.permission

# Print object metadata and ACL entries.
object_uri = boto.storage_uri(DOGS_BUCKET + '/labrador.txt', GOOGLE_STORAGE)
key = object_uri.get_key()
print ' Object size:\t%s' % key.size
print ' Last mod:\t%s' % key.last_modified
print ' MIME type:\t%s' % key.content_type
print ' MD5:\t%s' % key.etag.strip('"\'') # Remove surrounding quotes
for entry in key.get_acl().entries.entry_list:
  entry_id = entry.scope.id
  if not entry_id:
    entry_id = entry.scope.email_address
  print 'SCOPE: %s' % entry_id
  print 'PERMISSION: %s\n' % entry.permission

Borra objetos y depósitos

Para finalizar este instructivo, el siguiente código borra los objetos y depósitos que creaste. Un depósito debe estar vacío antes de que se pueda borrar, por lo que primero se borran sus objetos.

for bucket in (CATS_BUCKET, DOGS_BUCKET):
  uri = boto.storage_uri(bucket, GOOGLE_STORAGE)
  for obj in uri.get_bucket():
    print 'Deleting object: %s...' % obj.name
    obj.delete()
  print 'Deleting bucket: %s...' % uri.bucket_name
  uri.delete_bucket()

Volver al principio

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

¿Necesitas ayuda? Visita nuestra página de asistencia.