Plug-in de la bibliothèque cliente Boto

Ce tutoriel explique comment écrire un programme Python simple qui exécute des opérations Cloud Storage de base à l'aide de l'API XML. Dans ce document, nous partons du principe que vous connaissez bien Python ainsi que les concepts et opérations Cloud Storage présentés dans le guide de démarrage rapide de la console.

Devriez-vous plutôt utiliser les bibliothèques clientes Cloud Storage ?

En règle générale, il est recommandé d'utiliser la bibliothèque cliente Cloud Storage pour Python pour effectuer des opérations sur des buckets et des objets Cloud Storage. Les bibliothèques clientes Cloud Storage offrent davantage de flexibilité, et les exemples de code figurant dans les guides Cloud Storage les utilisent. Suivez ce tutoriel si vous souhaitez spécifiquement interagir avec Cloud Storage via l'API XML et la bibliothèque boto.

Configurer l'environnement

Avant de commencer ce tutoriel, vous devez effectuer les opérations suivantes :

  1. Installez une version autonome de gsutil sur votre ordinateur.
  2. Installez la bibliothèque boto et gcs-oauth2-boto-plugin.

    boto est une bibliothèque Python Open Source qui sert d'interface avec Cloud Storage. gcs-oauth2-boto-plugin est un plug-in d'authentification pour le framework du plug-in d'authentification boto. Il fournit des identifiants OAuth 2.0 qui peuvent être employés avec Cloud Storage.

    La configuration permettant d'utiliser la bibliothèque boto et le plug-in oauth2 dépend de votre système. Les exemples de configuration ci-dessous sont fournis à titre indicatif. Ces commandes installent pip, puis s'en servent pour installer d'autres packages. Les trois dernières commandes montrent comment tester l'importation des deux modules pour vérifier l'installation.

    Debian et 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 et 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. Configurez votre fichier de configuration boto pour utiliser OAuth2.0.

    Vous pouvez configurer votre fichier de configuration boto de façon à utiliser des identifiants de compte de service ou de compte utilisateur. En cas d'authentification au nom d'un service ou d'une application, privilégiez l'utilisation d'identifiants de compte de service. Pour authentifier des requêtes au nom d'un utilisateur spécifique (c'est-à-dire, une personne), privilégiez l'utilisation d'identifiants de compte utilisateur. Pour plus d'informations sur ces deux types d'identifiants, consultez la section Types d'identifiants acceptés.

    Comptes de service

    Pour utiliser des identifiants de compte de service :

    1. Utilisez un compte de service existant ou créez-en un, puis téléchargez la clé privée associée. Assurez-vous que la clé privée que vous obtenez est au format PKCS12. Par défaut, lorsque vous créez une clé, le format JSON de la clé privée est téléchargé.
    2. Configurez le fichier .boto avec le compte de service. Pour ce faire, vous pouvez faire appel à gsutil :
      gsutil config -e

      La commande vous invite à indiquer l'adresse e-mail du compte de service et l'emplacement de la clé privée du compte de service (.p12). Assurez-vous que la clé privée se trouve sur l'ordinateur sur lequel vous exécutez la commande gsutil.

    Comptes utilisateur

    Pour utiliser des identifiants de compte utilisateur :

    1. Si vous n'avez pas encore de fichier .boto, créez-en un. Pour ce faire, vous pouvez faire appel à gsutil.

      gsutil config
    2. Utilisez un ID client existant pour une application ou créez-en un.

    3. Modifiez le fichier .boto. Dans la section [OAuth2], spécifiez les valeurs client_id et client_secret avec celles que vous avez générées.

    4. Exécutez à nouveau la commande gsutil config pour générer un jeton d'actualisation basé sur l'ID client et le code secret que vous avez saisis.

      Si vous recevez un message d'erreur indiquant que le fichier .boto ne peut pas être sauvegardé, supprimez ou renommez le fichier de configuration de sauvegarde .boto.bak.

    5. Configurez la logique de secours du jeton d'actualisation.

      gcs-oauth2-boto-plugin requiert une logique de secours pour générer des jetons d'authentification lorsque vous utilisez des identifiants d'application. La logique de secours n'est pas nécessaire lorsque vous utilisez un compte de service.

      Vous disposez des options suivantes pour activer la logique de secours :

      1. Définissez les valeurs client_id et client_secret dans le fichier de configuration .boto. Il s'agit de l'option recommandée. Elle est requise pour pouvoir utiliser gsutil avec le nouveau fichier de configuration .boto.
      2. Définissez les variables d'environnement OAUTH2_CLIENT_ID et OAUTH2_CLIENT_SECRET.
      3. Utilisez la fonction SetFallbackClientIdAndSecret comme indiqué dans les exemples ci-dessous.

Utiliser Cloud Storage

Configurer votre fichier source Python

Pour démarrer ce tutoriel, créez un fichier Python à l'aide de l'éditeur de texte de votre choix. Ajoutez ensuite les directives, les instructions d'importation, la configuration et les affectations de constantes suivantes.

Notez que dans le code ci-dessous, nous utilisons la fonction SetFallbackClientIdAndSecret comme logique de secours pour générer des jetons d'actualisation. Pour connaître d'autres méthodes de spécification d'une logique de secours, consultez la section Utiliser des identifiants d'application. Si vous utilisez un compte de service pour l'authentification, vous n'avez pas besoin d'inclure la logique de secours.

#!/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)

Créer des buckets

Le code suivant crée deux buckets. Étant donné que les noms des buckets doivent être uniques (voir les consignes relatives à l'attribution de noms), un horodatage est ajouté à chaque nom afin d'en garantir l'unicité.

Si ces noms de buckets sont déjà utilisés, vous devrez modifier le code pour générer des noms uniques.

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

Répertorier les buckets

Pour récupérer la liste de tous les buckets, appelez storage_uri() pour instancier un objet BucketStorageUri, en spécifiant la chaîne vide en tant qu'URI. Appelez ensuite la méthode d'instance 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

Importer des objets

Pour importer des objets, créez un objet de fichier (ouvert pour lecture) qui pointe vers votre fichier local et un objet d'URI de stockage qui pointe vers l'objet de destination sur Cloud Storage. Appelez la méthode d'instance set_contents_from_file() en spécifiant le traitement du fichier comme argument.

# 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!

Répertorier les objets

Pour répertorier tous les objets d'un bucket, appelez storage_uri() et spécifiez l'URI du bucket et le schéma d'URI Cloud Storage en tant qu'arguments. Ensuite, récupérez une liste d'objets à l'aide de la méthode d'instance 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()

Télécharger et copier des objets

Le code suivant lit les objets dans DOGS_BUCKET, puis les copie dans votre répertoire d'accueil et dans CATS_BUCKET. Il montre également que vous pouvez utiliser la bibliothèque boto pour effectuer des opérations à la fois sur les fichiers locaux et sur les objets Cloud Storage avec la même interface.

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()

Transferts en streaming

Pour effectuer un transfert en streaming, utilisez le code suivant :

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

Par exemple, le code suivant effectue l'importation en streaming d'un fichier nommé data_file vers un objet portant le même nom :

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)

Pour effectuer un téléchargement en streaming, utilisez le code suivant :

import sys

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

Par exemple, le code suivant effectue le téléchargement en streaming d'un objet nommé 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)

Modifier des listes de contrôles d'accès (LCA) d'objets

Le code suivant accorde au compte Google spécifié les autorisations FULL_CONTROL pour labrador.txt. N'oubliez pas de remplacer valid-email-address par une adresse e-mail de compte Google valide.

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())

Lire des métadonnées d'objet et de bucket

Ce code récupère et imprime les métadonnées associées à un bucket et à un objet.

# 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

Supprimer des objets et des buckets

Pour conclure ce tutoriel, ce code supprime les objets et les buckets que vous avez créés. Pour pouvoir être supprimé, un bucket doit être vide. Par conséquent, ses objets sont d'abord supprimés.

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()

Haut de page

Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Besoin d'aide ? Consultez notre page d'assistance.