1. Utiliser les API Google Workspace
Cet atelier de programmation vous présente l'utilisation des API RESTful basées sur HTTP de Google Workspace (anciennement G Suite). L'exemple sera donné en Python pour des raisons de concision et de disponibilité, mais vous pouvez également choisir d'utiliser votre langage de développement préféré. Vous découvrirez des sujets d'introduction, comme l'utilisation de la console pour les développeurs afin de créer et de gérer des projets, l'obtention d'identifiants d'autorisation et l'installation des bibliothèques clientes de l'API. Une fois les formalités remplies, vous allez écrire une application pour afficher les 100 premiers fichiers et dossiers de votre Google Drive à l'aide de son API.
Points abordés
- Créer un projet à l'aide de la console Google/Cloud Developers
- Obtenir et utiliser des identifiants d'application OAuth2 dans votre application
- En savoir plus sur l'utilisation des bibliothèques clientes des API Google
- Écrire des applications à l'aide des API Google et Google Workspace
- Obtenir des informations sur les fichiers et les dossiers avec l'API Google Drive
Prérequis
- Accès à Internet et à un navigateur Web
- Un compte Google (l'approbation de l'administrateur peut être nécessaire pour les comptes Google Workspace)
- Connaissance des systèmes compatibles POSIX tels que Linux et Mac OS X
- Vous devez pouvoir créer des fichiers sources à l'aide d'un éditeur de code ou de commandes shell.
- Des connaissances de base en Python (version 2 ou 3), mais vous pouvez utiliser n'importe quel langage compatible
- Certains fichiers et/ou dossiers de votre Google Drive
2. Enquête
Comment allez-vous utiliser ce tutoriel de programmation ?
Quel est votre niveau d'expérience avec les outils et API pour les développeurs Google Workspace ?
3. Présentation
Dans cet atelier de programmation, vous allez apprendre à :
- Télécharger la bibliothèque cliente des API Google pour Python
- Créez un projet dans la console Google/Cloud Developers.
- Obtenir les identifiants nécessaires pour votre application
- Utilisez ces identifiants pour accéder à l'API Google Drive.
Si vous préférez ne pas utiliser Python, n'hésitez pas à implémenter l'atelier de programmation dans votre outil de développement favori (les bibliothèques clientes des langages compatibles sont disponibles ici) et à vous référer simplement aux exemples Python en tant que pseudo-code (exécutable).
4. Confirmer l'environnement Python
Cet atelier de programmation requiert l'utilisation du langage Python. Toutefois, les bibliothèques clientes des API Google sont compatibles avec un grand nombre de langages : n'hésitez donc pas à créer un équivalent dans votre outil de développement favori et à utiliser Python simplement sous forme de pseudo-code. En particulier, cet atelier de programmation est compatible avec Python 2 et 3, mais nous vous recommandons de passer à la version 3.x dès que possible.
Cloud Shell est un outil pratique que les utilisateurs peuvent exploiter directement depuis la console Cloud. Il ne nécessite pas d'environnement de développement local. Vous pouvez donc suivre ce tutoriel entièrement dans le cloud avec un navigateur Web. Cloud Shell est particulièrement utile si vous développez ou envisagez de continuer à développer en utilisant des produits et des API GCP. En particulier, pour cet atelier de programmation, Cloud Shell contient déjà les deux versions de Python pré-installées.
Cloud Shell inclut également IPython. Il s'agit d'un interpréteur Python interactif de haut niveau que nous recommandons, en particulier si vous faites partie de la communauté des data scientists ou du machine learning. Si tel est le cas, IPython est l'interpréteur par défaut pour les notebooks Jupyter et pour Colab, la collection de notebooks Jupyter hébergée par Google Research.
IPython privilégie un interpréteur Python 3, mais passe à Python 2 s'il n'y a pas de version 3.x disponible. IPython est accessible depuis Cloud Shell, mais il peut également être installé dans un environnement de développement local. Pour quitter, utiliser la combinaison de touches "^D" (Ctrl+D), puis acceptez l'invite. Les lignes ci-dessous représentent un exemple de la sortie affichée au démarrage de ipython :
$ ipython Python 3.7.3 (default, Mar 4 2020, 23:11:43) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
Si IPython n'est pas l'interpréteur de votre choix, il est tout à fait acceptable d'utiliser un interpréteur interactif Python standard (que ce soit dans Cloud Shell dans votre environnement de développement local). Vous le quittez de la même manière avec ^D :
$ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> $ python3 Python 3.7.3 (default, Mar 10 2020, 02:33:39) [GCC 6.3.0 20170516] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
L'atelier de programmation part également du principe que vous disposez de l'outil d'installation pip (gestionnaire de packages Python et résolveur de dépendances). Il est fourni avec les versions 2.7.9 et ultérieures, ou 3.4 et ultérieures. Si vous possédez une version de Python plus ancienne, consultez ce guide pour savoir comment l'installer. Selon vos autorisations, vous aurez peut-être besoin d'un accès sudo ou super-utilisateur, mais ce n'est généralement pas le cas. Vous pouvez également utiliser explicitement pip2 ou pip3 afin d'exécuter pip pour des versions spécifiques de Python.
Le reste de l'atelier de programmation suppose que vous utilisez Python 3. Des instructions spécifiques seront fournies pour Python 2 si elles diffèrent de la version 3.x de manière significative.
*Créer et utiliser des environnements virtuels
Cette section est facultative et n'est obligatoire que pour les utilisateurs devant utiliser un environnement virtuel pour cet atelier de programmation (conformément à l'avertissement ci-dessus). Si vous avez installé uniquement Python 3 sur votre ordinateur, vous pouvez simplement exécuter cette commande pour créer un environnement virtuel nommé my_env (vous pouvez choisir un autre nom si vous le souhaitez) :
virtualenv my_env
Toutefois, si Python 2 et 3 sont tous les deux installés sur votre ordinateur, nous vous recommandons d'installer un environnement virtuel Python 3, ce que vous pouvez faire à l'aide de l'option -p flag comme suit :
virtualenv -p python3 my_env
"Entrez" dans l'environnement virtuel que vous venez de créer en l'activant comme suit :
source my_env/bin/activate
Vérifiez que vous vous trouvez bien dans l'environnement en observant votre invite d'interface système, qui doit maintenant être précédée du nom de votre environnement, par exemple :
(my_env) $
Vous devriez maintenant pouvoir installer tous les packages requis à l'aide de la commande pip install, exécuter du code dans cet environnement, etc. Un autre avantage est que, si vous déréglez votre environnement, que vous parvenez à une situation dans laquelle votre installation Python est corrompue, ou autre problème majeur, vous pouvez simplement supprimer l'intégralité de cet environnement sans affecter le reste de votre système.
5. Installer la bibliothèque cliente des API Google pour Python
Cet atelier de programmation requiert l'utilisation de la bibliothèque cliente des API Google pour Python. Il s'agit donc d'un processus d'installation simple, voire qui ne requiert aucune action de votre part.
Un peu plus tôt, nous vous avons recommandé d'utiliser Cloud Shell pour plus de commodité. Vous pouvez suivre l'intégralité de ce tutoriel à partir d'un navigateur Web dans le cloud. Autre avantage de Cloud Shell : de nombreux outils de développement et bibliothèques nécessaires sont déjà préinstallés.
*Installer les bibliothèques clientes
(Facultatif) Vous pouvez ignorer cette étape si vous utilisez Cloud Shell ou un environnement local dans lequel vous avez déjà installé les bibliothèques clientes. Vous ne devez effectuer cette opération que si vous développez en local et que les bibliothèques ne sont pas installées (ou si vous n'en êtes pas certain). Le moyen le plus simple consiste à utiliser pip (ou pip3) pour effectuer l'installation (y compris mettre à jour pip si nécessaire) :
pip install -U pip google-api-python-client oauth2client
Confirmer l'installation
Cette commande installe la bibliothèque cliente, ainsi que tous les packages dont elle dépend. Que vous utilisiez Cloud Shell ou votre propre environnement, vérifiez que la bibliothèque cliente est installée en important les packages nécessaires et en confirmant qu'il n'y a aucune erreur d'importation (ou sortie affichée) :
python3 -c "import googleapiclient, httplib2, oauth2client"
Si vous utilisez Python 2 (à partir de Cloud Shell), vous recevrez un avertissement indiquant que sa compatibilité est obsolète :
******************************************************************************* Python 2 is deprecated. Upgrade to Python 3 as soon as possible. See https://cloud.google.com/python/docs/python2-sunset To suppress this warning, create an empty ~/.cloudshell/no-python-warning file. The command will automatically proceed in seconds or on any key. *******************************************************************************
Dès lors que vous pouvez exécuter cette commande d'importation de test (sans erreur ni sortie), vous êtes prêt à communiquer avec les API Google.
Résumé
Comme il s'agit d'un atelier de programmation d'introduction, nous partons du principe que vous n'avez jamais utilisé les API Google et Google Workspace. Si vous avez déjà créé des projets et des "ID client OAuth" pour l'autorisation des utilisateurs. Si c'est le cas, créez ou réutilisez un projet existant, créez ou réutilisez un ID client OAuth existant, puis passez les deux modules suivants et accédez directement à "Afficher votre application de fichiers et dossiers Drive" ou à "Utilisation avancée de la console de développement" pour examiner ces étapes avec moins d'aide.
6. Spécifier un projet dans la console Cloud
Une application utilisant les API Google nécessite un projet. Elles sont gérées dans la console Google Cloud pour les développeurs, ou simplement "console pour les développeurs". Dans cet atelier de programmation, nous n'utiliserons que l'API Google Drive. Nous avons donc un lien magique (ci-dessous à l'étape 1) qui :
- Vous redirige vers la console Dev
- vous guide pour créer un projet (ou en choisir un existant) ;
- Active automatiquement l'API Drive
C'est parti !
- Accédez à console.developers.google.com/start/api?id=drive et connectez-vous à votre compte Google.
- Si vous n'avez pas encore de projets, cet écran s'affiche pour vous permettre d'accepter les Conditions d'utilisation des API Google :
Une fois que vous avez accepté les conditions d'utilisation, un projet nommé Mon projet est créé et l'API Drive est automatiquement activée. 3. Si vous avez déjà créé un projet (peut-être lors d'un atelier de programmation précédent), l'écran suivant s'affiche : 
Lorsque vous cliquez sur le menu déroulant Créer un projet, sélectionnez un projet existant ou créez-en un. 
Une fois votre sélection effectuée (nouveau projet ou projet existant), l'API Drive sera automatiquement activée pour vous. 4. Vous saurez que l'API Drive a été activée grâce à cette confirmation : 
5. Cliquez sur Passer à l'étape "Identifiants" pour passer à l'étape suivante.
7. *Autoriser les requêtes API (autorisation utilisateur)
Vous pouvez ignorer cette section si vous avez déjà créé des identifiants d'autorisation via un compte utilisateur et que vous connaissez le processus. Cela diffère de l'autorisation via un compte de service, qui utilise une technique distincte. Veuillez continuer ci-dessous.
Présentation de l'autorisation (et quelques éléments concernant l'authentification)
Pour pouvoir envoyer des requêtes aux API, votre application doit disposer d'une autorisation appropriée. L'authentification, qui est un terme similaire, décrit les identifiants de connexion. Vous vous authentifiez lorsque vous vous connectez à votre compte Google à l'aide d'un identifiant et d'un mot de passe. Une fois authentifié, l'étape suivante consiste à vérifier si vous, ou plus exactement votre code, êtes autorisé à accéder à des données, telles que des fichiers blob sur Cloud Storage ou les fichiers personnels d'un utilisateur sur Google Drive.
Les API Google sont compatibles avec plusieurs types d'autorisation, mais le plus courant pour les utilisateurs de l'API Google Workspace est l'autorisation des utilisateurs. En effet, l'exemple d'application de cet atelier de programmation accède aux données des utilisateurs finaux. Ces utilisateurs finaux doivent autoriser votre application à accéder à leurs données. Cela signifie que votre code doit obtenir les identifiants OAuth2 du compte utilisateur.
Pour obtenir des identifiants OAuth2 pour l'autorisation des utilisateurs, revenez au gestionnaire d'API, puis sélectionnez l'onglet "Identifiants" (Credentials) dans le menu de navigation de gauche :
Une fois sur cet écran, vous verrez tous vos identifiants s'afficher dans trois sections distinctes :
La première concerne les clés API, la deuxième les ID client OAuth 2.0, et la dernière concerne les comptes de service OAuth2. Celle que nous utilisons est la deuxième section.
Créer des identifiants
Sur la page "Identifiants", cliquez sur le bouton + Créer des identifiants (Create Credentials) qui se trouve en haut. Une boîte de dialogue s'affiche alors, dans laquelle vous devez choisir "ID client OAuth".
Sur l'écran suivant, vous avez deux actions à effectuer : configurer l'écran d'autorisation de votre application et choisir le type d'application :
Si vous n'avez pas configuré d'écran d'autorisation, un avertissement s'affiche dans la console et vous devez configurer l'écran d'autorisation dès maintenant. (Ignorez ces étapes si votre écran d'autorisation a déjà été configuré).
Écran de consentement OAuth
Cliquez sur "Configurer l'écran d'autorisation" (Configure consent screen), et vous devez alors sélectionner une application "Externe" (External) ou "Interne" (Internal) si vous êtes un client Google Workspace (anciennement "G Suite") :
Notez que, dans le cadre de cet exercice, ce choix n'a pas d'importance, car vous n'allez pas publier votre exemple d'application de l'atelier de programmation. La plupart des utilisateurs sélectionnent "Externe" pour accéder à un écran plus complexe, mais il vous suffit de remplir le champ "Nom de l'application" (Application name) en haut :
Pour le moment, il vous suffit d'indiquer un nom d'application. Choisissez donc un nom qui reflète l'atelier de programmation que vous êtes en train de suivre, puis cliquer sur Enregistrer (Save).
Création de l'ID client OAuth (authentification par compte utilisateur)
Revenez maintenant à l'onglet "Identifiants" (Credentials) pour créer un ID client OAuth2. Voici différents ID client OAuth que vous pouvez créer :
Nous développons un outil de ligne de commande de type Autre (Other). Sélectionnez donc cette option, puis cliquez sur le bouton Créer (Create). Choisissez un nom d'ID client qui reflète l'application que vous créez, ou conservez simplement le nom par défaut, qui est généralement : "Autre client N" (Other Client N).
Enregistrer vos identifiants
- Une boîte de dialogue contenant les nouveaux identifiants s'affiche. cliquez sur OK pour la fermer.
- Revenez à la page "Identifiants" (Credentials), faites défiler la page jusqu'à la section "ID client OAuth2" (OAuth2 Client IDs), puis cliquez sur l'icône de téléchargement
située à l'extrême droite de l'ID client que vous venez de créer.
- Cette action ouvre une boîte de dialogue permettant d'enregistrer un fichier nommé
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, probablement dans votre dossier Téléchargements. Nous vous recommandons de raccourcir ce nom vers quelque chose de plus simple, par exempleclient_secret.json(qui est le nom utilisé par l'application d'exemple), puis de l'enregistrer dans le répertoire/dossier où vous allez créer l'exemple d'application dans le cadre de cet atelier de programmation.
Résumé
Maintenant que vous avez les identifiants, vous êtes prêt à accéder à l'API Drive depuis votre application. N'oubliez pas que l'ID client OAuth permet à vos utilisateurs d'accorder à votre application l'autorisation d'accéder à leurs données dans Google Drive.
NOTE : Vous trouverez plus d'informations sur la création de projets, l'activation d'API et l'obtention d'identifiants manuellement, c'est-à-dire sans utiliser l'assistant ci-dessus, à la fin de cet atelier de programmation pour approfondir vos connaissances.
8. Afficher l'application Fichiers et dossiers Drive
Que ce soit dans votre environnement de développement local ou dans Cloud Shell, dans le même répertoire où se trouve votre fichier d'identifiants client_id.json, créez un fichier Python nommé drive_list.py et ajoutez les lignes de code ci-dessous :
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
Structure de l'application
Cette application comporte trois sections principales :
- Importations Python pour intégrer les fonctionnalités de la bibliothèque
- Obtenir des identifiants d'application
- Récupérer et afficher les noms de fichiers et de dossiers, ainsi que les types MIME dans le Google Drive de l'utilisateur
NOTE : Une explication détaillée du code, ligne par ligne, sera disponible à la fin de cet atelier de programmation pour vous permettre d'approfondir vos connaissances.
Exécuter l'application
Nommez ce fichier, par exemple drive_list.py. La première fois que vous allez exécuter ce script, il ne sera pas autorisé à accéder aux fichiers de l'utilisateur (vous) sur Drive. Le résultat se présente comme suit, avec l'exécution mise en pause :
$ python3 ./drive_list.py /usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Your browser has been opened to visit: https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Depuis l'environnement de développement local
Le script de ligne de commande est mis en pause tandis qu'une fenêtre de navigateur s'ouvre et affiche la boîte de dialogue des autorisations OAuth2 :
C'est là que l'application demande à l'utilisateur les autorisations requises par le code (via la variable SCOPES). Dans ce cas, il est demandé d'autoriser l'application à consulter les métadonnées des fichiers du stockage Google Drive de l'utilisateur. Oui, dans votre code, ces niveaux d'accès apparaissent sous forme d'URI, mais ils sont traduits dans la langue spécifiée par vos paramètres régionaux dans la fenêtre de dialogue du flux OAuth2. L'utilisateur doit explicitement accorder son autorisation pour les autorisations demandées. Sinon, la partie "run flow" du code lèvera une exception et le script ne poursuivra pas le processus.
NOTE : Certains utilisateurs ont plusieurs navigateurs. Il est possible que la demande d'autorisation s'affiche dans un navigateur non préféré. Si c'est le cas, il vous suffit de copier l'intégralité de l'URL de la fenêtre de navigateur que vous ne souhaitez pas utiliser et de la coller dans la barre d'adresse d'un navigateur que vous souhaitez utiliser.
Depuis Cloud Shell
Si vous n'avez pas fait attention et que vous avez exécuté le programme dans Cloud Shell, aucune fenêtre de navigateur ne s'est ouverte et vous êtes bloqué. Notez alors que le message de diagnostic figurant en bas (et copié ci-dessous) vous était destiné :
If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Lorsque vous exécutez la commande de cette manière, vous obtenez le résultat suivant :
$ python3 drive_list.py --noauth_local_webserver /usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Go to the following link in your browser: https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code Enter verification code:
Si vous suivez les instructions et accédez à un autre onglet du navigateur avec cette URL, vous bénéficierez d'une expérience presque identique à celle décrite ci-dessus pour les environnements de développement locaux. La principale différence se situe à la fin du processus, où un écran supplémentaire s'affiche avec le code de validation à saisir dans Cloud Shell :
Coupez et collez ce code dans la fenêtre de terminal.
Résumé
Une fois que l'utilisateur a cliqué sur "Autoriser" et/ou que le code de validation a été collé dans l'invite, l'application (continue de) s'exécuter. Vous devriez donc voir un résultat composé de fichiers/dossiers Drive et de leurs types MIME. Voici un exemple tiré de l'un de nos comptes de test :
$ python3 ./drive_list.py Travel expenses application/vnd.google-apps.spreadsheet Gmail Add-ons codelab application/vnd.google-apps.script Google Workspace Developer Intro application/vnd.google-apps.presentation Baseball Sheets application/vnd.google-apps.folder My Resume application/vnd.google-apps.document . . .
Notez que lors des exécutions successives, vous n'êtes plus invité à autoriser l'accès (car il a été mis en cache par les bibliothèques d'authentification) et que vous passez directement à la sortie. N'est-ce pas excitant de voir vos documents dans un terminal pour la première fois ? Nous le pensons aussi !
9. Conclusion
Vous êtes maintenant prêt à découvrir d'autres fonctionnalités concernant l'API Drive ou à explorer d'autres API Google Workspace (Gmail, Google Docs, Sheets, Slides, Agenda) et Google (Maps, Analytics, YouTube, etc.). Félicitations pour être arrivé jusqu'au bout !
Le code figurant dans cet atelier de programmation est également accessible dans son dépôt GitHub à l'adresse github.com/googlecodelabs/gsuite-apis-intro. (Nous nous efforçons d'assurer la synchronisation de cet atelier de programmation avec le dépôt.) Vous êtes prêt à continuer ? Vous trouverez ci-dessous diverses ressources pouvant vous aider à explorer plus en détail les aspects abordés dans cet atelier de programmation, ou à élargir vos horizons et à découvrir d'autres moyens d'accéder aux technologies Google de manière programmatique.
Comme nous l'avons indiqué précédemment, si vous n'êtes pas un développeur Python régulier, nous vous invitons à refaire cet exemple d'atelier de programmation dans votre langage de développement préféré. Les bibliothèques clientes pour les langages compatibles sont disponibles ici.
Approfondir
Maintenant que vous avez acquis de l'expérience avec l'API Drive, voici quelques exercices recommandés pour développer vos compétences :
- Fichiers ZIP : écrivez une application qui sauvegarde plusieurs archives ZIP dans Drive, en les décompressant à la volée afin que chaque nom de fichier ZIP corresponde au nom du dossier dans lequel ces fichiers sont placés. BONUS : gérez les archives ZIP récursives dans d'autres fichiers ZIP avec des dossiers Drive imbriqués dans d'autres dossiers. Si vous abandonnez, consultez cet exemple d'application Node.js.
- Albums photo : écris le début d'un outil de génération d'albums photo qui importe plusieurs images dans Google Drive et les organise dans des dossiers distincts par code temporel et géolocalisation. BONUS : trouvez une bibliothèque de manipulation d'images Open Source et assemblez toutes les photos de chaque dossier pour représenter les événements que vous avez pu vivre (un voyage, un dîner, etc.).
- Explorer GCP : écrivez une application qui connecte Google Workspace et Google Cloud Platform (GCP). Écrivez un outil qui sauvegarde les fichiers image de Google Drive vers Google Cloud Storage (GCS), une autre solution de stockage de fichiers dans le cloud. Croyez-le ou non, l'utilisation de GCS sera plus simple que celle de Drive grâce à ses bibliothèques clientes avancées.
- Analyser et enregistrer : étendez votre solution à l'étape 3 en analysant chaque image sauvegardée. Pour ce faire, transmettez-la à l'API Google Cloud Vision et obtenez les principaux libellés (3, 5 ou 10) de ce que l'API voit dans ces images. Pour chaque image, écrivez une ligne dans une feuille de calcul Google Sheets contenant l'analyse de Cloud Vision ainsi que son emplacement de sauvegarde sur GCS. Si vous abandonnez, consultez cet atelier de programmation Python.
10. Autres ressources
Documentation
- Documentation de l'API Google Drive (API REST et SDK/API natifs Android)
- Documentation sur les autres API Google Workspace
- Documentation sur les autres API Google
- Bibliothèques clientes des API Google
- Documentation OAuth2
Vidéos similaires et générales
- Créer des projets d'API Google ( article de blog et vidéo)
- Examen du code passe-partout d'autorisation Python ( vidéo)
- Lister vos fichiers dans Google Drive ( vidéo, article de blog)
- Bibliothèque de vidéos sur l'API Google Drive
- Série de vidéos Launchpad Online
- Série de vidéos Google Workspace Dev Show
Informations et actualités
- Blog des développeurs Google Workspace
- Twitter des développeurs Google Workspace (@GSuiteDevs)
- Newsletter mensuelle des développeurs Google Workspace
Autres ateliers de programmation
Introduction
- [Apps Script] Présentation de Google Apps Script
Intermédiaire
- [Apps Script] Outil de ligne de commande CLASP Apps Script
- [Apps Script] Modules complémentaires Gmail
- [Apps Script] Module complémentaire Docs et API Natural Language de GCP
- [Apps Script] Framework de bot Hangouts Chat
- [API REST] Outil de création de rapports personnalisés (API Sheets)
- [API REST] Générateur de diapositives personnalisées pour l'analyseur BigQuery de licence GitHub (API Slides et BigQuery)
Avancé
- [API REST] Workflow de traitement des images dans le cloud (API Drive, Cloud Storage, Cloud Vision, Sheets)
Applications de référence
- Convertisseur Markdown vers Google Slides (API REST Slides)
11. *Explication détaillée de l'application
Cette section facultative est à utiliser pour l'autoformation après la fin de la session, afin de combler les éventuelles lacunes ou pour approfondir vos recherches.
Importations Python pour intégrer les fonctionnalités de la bibliothèque
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- La première instruction
importpermet à ce code de s'exécuter sur Python 2. Vous pouvez la supprimer complètement si vous n'utilisez que Python 3. - L'une des consignes de style Python consiste à séparer les importations de la bibliothèque standard et des modules tiers. C'est à cela que sert la ligne vide.
- Les trois importations suivantes apportent les classes et fonctions nécessaires de la bibliothèque cliente des API Google. Elles sont toutes nécessaires pour écrire cette application. Voici ce qu'elles font en bref :
googleapiclientse concentre sur la connexion aux API Google.httplib2fournit un client HTTP que l'application peut utiliser.oauth2clientnous aide à gérer les identifiants OAuth2.
Autorisation et obtention des identifiants de l'application
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
- Les autorisations d'application
SCOPESsont celles qu'une application demandera à l'utilisateur qui l'exécute. Pour protéger les données utilisateur, les applications ne peuvent pas s'exécuter sans autorisation. - Il est recommandé d'utiliser les autorisations les plus restrictives dont votre application a besoin pour fonctionner. Pourquoi ?
- N'est-ce pas ennuyeux lorsqu'une application demande un grand nombre d'autorisations lorsque vous l'installez ou l'exécutez ? Devinez quoi ? Vous êtes maintenant de l'autre côté de la pièce, en demandant à vos utilisateurs toutes ces autorisations. En utilisant des niveaux d'accès plus restrictifs, vous rassurez les utilisateurs qui sont plus enclins à installer votre application, car vous demandez moins d'accès.
- La plupart des champs d'application ressemblent à de longues URL, et le champ d'application des métadonnées Drive ne fait pas exception.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- Un jeton est nécessaire pour que les applications puissent communiquer avec les serveurs Google. Les jetons valides renvoyés par Google seront enregistrés dans le fichier de stockage des jetons,
storage.json. Si vous n'enregistrez pas ces jetons, vous devrez réautoriser votre application chaque fois que vous l'exécuterez.
store = file.Storage('storage.json')
- Cette application vérifie d'abord si nous disposons déjà d'identifiants valides dans le stockage (voir l'instruction conditionnelle
if).
creds = store.get()
if not creds or creds.invalid:
- Si vous n'avez pas d'identifiants ou s'ils ont expiré, vous devez créer un nouveau flux d'autorisation [via
oauth2client.client.flow_from_clientsecrets()] à partir de l'ID client et du code secret OAuth dans le fichierclient_id.jsonque vous avez téléchargé.
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
- Une fois que votre application dispose d'un flux, elle doit l'exécuter pour présenter à l'utilisateur l'écran des autorisations OAuth2 [via
oauth2client.tools.run_flow()] décrit et illustré ci-dessus.
creds = tools.run_flow(flow, store)
- En cliquant sur Autoriser, les utilisateurs autorisent votre application à accéder aux métadonnées de leurs fichiers Google Drive, et les serveurs Google renvoient des jetons pour accéder à l'API. Ils sont renvoyés sous la forme
credset mis en cache dans le fichierstorage.json. - À ce stade, votre application dispose d'identifiants valides pour effectuer des appels d'API. L'appel de
googleapiclient.discovery.build()crée un point de terminaison de service pour l'API que vous utilisez. - Pour utiliser
build(), transmettez le nom de l'API ('drive') et la version souhaitée (actuellement'v3'). - Le dernier paramètre est un client HTTP à utiliser pour les appels d'API chiffrés.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
Récupérer et afficher les 100 premiers fichiers/dossiers Drive et types MIME
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- La ligne de code suivante appelle la méthode
list()dans la collectionfiles()de l'API Drive pour créer la requête, qui est immédiatement appelée avecexecute(). UndictPython est renvoyé, à partir duquel nous demandons la clé'files'pour obtenir les noms de 100 fichiers et dossiers du Google Drive de l'utilisateur (ou moins s'il a moins de fichiers). - Pourquoi 100 ? Il s'agit de la valeur par défaut de
DRIVE.files().list(). Si vous souhaitez modifier ce nombre (par exemple, pour n'inclure que 10 fichiers ou 1 000), ajoutez le paramètrepageSizeà votre requête :DRIVE.files().list(pageSize=10). Pour en savoir plus sur les options disponibles, consultez la documentation. - La dernière partie du script parcourt chaque fichier et affiche son nom et son type MIME.
Vous venez d'écrire votre première application qui utilise une API REST Google. Félicitations ! Hormis les importations et le code d'autorisation, ce script ne comporte que quelques lignes de code (celles que vous voyez ci-dessus). La plupart des API Google fonctionnent de manière similaire. Vous n'aurez qu'à créer des points de terminaison de service pour chacune d'elles.
Utiliser plusieurs API Google dans une application
Oui, vous pouvez tout à fait utiliser plusieurs API dans la même application. Voici un extrait de code Python pour une application qui réutilise le même client HTTP et crée des points de terminaison de service pour trois API Google (oui, également avec trois SCOPES différents) :
SCOPES = (
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/spreadsheets.readonly',
'https://www.googleapis.com/auth/presentations',
)
. . .
HTTP = creds.authorize(Http())
DRIVE = discovery.build('drive', 'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)
Nous imaginons que ce code peut faire partie d'une application qui génère plusieurs présentations (API Slides) à partir de données de feuille de calcul (API Sheets) et utilise un modèle de diapositive qui est copié (API Drive) pour chaque présentation générée. Bien qu'une telle application n'existe pas, vous devriez pouvoir créer quelque chose de similaire en utilisant deux exemples existants que l'équipe Google Workspace a créés comme blocs de construction :
- Remplacer du texte et des images dans des diapositives ( article de blog et vidéo) : utilise l'API Drive pour copier un modèle de diapositives, puis l'API Slides pour modifier les espaces réservés pour le texte et les images
- Générer des diapositives à partir des données de feuilles de calcul ( article de blog et vidéo) : lit les données d'une feuille de calcul (API Sheets) et crée des diapositives (API Slides) en fonction de ces données.
Votre défi : créer cette application !
12. *Utilisation avancée de la console Dev
Dans cette section facultative, nous décrivons comment créer des projets dans la console de développement, activer des API et obtenir des identifiants, le tout sans utiliser l'assistant comme indiqué ci-dessus dans l'atelier de programmation. Cette option s'adresse aux utilisateurs intermédiaires qui se sentent suffisamment à l'aise pour le faire manuellement ou qui souhaitent apprendre à le faire.
Spécifier un projet dans la console Cloud
Chaque fois que vous écrivez une application à l'aide des API Google, vous devez disposer d'un projet. Vous pouvez réutiliser un projet existant ou en créer un. Cela se fait dans la console Cloud. Certains ateliers de programmation fournissent un lien magique (comme un assistant de configuration) qui vous permet de démarrer rapidement en ignorant de nombreuses étapes requises. Toutefois, ce n'est pas le cas de tous. Ces instructions sont donc générales et vous expliquent comment créer des projets.
Vous pouvez créer des projets depuis la plupart des écrans de la console Cloud, à condition d'être connecté avec vos identifiants Google et de voir un menu déroulant de projet en haut de la console. Notez que la plupart des captures d'écran présentées ici proviennent du gestionnaire d'API, également appelé console Developers (facilement accessible en cliquant sur "Gestionnaire d'API" dans le panneau de navigation de gauche ou en saisissant directement console.developers.google.com dans votre navigateur).
- Si vous n'avez pas encore de projets, vous serez peut-être redirigé vers…
- la page Tableau de bord :
- la page Bibliothèque :
- ou une page complètement vide :
Si vous rencontrez ce troisième problème, actualisez simplement le navigateur pour accéder à la page Bibliothèque.
- Que vous soyez sur la page Tableau de bord ou Bibliothèque, cliquez sur le sélecteur de projet en haut de la page :
.
- Vous verrez ensuite la boîte de dialogue du sélecteur. Cliquez sur le bouton "+" à droite pour créer un projet :
- Une fois que vous avez cliqué sur le bouton "+", la page Nouveau projet s'affiche. Tous les comptes personnels bénéficient de 12 projets par défaut. Avant de créer votre premier projet, vous devez accepter les Conditions d'utilisation des API Google :
Une fois cette opération effectuée, les questions sur les sollicitations par e-mail et les conditions d'utilisation ne s'affichent plus lorsque vous créez des projets :
Vous avez créé un projet. Vous pouvez maintenant choisir les API que vous souhaitez utiliser pour votre projet.
Activer les API Google
Avant de pouvoir utiliser les API Google, vous devez les activer. L'exemple ci-dessous montre ce que vous devez faire pour activer l'API Cloud Vision. Dans cet atelier de programmation, vous pouvez être amené à utiliser plusieurs API et vous devez donc suivre la même procédure pour les activer avant toute utilisation.
Depuis Cloud Shell
Dans Cloud Shell, vous pouvez activer l'API à l'aide de la commande suivante:
gcloud services enable vision.googleapis.com
Depuis Cloud Console
Vous pouvez également activer l'API Vision dans le gestionnaire d'API. Dans la console Cloud, accédez au Gestionnaire d'API, puis sélectionnez "Bibliothèque".
Dans la barre de recherche, commencez à saisir "vision", puis sélectionnez l'API Vision lorsqu'elle s'affiche. La recherche avec une saisie partielle doit ressembler à ceci :
Sélectionnez l'API Cloud Vision pour obtenir la boîte de dialogue visible ci-dessous, puis cliquez sur le bouton "Activer" (Enable) :
Coût
Bien que de nombreuses API Google puissent être utilisées sans frais, l'utilisation de GCP (produits et API) est payante. Lorsque vous activez l'API Vision (comme décrit ci-dessus), vous pouvez être invité à renseigner un compte de facturation actif. Les informations tarifaires de l'API Vision doivent être référencées par l'utilisateur avant activation. N'oubliez pas que certains produits Google Cloud Platform (GCP) disposent d'un niveau "Toujours sans frais" que vous devez dépasser pour que la facturation démarre. Pour les besoins de l'atelier de programmation, chaque appel à l'API Vision est comptabilisé dans cette version sans frais. Tant que votre utilisation agrégée ne dépasse pas les limites (pour chaque mois), aucuns frais ne vous seront facturés.
Certaines API Google, par exemple Google Workspace, voient leur utilisation couverte par un abonnement mensuel. Par conséquent, il n'y a pas de facturation directe pour l'utilisation des API Gmail, Google Drive, Agenda, Docs, Sheets et Slides, par exemple. La procédure de facturation est différente selon les produits Google. Par conséquent, assurez-vous de vous référer à la documentation de votre API pour obtenir ces informations.
Résumé
Dans cet atelier de programmation, vous n'avez besoin d'activer que l'API Google Drive. Suivez donc les instructions ci-dessus et recherchez "Drive". Une fois la fonctionnalité activée, passez à l'étape suivante.
Autoriser les requêtes d'API (autorisation utilisateur)
Présentation de l'autorisation (et quelques éléments concernant l'authentification)
Pour pouvoir envoyer des requêtes aux API, votre application doit disposer d'une autorisation appropriée. L'authentification, qui est un terme similaire, décrit les identifiants de connexion. Vous vous authentifiez lorsque vous vous connectez à votre compte Google à l'aide d'un identifiant et d'un mot de passe. Une fois authentifié, l'étape suivante consiste à vérifier si vous, ou plus exactement votre code, êtes autorisé à accéder à des données, telles que des fichiers blob sur Cloud Storage ou les fichiers personnels d'un utilisateur sur Google Drive.
Les API Google sont compatibles avec plusieurs types d'autorisation, mais le plus courant pour les utilisateurs de l'API Google Workspace est l'autorisation des utilisateurs. En effet, l'exemple d'application de cet atelier de programmation accède aux données des utilisateurs finaux. Ces utilisateurs finaux doivent autoriser votre application à accéder à leurs données. Cela signifie que votre code doit obtenir les identifiants OAuth2 du compte utilisateur.
Pour obtenir des identifiants OAuth2 pour l'autorisation des utilisateurs, revenez au gestionnaire d'API, puis sélectionnez l'onglet "Identifiants" (Credentials) dans le menu de navigation de gauche :
Une fois sur cet écran, vous verrez tous vos identifiants s'afficher dans trois sections distinctes :
La première concerne les clés API, la deuxième les ID client OAuth 2.0, et la dernière concerne les comptes de service OAuth2. Celle que nous utilisons est la deuxième section.
Créer des identifiants
Sur la page "Identifiants", cliquez sur le bouton + Créer des identifiants (Create Credentials) qui se trouve en haut. Une boîte de dialogue s'affiche alors, dans laquelle vous devez choisir "ID client OAuth".
Sur l'écran suivant, vous avez deux actions à effectuer : configurer l'écran d'autorisation de votre application et choisir le type d'application :
Si vous n'avez pas configuré d'écran d'autorisation, un avertissement s'affiche dans la console et vous devez configurer l'écran d'autorisation dès maintenant. (Ignorez ces étapes si votre écran d'autorisation a déjà été configuré).
Écran de consentement OAuth
Cliquez sur "Configurer l'écran d'autorisation" (Configure consent screen), et vous devez alors sélectionner une application "Externe" (External) ou "Interne" (Internal) si vous êtes un client Google Workspace :
Notez que, dans le cadre de cet exercice, ce choix n'a pas d'importance, car vous n'allez pas publier votre exemple d'application de l'atelier de programmation. La plupart des utilisateurs sélectionnent "Externe" pour accéder à un écran plus complexe, mais il vous suffit de remplir le champ "Nom de l'application" (Application name) en haut :
Pour le moment, il vous suffit d'indiquer un nom d'application. Choisissez donc un nom qui reflète l'atelier de programmation que vous êtes en train de suivre, puis cliquer sur Enregistrer (Save).
Création de l'ID client OAuth (authentification par compte utilisateur)
Revenez maintenant à l'onglet "Identifiants" (Credentials) pour créer un ID client OAuth2. Voici différents ID client OAuth que vous pouvez créer :
Nous développons un outil de ligne de commande de type Autre (Other). Sélectionnez donc cette option, puis cliquez sur le bouton Créer (Create). Choisissez un nom d'ID client qui reflète l'application que vous créez, ou conservez simplement le nom par défaut, qui est généralement : "Autre client N" (Other Client N).
Enregistrer vos identifiants
- Une boîte de dialogue contenant les nouveaux identifiants s'affiche. cliquez sur OK pour la fermer.
- Revenez à la page "Identifiants" (Credentials), faites défiler la page jusqu'à la section "ID client OAuth2" (OAuth2 Client IDs), puis cliquez sur l'icône de téléchargement
- Cette action ouvre une boîte de dialogue permettant d'enregistrer un fichier nommé
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, probablement dans votre dossier Téléchargements. Nous vous recommandons de raccourcir ce nom vers quelque chose de plus simple, par exempleclient_secret.json(qui est le nom utilisé par l'application d'exemple), puis de l'enregistrer dans le répertoire/dossier où vous allez créer l'exemple d'application dans le cadre de cet atelier de programmation.