Utiliser la bibliothèque cliente Python

Ce document montre comment utiliser la bibliothèque cliente Python de Google pour Google Compute Engine. Il décrit comment autoriser des requêtes et comment créer, répertorier et supprimer des instances. Cet exercice explique comment utiliser la bibliothèque google-api-python-client pour accéder aux ressources Google 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.

Une liste complète des bibliothèques clientes disponibles, notamment les autres bibliothèques clientes Google et les bibliothèques Open Source tierces, est disponible à la page 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 Cloud Platform, tels que Compute Engine.

Les nouveaux utilisateurs de 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 la commande 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 plus d'informations 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 la bibliothèque cliente Python de Google.

  7. Activez l'API Google Cloud Storage.
  8. Créez un bucket de stockage et notez le nom du bucket. Nous en aurons besoin par la suite.

Autoriser des 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, mais dans le cadre de cet exemple, vous utiliserez les identifiants par défaut de l’application. Cela vous permet soit de réutiliser les identifiants de l'outil gcloud si vous exécutez l'exemple sur un poste de travail local, soit 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 devrez 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 renseigné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, qui permet à l'instance de lire et d'écrire des fichiers dans Google Cloud Storage
    • https://www.googleapis.com/auth/logging.write, qui vous permet d'importer des journaux d'instances dans Google Cloud 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 votre instance, vous pouvez souhaiter inclure des métadonnées d'instance telles qu'un script de démarrage, des variables de configuration et des clés ssh. Dans le corps de votre requête de l'exemple ci-dessus, vous avez utilisé le champ metadata pour 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 Google 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 sera 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 :

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 Google Compute Engine visant à modifier des ressources telles que des instances renvoient immédiatement une réponse confirmant la requête. Cette confirmation vous permettra 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 auxiliaire attend que l'opération se termine avant de rendre la main :

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)

Effectuer un nettoyage

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 :

  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 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.
  • Commencez à créer vos propres applications !
Cette page vous a-t-elle été utile ? Évaluez-la :

Envoyer des commentaires concernant…

Documentation Compute Engine