Utiliser les bibliothèques clientes Cloud pour Python

Ce document explique comment utiliser les bibliothèques clientes Cloud pour Python avec Compute Engine. Il décrit comment autoriser des requêtes et comment créer, répertorier et supprimer des instances. Cet exercice décrit comment utiliser la bibliothèque google-api-python-client pour accéder aux ressources Compute Engine. Vous pouvez exécuter cet exemple depuis votre ordinateur local ou sur une instance de VM, à condition d'avoir correctement autorisé l'exemple.

Pour obtenir la liste complète des bibliothèques clientes disponibles, y compris les autres bibliothèques clientes Google et les bibliothèques Open Source tierces, consultez la page sur les bibliothèques clientes.

Pour ignorer cet exercice et voir le code complet de l'exemple, consultez la page GoogleCloudPlatform/python-docs-samples sur GitHub.

Objectifs

  • Réaliser une autorisation OAuth 2.0 à l'aide de la bibliothèque oauth2client
  • Créer une instance à l'aide de la bibliothèque google-python-client
  • Répertorier les instances à l'aide de la bibliothèque google-python-client
  • Supprimer une instance à l'aide de la bibliothèque google-python-client

Coûts

Ce tutoriel utilise des composants facturables de Google Cloud Platform, y compris Compute Engine.

Les nouveaux utilisateurs de Google Cloud Platform peuvent bénéficier d'un essai gratuit.

Avant de commencer

  1. Connectez-vous à votre compte Google.

    Si vous n'en possédez pas déjà un, vous devez en créer un.

  2. Sélectionnez ou créez un projet Google Cloud Platform.

    Accéder à la page "Gérer les ressources"

  3. Assurez-vous que la facturation est activée pour votre projet Google Cloud Platform.

    Découvrir comment activer la facturation

  4. Installez le SDK Cloud.
  5. Une fois le SDK installé, exécutez gcloud auth application-default login.
  6. Installez la bibliothèque google-api-python-client. Vous pouvez par exemple exécuter la commande :
    $ pip install --upgrade google-api-python-client

    Pour en savoir plus sur l'installation de cette bibliothèque, consultez les instructions d'installation. Vous devez également disposer de Python 2.7 ou 3.3+ pour exécuter les bibliothèques clientes Cloud pour Python.

  7. Activez l'API Cloud Storage.
  8. Créez un bucket Cloud Storage et notez le nom du bucket. Vous en aurez besoin par la suite.

Autoriser les requêtes

Cet exemple utilise le protocole d'autorisation OAuth 2.0. Il existe de nombreuses manières d'autoriser des requêtes à l'aide de OAuth 2.0. Toutefois, dans le cadre de cet exemple, vous utiliserez les identifiants par défaut de l'application. Cela vous permet de réutiliser les identifiants de l'outil gcloud si vous exécutez l'exemple sur un poste de travail local, ou de réutiliser les identifiants d'un compte de service si vous exécutez l'exemple depuis Compute Engine ou App Engine. Vous devez avoir installé et autorisé l'outil gcloud à la section Avant de commencer.

Les identifiants par défaut de l'application sont fournis automatiquement dans les bibliothèques clientes de l'API Google. Il vous suffit de créer et d'initialiser l'API :

compute = googleapiclient.discovery.build('compute', 'v1')

Ainsi, l'extrait de code suivant représente la méthode principale de cet exemple. Elle génère et initialise l'API, puis effectue des appels pour créer, répertorier et supprimer une instance :

def main(project, bucket, zone, instance_name, wait=True):
    compute = googleapiclient.discovery.build('compute', 'v1')

    print('Creating instance.')

    operation = create_instance(compute, project, zone, instance_name, bucket)
    wait_for_operation(compute, project, zone, operation['name'])

    instances = list_instances(compute, project, zone)

    print('Instances in project %s and zone %s:' % (project, zone))
    for instance in instances:
        print(' - ' + instance['name'])

    print("""
Instance created.
It will take a minute or two for the instance to complete work.
Check this URL: http://storage.googleapis.com/{}/output.png
Once the image is uploaded press enter to delete the instance.
""".format(bucket))

    if wait:
        input()

    print('Deleting instance.')

    operation = delete_instance(compute, project, zone, instance_name)
    wait_for_operation(compute, project, zone, operation['name'])

if __name__ == '__main__':
    parser = argparse.ArgumentParser(
        description=__doc__,
        formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument('project_id', help='Your Google Cloud project ID.')
    parser.add_argument(
        'bucket_name', help='Your Google Cloud Storage bucket name.')
    parser.add_argument(
        '--zone',
        default='us-central1-f',
        help='Compute Engine zone to deploy to.')
    parser.add_argument(
        '--name', default='demo-instance', help='New instance name.')

    args = parser.parse_args()

    main(args.project_id, args.bucket_name, args.zone, args.name)

Répertorier les instances

La bibliothèque cliente Python vous permet de répertorier les instances grâce à la méthode compute.instances().list. Vous devez fournir l'ID du projet et la zone pour laquelle vous souhaitez répertorier les instances. Exemple :

def list_instances(compute, project, zone):
    result = compute.instances().list(project=project, zone=zone).execute()
    return result['items'] if 'items' in result else None

Ajouter une instance

Pour ajouter une instance, utilisez la méthode instances().insert et spécifiez les propriétés de la nouvelle instance. Ces propriétés sont indiquées dans le corps de la requête. Pour en savoir plus sur chaque propriété, consultez la documentation de référence de l'API pour instances.insert.

A minima, lorsque vous créez une instance, votre demande doit fournir des valeurs pour les propriétés suivantes :

  • Nom de l'instance
  • Disque persistant racine
  • Type de machine
  • Zone
  • Interfaces réseau

Cet exemple démarre une instance possédant les propriétés suivantes dans une zone de votre choix :

  • Type de machine : n1-standard-1
  • Disque persistant racine : un nouveau disque persistant basé sur la dernière image de Debian 8
  • Compte de service Compute Engine par défaut avec les champs d'application suivants :

    • https://www.googleapis.com/auth/devstorage.read_write, afin que l'instance puisse lire et écrire des fichiers dans Cloud Storage
    • https://www.googleapis.com/auth/logging.write, afin que les journaux d'instances puissent être importés dans Stackdriver Logging.
  • Métadonnées pour spécifier les commandes que l'instance doit exécuter au démarrage

def create_instance(compute, project, zone, name, bucket):
    # Get the latest Debian Jessie image.
    image_response = compute.images().getFromFamily(
        project='debian-cloud', family='debian-9').execute()
    source_disk_image = image_response['selfLink']

    # Configure the machine
    machine_type = "zones/%s/machineTypes/n1-standard-1" % zone
    startup_script = open(
        os.path.join(
            os.path.dirname(__file__), 'startup-script.sh'), 'r').read()
    image_url = "http://storage.googleapis.com/gce-demo-input/photo.jpg"
    image_caption = "Ready for dessert?"

    config = {
        'name': name,
        'machineType': machine_type,

        # Specify the boot disk and the image to use as a source.
        'disks': [
            {
                'boot': True,
                'autoDelete': True,
                'initializeParams': {
                    'sourceImage': source_disk_image,
                }
            }
        ],

        # Specify a network interface with NAT to access the public
        # internet.
        'networkInterfaces': [{
            'network': 'global/networks/default',
            'accessConfigs': [
                {'type': 'ONE_TO_ONE_NAT', 'name': 'External NAT'}
            ]
        }],

        # Allow the instance to access cloud storage and logging.
        'serviceAccounts': [{
            'email': 'default',
            'scopes': [
                'https://www.googleapis.com/auth/devstorage.read_write',
                'https://www.googleapis.com/auth/logging.write'
            ]
        }],

        # Metadata is readable from the instance and allows you to
        # pass configuration from deployment scripts to instances.
        'metadata': {
            'items': [{
                # Startup script is automatically executed by the
                # instance upon startup.
                'key': 'startup-script',
                'value': startup_script
            }, {
                'key': 'url',
                'value': image_url
            }, {
                'key': 'text',
                'value': image_caption
            }, {
                'key': 'bucket',
                'value': bucket
            }]
        }
    }

    return compute.instances().insert(
        project=project,
        zone=zone,
        body=config).execute()

Les sections suivantes décrivent les paramètres de création de l'instance.

Disques persistants racines

Toutes les instances doivent démarrer à partir d'un disque persistant racine. Le disque persistant racine contient tous les fichiers nécessaires au démarrage d'une instance. Lorsque vous créez un disque persistant racine, vous devez spécifier l'image de l'OS source devant s'appliquer au disque. Dans l'exemple ci-dessus, vous avez créé, en même temps que l'instance, un nouveau disque persistant racine basé sur Debian 8. Toutefois, il est également possible de créer un disque préalablement, puis de l'associer à l'instance.

Métadonnées de l'instance

Lorsque vous créez une instance, vous pouvez inclure des métadonnées d'instance telles qu'un script de démarrage, des variables de configuration et des clés SSH. Dans l'exemple ci-dessus, vous avez utilisé le champ metadata dans le corps de la requête afin de spécifier un script de démarrage pour l'instance, ainsi que certaines variables de configuration sous forme de paires clé/valeur. Le script de démarrage, disponible ci-dessous, montre comment lire ces variables et les utiliser pour insérer du texte dans une image, puis transférer celle-ci vers Cloud Storage.

apt-get update
apt-get -y install imagemagick

# Use the metadata server to get the configuration specified during
# instance creation. Read more about metadata here:
# https://cloud.google.com/compute/docs/metadata#querying
IMAGE_URL=$(curl http://metadata/computeMetadata/v1/instance/attributes/url -H "Metadata-Flavor: Google")
TEXT=$(curl http://metadata/computeMetadata/v1/instance/attributes/text -H "Metadata-Flavor: Google")
CS_BUCKET=$(curl http://metadata/computeMetadata/v1/instance/attributes/bucket -H "Metadata-Flavor: Google")

mkdir image-output
cd image-output
wget $IMAGE_URL
convert * -pointsize 30 -fill white -stroke black -gravity center -annotate +10+40 "$TEXT" output.png

# Create a Google Cloud Storage bucket.
gsutil mb gs://$CS_BUCKET

# Store the image in the Google Cloud Storage bucket and allow all users
# to read it.
gsutil cp -a public-read output.png gs://$CS_BUCKET/output.png

Supprimer une instance

Pour supprimer une instance, vous devez appeler la méthode instances().delete et renseigner le nom, la zone et l'ID du projet correspondant à l'instance à supprimer. Comme vous avez défini le paramètre autoDelete pour le disque de démarrage, celui-ci est supprimé en même temps que l'instance. Ce paramètre est désactivé par défaut, mais il est utile lorsque votre cas d'utilisation nécessite de supprimer simultanément les disques et les instances.

def delete_instance(compute, project, zone, name):
    return compute.instances().delete(
        project=project,
        zone=zone,
        instance=name).execute()

Exécuter l'exemple

Vous pouvez exécuter l'exemple complet en téléchargeant le code et en l'exécutant en ligne de commande. Veillez à télécharger le fichier create_instance.py ainsi que le fichier startup-script.sh. Pour exécuter l'exemple, saisissez la commande suivante :

python create_instance.py --name [INSTANCE_NAME] --zone [ZONE] [PROJECT_ID] [CLOUD_STORAGE_BUCKET]

où :

  • [INSTANCE_NAME] est le nom de l'instance à créer ;
  • [ZONE] est la zone souhaitée pour cette requête ;
  • [PROJECT_ID] est l'identifiant de notre projet ;
  • [CLOUD_STORAGE_BUCKET] est le nom du bucket que vous avez initialement configuré, mais sans le préfixe gs://.

Exemple :

python python-example.py --name example-instance --zone us-central1-a example-project my-gcs-bucket

Attendre la fin des opérations

Les requêtes adressées à l'API Compute Engine visant à modifier des ressources telles que des instances renvoient immédiatement une réponse accusant réception de la requête. L'accusé de réception vous permet de vérifier l'état de l'opération demandée. Les opérations peuvent prendre quelques minutes. Il est donc souvent plus facile d'attendre que l'opération se termine avant de continuer. Cette méthode d'assistance attend la fin de l'opération avant de renvoyer les lignes suivantes :

def wait_for_operation(compute, project, zone, operation):
    print('Waiting for operation to finish...')
    while True:
        result = compute.zoneOperations().get(
            project=project,
            zone=zone,
            operation=operation).execute()

        if result['status'] == 'DONE':
            print("done.")
            if 'error' in result:
                raise Exception(result['error'])
            return result

        time.sleep(1)

Nettoyer

Afin d'éviter que des frais ne soient facturés sur votre compte Google Cloud Platform pour les ressources utilisées dans ce tutoriel, procédez comme suit :

Supprimer votre bucket Cloud Storage

Pour supprimer un bucket Cloud Storage, procédez comme suit :

  1. Dans la console GCP, accédez au navigateur Cloud Storage.

    Accéder au navigateur Cloud Storage

  2. Cochez la case à côté du bucket que vous souhaitez supprimer.
  3. Cliquez sur le bouton Supprimer delete situé en haut de la page pour supprimer le bucket.

Étapes suivantes

  • Téléchargez et consultez l'exemple de code complet. Il comprend une courte illustration de l'utilisation conjointe de toutes ces méthodes. N'hésitez pas à le télécharger, à le modifier et à l'exécuter selon vos besoins.
  • Consultez la documentation de référence sur l'API pour découvrir comment réaliser d'autres tâches avec l'API.
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Compute Engine