google api nodejs client
v0.1.0
Bibliothèque client Node.js pour l'utilisation d'API Google. La prise en charge de l'autorisation et de l'authentification avec OAuth 2.0, les clés API et les jetons JWT est incluse.
API Google
Commencer
Installation
Utilisation de la bibliothèque client
Échantillons
Référence de l'API
Authentification et autorisation
Client OAuth2
Utilisation des touches API
Application des informations d'identification par défaut
Informations sur le compte de service
Définition de l'automobile au niveau global ou du service
Usage
Spécification du corps de demande
Téléchargements de médias
Demander des options
Utilisation d'un proxy
API soutenues
Manuscrit
Http / 2
Licence
Contributif
Questions / problèmes?
La liste complète des API prises en charge peut être trouvée sur Google API Explorer. Les points de terminaison de l'API sont générés automatiquement, donc si l'API n'est pas dans la liste, elle n'est actuellement pas prise en charge par cette bibliothèque client API.
Lorsque vous utilisez des API de plate-forme Cloud Google comme le stockage de données, le stockage cloud ou le Pub / Sub, il est conseillé de tirer parti des bibliothèques client @ google-cloud. Ces bibliothèques sont des clients Node.js idiomatiques spécialement conçus pour des services de plate-forme Google Cloud spécifiques. Nous vous recommandons d'installer des packages API individuels, tels que @google-cloud/storage . Pour explorer une liste complète des packages spécifiques à la plate-forme Google Cloud, veuillez vous référer à https://cloud.google.com/nodejs/docs/reference.
Ces bibliothèques de clients sont officiellement prises en charge par Google. Cependant, ces bibliothèques sont considérées comme complètes et sont en mode de maintenance. Cela signifie que nous aborderons les bogues et les problèmes de sécurité critiques, mais n'ajouterons aucune nouvelle fonctionnalité. Pour les API de la plate-forme Google Cloud, nous vous recommandons d'utiliser Google-Cloud-Node qui est en cours de développement actif.
Cette bibliothèque prend en charge les LT de maintenance, le LTS actif et la version actuelle de Node.js. Voir le programme de version Node.js pour plus d'informations.
Cette bibliothèque est distribuée sur npm . Afin de l'ajouter comme dépendance, exécutez la commande suivante:
$ npm installer googleapis
Si vous devez réduire les temps de démarrage, vous pouvez également installer un sous-module comme sa propre dépendance. Nous nous efforçons de publier des sous-modules qui ne figurent pas dans cette liste. Afin de l'ajouter comme dépendance, exécutez l'exemple de commande suivante, en remplaçant par votre API préférée:
$ npm install @ googleapis / docs
Vous pouvez exécuter cette recherche sur npm , pour trouver une liste des sous-modules disponibles.
Ceci est un exemple très simple. Cela crée un client blogueur et récupère les détails d'un blog compte tenu de l'ID de blog:
const {google} = require ('googleapis'); // chaque API peut prendre en charge plusieurs versions. Avec cet échantillon, nous obtenons // v3 de l'API Blogger, et utilisant une clé API pour authentifier.const Blogger = Google.Blogger ({{
Version: «V3»,
auth: 'Votre clé API'}); const params = {{
Blogid: '3213900'}; // Obtenez le blog de détailsblogger.blogs.get (params, (err, res) => {
if (err) {console.error (err); throw err;
}
console.log (`L'URL du blog est $ {res.data.url}`);});Au lieu d'utiliser des rappels, vous pouvez également utiliser des promesses!
blogger.blogs.get (params)
.Then (res => {console.log (`L'URL du blog est $ {res.data.url}`);
})
.Catch (error => {Console.Error (erreur);
});Ou async / attend:
fonction async runsample () {
const Res = attendre blogger.blogs.get (params);
console.log (`L'URL du blog est $ {res.data.url}`);} runsample (). Catch (console.error);Alternativement, vous pouvez passer des appels directement aux API en installant un sous-module:
const docs = require ('@ googleapis / docs') const auth = new docs.auth.googleAuth ({
KeyFileName: 'path_to_service_account_key.json', // Les étendues peuvent être spécifiées soit en tableau ou en une seule chaîne dédiée à l'espace.
Scopes: ['https://www.googleapis.com/auth/Documents' de Lodaly)' }); const CreateResponse = attendre client.documents.create ({requestBody: {title: 'Votre nouveau document!',},}); console.log (CreateResponse.data);Il y a beaucoup d'échantillons? Si vous essayez de comprendre comment utiliser une API ... regardez d'abord là-bas! S'il y a un échantillon qui vous manque, n'hésitez pas à déposer un problème.
Cette bibliothèque a un ensemble complet de documentation de référence API. Cette documentation est générée automatiquement et l'emplacement peut changer.
Il existe plusieurs façons de s'authentifier aux API Google. Certains services prennent en charge toutes les méthodes d'authentification, tandis que d'autres ne peuvent prendre en charge qu'un ou deux.
OAuth2 - Cela vous permet de passer des appels d'API au nom d'un utilisateur donné. Dans ce modèle, l'utilisateur visite votre application, signe avec son compte Google et fournit une autorisation de votre application par rapport à un ensemble de lunettes. Apprendre encore plus.
Clé API - Avec une clé API, vous pouvez accéder à votre service à partir d'un client ou du serveur. Généralement moins sécurisé, cela n'est disponible que sur un petit sous-ensemble de services avec des lunettes limitées. Apprendre encore plus.
Application par défaut des informations d'identification - fournit un accès automatique aux API Google à l'aide du SDK Google Cloud pour le développement local, ou le serveur de métadonnées GCE pour les applications déployées sur Google Cloud Platform. Apprendre encore plus.
Informations sur le compte de service - Dans ce modèle, votre application s'entretient directement avec Google API à l'aide d'un compte de service. Il est utile lorsque vous avez une application backend qui parlera directement aux API Google à partir du backend. Apprendre encore plus.
Pour en savoir plus sur le client d'authentification, consultez la bibliothèque Google Auth.
Ce module est livré avec un client OAuth2 qui vous permet de récupérer un jeton d'accès, de le rafraîchir et de réessayer la demande de manière transparente. Les bases de l'implémentation OAuth2 de Google sont expliquées sur l'autorisation de Google et la documentation d'authentification.
Dans les exemples suivants, vous pouvez avoir besoin d'un CLIENT_ID , CLIENT_SECRET et REDIRECT_URL . Vous pouvez trouver ces informations en vous rendant à la console du développeur, en cliquant sur votre projet -> API & AUTH -> Contaliens.
Accédez à la console cloud et créez un nouvel ID client OAuth2
Sélectionnez Web Application pour le type d'application
Ajoutez un URI redirigé autorisé avec la valeur http://localhost:3000/oauth2callback (ou valeur applicable pour votre scénario)
Cliquez sur Create , et Ok sur l'écran suivant
Cliquez sur l'icône Download à côté de votre ID client OAuth2 nouvellement créé
Assurez-vous de stocker ce fichier en lieu sûr et ne vérifiez pas ce fichier dans le contrôle de la source!
Pour plus d'informations sur OAuth2 et comment cela fonctionne, consultez ici.
Un exemple d'échantillon complet qui autorise et authentifie avec le client OAuth2 est disponible chez samples/oauth2.js .
Pour demander des autorisations à un utilisateur pour récupérer un jeton d'accès, vous les redirigez vers une page de consentement. Pour créer une URL de page de consentement:
const {google} = requis ('googleapis'); const oauth2client = new Google.auth.oauth2 (
Votre_client_id,
Votre_client_secret,
Your_redirect_url); // générer une URL qui demande des autorisations pour Blogger et Google Calendar ScopesConst Scopes = [
'https://www.googleapis.com/auth/blogger',
'https://www.googleapis.com/auth/calendar'mal ;const url = oauth2client.generateUtHurl ({
// `` en ligne '' (par défaut) ou «hors ligne» (obtient Refresh_Token)
Access_type: «hors ligne»,
// Si vous n'avez besoin que d'une seule portée, vous pouvez le passer en tant que chaîne
Scope: Scopes}); Remarque importante - Le refresh_token n'est renvoyé que sur la première autorisation. Plus de détails ici.
Une fois qu'un utilisateur a donné des autorisations sur la page de consentement, Google redirigera la page vers l'URL de redirection que vous avez fournie avec un paramètre de requête de code.
GET /oauthcallback?code={authorizationCode}Avec le code retourné, vous pouvez demander un jeton d'accès comme indiqué ci-dessous:
// Cela fournira un objet avec l'accès_token et refresh_token.// les enregistrer dans un endroit sûr afin qu'ils puissent être utilisés plus tard.const {tokens} = attendre oAuth2Client.getToken (code) oAuth2Client.SetCredentials (tokens);Avec les informations d'identification fixées sur votre client OAuth2 - vous êtes prêt à partir!
Les jetons d'accès expirent. Cette bibliothèque utilisera automatiquement un jeton de rafraîchissement pour obtenir un nouveau jeton d'accès s'il est sur le point d'expirer. Un moyen facile de vous assurer de toujours stocker les jetons les plus récents est d'utiliser l'événement tokens :
oAuth2Client.on ('tokens', (tokens) => {
if (tokens.refresh_token) {// Stockez le refresh_token dans ma base de données! Console.log (tokens.refresh_token);
}
console.log (tokens.access_token);}); Cet événement de jetons ne se produit que dans la première autorisation, et vous devez avoir défini votre access_type sur offline lorsque vous appelez la méthode generateAuthUrl pour recevoir le jeton de rafraîchissement. Si vous avez déjà donné à votre application les autorisations requises sans définir les contraintes appropriées pour recevoir un jeton de rafraîchissement, vous devrez réautoriser l'application pour recevoir un nouveau jeton de rafraîchissement. Vous pouvez révoquer l'accès de votre application à votre compte ici.
Pour définir le refresh_token plus tard, vous pouvez utiliser la méthode setCredentials :
oAuth2Client.setCredentials ({{
Refresh_token: `Stored_refresh_token`});Une fois que le client a un jeton de rafraîchissement, les jetons d'accès seront acquis et actualisés automatiquement lors de l'appel suivant à l'API.
Les jetons de rafraîchissement peuvent cesser de travailler après leur accord, soit parce que:
L'utilisateur a révoqué l'accès de votre application
Le jeton de rafraîchissement n'a pas été utilisé depuis 6 mois
L'utilisateur modifié les mots de passe et le jeton de rafraîchissement contient des étendues Gmail
Le compte d'utilisateur a dépassé un nombre maximum de jetons de rafraîchissement en direct
L'application a un statut de «test» et l'écran de consentement est configuré pour un type d'utilisateur externe, ce qui fait expirer le jeton dans 7 jours
En tant que développeur, vous devez écrire votre code pour gérer le cas où un jeton de rafraîchissement ne fonctionne plus.
Vous devrez peut-être envoyer une clé API avec la demande que vous allez faire. Ce qui suit utilise une clé API pour faire une demande au service API Blogger pour récupérer le nom d'un blog, URL et son montant total de messages:
const {google} = required ('googleapis'); const blogger = google.blogger_v3 ({
Version: «V3»,
auth: 'your_api_key' // spécifiez votre clé API ici}); const params = {
Blogid: '3213900'}; fonction asynchrone Main (params) {
const Res = attendre blogger.blogs.get ({blogid: params.blogid});
console.log (`$ {res.data.name} a $ {res.data.post.totalitems} Posts! L'URL du blog est $ {res.data.url}`)}; main (). Catch (console. erreur);Pour en savoir plus sur les clés API, veuillez consulter la documentation.
Plutôt que de créer manuellement un client OAuth2, un client JWT ou un client de calcul, la bibliothèque AUTH peut créer le type d'identification correct pour vous, selon l'environnement dans lequel vous exécutez.
Par exemple, un client JWT Auth sera créé lorsque votre code s'exécute sur votre machine de développeur locale, et un client de calcul sera créé lorsque le même code s'exécute sur une instance configurée de Google Compute Engine. Le code ci-dessous montre comment récupérer un type d'identification par défaut, selon l'environnement d'exécution.
Pour utiliser les informations d'identification par défaut de l'application localement avec le SDK Google Cloud, exécutez:
$ GCLOUD AUTH APPLICATION-DEFAULT Connexion
Lors de l'exécution dans GCP, le service Autoriser est automatiquement fourni via le serveur de métadonnées GCE.
const {google} = required ('googleapis'); const compute = google.compute ('v1'); fonction async main () {
const Auth = new Google.auth.googleAuth ({// Scopes peut être spécifié soit en tableau ou en un seul, Space-Delimited String.scopes: ['https://www.googleapis.com/auth/compute']
});
const uttelClient = attend auth.getClient ();
// Obtenez l'ID du projet actuel
const project = attend auth.getProjectId ();
// Récupérez la liste des zones GCE dans un projet.
const res = attend compute.zones.list ({project, auth: authClient});
console.log (res.data);} main (). Catch (console.error);Les comptes de service vous permettent d'effectuer une authentification de niveau de serveur à serveur, à l'aide d'un compte robot. Vous allez créer un compte de service, télécharger un fichier clé et l'utiliser pour s'authentifier avec Google API. Pour créer un compte de service:
Accédez à la page Créer un compte de compte Service
Sélectionnez New Service Account dans la liste déroulante
Cliquez sur le bouton Create
Enregistrez le fichier d'identification du compte de service dans un endroit sûr et ne vérifiez pas ce fichier dans le contrôle de la source ! Pour référencer le fichier d'identification du compte Service, vous avez quelques options.
GOOGLE_APPLICATION_CREDENTIALS Env var Vous pouvez commencer le processus avec une variable d'environnement nommée GOOGLE_APPLICATION_CREDENTIALS . La valeur de cet Env Var doit être le chemin d'accès complet au fichier d'identification du compte de service:
$ Google_Application_Credentials =. / Your-Seret-Key.json Node Server.js
keyFile Alternativement, vous pouvez spécifier le chemin d'accès au fichier d'identification du compte de service via la propriété keyFile dans le constructeur GoogleAuth :
const {google} = required ('googleapis'); const auth = new Google.auth.googleAuth ({
KeyFile: '/path/to/your-secret-key.json',
Scopes: ['https://www.googleapis.com/auth/cloud-platform'],}); Vous pouvez définir l' auth en tant qu'option globale ou au niveau du service afin que vous n'ayez pas besoin de le spécifier à chaque demande. Par exemple, vous pouvez définir auth comme une option globale:
const {google} = requis ('googleapis'); const oauth2client = new Google.auth.oauth2 (
Votre_client_id,
Votre_client_secret,
Your_redirect_url); // définir l'auth en tant que Global DefaultGoogle.options ({
auth: oAuth2Client});Au lieu de définir l'option globalement, vous pouvez également définir le client d'authentification au niveau du service:
const {google} = requis ('googleapis'); const oauth2client = new Google.auth.oauth2 (
Votre_client_id,
Votre_client_secret,
Your_redirect_url); const drive = google.drive ({
Version: «V2»,
auth: oAuth2Client});Voir la section Options pour plus d'informations.
Le corps de la demande est spécifié dans l'objet de paramètre requestBody de la demande. Le corps est spécifié comme un objet JavaScript avec des paires de touches / valeur. Par exemple, cet échantillon crée un observateur qui publie des notifications à un sujet de pub / sous Google Cloud lorsque les e-mails sont envoyés à un compte Gmail:
const res = attend gmail.users.watch ({{
UserId: «moi»,
requestbody: {// remplacer par `projets / $ {project_id} / sujets / $ {topic_name}` topicname: `projets / el-gato / sujets / gmail`
}}); console.log (res.data); Ce client prend en charge les téléchargements de médias multiples. Les paramètres de ressource sont spécifiés dans l'objet de paramètre requestBody , et le support lui-même est spécifié dans le paramètre media.body avec un type MIME spécifié dans media.mimeType .
Cet exemple télécharge un fichier texte brut sur Google Drive avec le titre "test" et le contenu "Hello World".
const drive = google.drive ({
Version: «V3»,
auth: oAuth2Client}); const res = wait drive.files.create ({
requestbody: {name: 'test', mimeType: 'text / plain'
},
Média: {mimeType: 'Text / PLAIN', Body: 'Hello World'
}}); Vous pouvez également télécharger des médias en spécifiant media.body en tant que flux lisible. Cela peut vous permettre de télécharger des fichiers très grands qui ne peuvent pas rentrer dans la mémoire.
const fs = require ('fs'); const drive = google.drive ({
Version: «V3»,
auth: oAuth2Client}); fonction asynchrone main () {
const Res = Await Drive.Files.create ({requestbody: {name: 'Tesimage.png', mimeType: 'image / png'}, média: {mimeType: 'image / png', body: fscreateadStream ('Awesome .png ')}
});
console.log (res.data);} main (). Catch (console.error); Pour plus d'exemples de demandes de création et de modification avec les pièces jointes, jetez un œil à l'échantillon samples/drive/upload.js .
Pour un contrôle plus ajusté sur la façon dont vos appels API sont effectués, nous vous offrons la possibilité de spécifier des options supplémentaires qui peuvent être appliquées directement à l'objet 'GAXIOS' utilisé dans cette bibliothèque pour passer des appels réseau vers l'API.
Vous pouvez spécifier des options supplémentaires dans l'objet google global ou sur une base client de service. Les options que vous spécifiez sont attachées à l'objet gaxios , donc tout ce que gaxios prend en charge, cette bibliothèque prend en charge. Vous pouvez également spécifier des paramètres de demande globale ou par service qui seront attachés à tous les appels d'API que vous effectuez.
Une liste complète des options prises en charge peut être trouvée ici.
Vous pouvez choisir des options par défaut qui seront envoyées avec chaque demande. Ces options seront utilisées pour chaque service instancié par le client Google. Dans cet exemple, la propriété timeout de GaxiosOptions sera définie pour chaque demande:
const {google} = require ('googleapis'); google.options ({{
// Toutes les demandes faites avec cet objet utiliseront ces paramètres à moins d'être remplacés.
Timeout: 1000,
auth: auth});Vous pouvez également modifier les paramètres envoyés avec chaque demande:
const {google} = require ('googleapis'); google.options ({{
// Toutes les demandes de tous les services contiendront le paramètre de requête ci-dessus
// Sauf s'il est remplacé par un client de service ou dans des appels API individuels.
Params: {quotauser: '[email protected]'
}});Vous pouvez également spécifier des options lors de la création d'un client de service.
const blogger = google.blogger ({
Version: «V3»,
// Toutes les demandes faites avec cet objet utiliseront l'autheure spécifiée.
auth: 'api key';}); En faisant cela, chaque appel API fait avec ce client de service utilisera 'API KEY' pour s'authentifier.
Remarque: les clients créés sont immuables , vous devez donc en créer un nouveau si vous souhaitez spécifier différentes options.
Semblable aux exemples ci-dessus, vous pouvez également modifier les paramètres utilisés pour chaque appel d'un service donné:
const blogger = google.blogger ({
Version: «V3»,
// Toutes les demandes faites avec ce client de service contiendront le
// Paramètre de requête Blogid Sauf dépasser les appels API individuels.
Params: {Blogid: '3213900'
}}); // Les appels avec ce client Drive ne contiendront pas le paramètre de requête du blogid.const drive = google.drive ('v3'); ... Vous pouvez spécifier un objet auth à utiliser par demande. Chaque demande hérite également des options spécifiées au niveau du service et au niveau mondial.
Par exemple:
const {google} = required ('googleapis'); const bigQuery = google.bigQuery ('v2'); fonction async main () {{
// Cette méthode recherche le gcloud_project et google_application_credentials
// Variables d'environnement.
const Auth = new Google.auth.googleAuth ({Scopes: ['https://www.googleapis.com/auth/cloud-platform']]
});
const uttelClient = attend auth.getClient ();
const projectId = attend auth.getProjectId ();
const de demande = {projectId, dataSetid: '<your_dataset_id>', // Il s'agit d'un "niveau de requête" facultatif: authClient
};
const Res = Await BigQuery.DatAsets.Delete (demande);
console.log (res.data);} main (). Catch (console.error); Vous pouvez également remplacer les options GAXIOS par demande, telles que url , method et responseType .
Par exemple:
const res = attend drive.files.export ({{
FileID: 'ASXKJOD9S79', // un Google Doc
mimeType: 'application / pdf'}, {
// Assurez-vous d'obtenir les données binaires
ResponseType: 'stream'});Vous pouvez utiliser les variables d'environnement suivantes pour proxy les demandes HTTP et HTTPS:
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
Lorsque http_proxy / http_proxy est défini, ils seront utilisés pour proxy les demandes non-SSL qui n'ont pas d'option de configuration proxy explicite présente. De même, HTTPS_PROXY / HTTPS_PROXY sera respecté pour les demandes SSL qui n'ont pas d'option de configuration de proxy explicite. Il est valable de définir un proxy dans l'une des variables d'environnement, mais ensuite de l'emporter pour une demande spécifique, en utilisant l'option de configuration de proxy.
Vous pouvez obtenir par programme la liste des API prises en charge et toutes les versions disponibles:
const {google} = require ('googleapis'); const apis = google.getsupportEdapis ();Cela renverra un objet avec le nom de l'API comme noms de propriété d'objet et un tableau de chaînes de version comme valeurs d'objet;
Cette bibliothèque est écrite en dactylographie et fournit des types hors de la boîte. Toutes les classes et interfaces générées pour chaque API sont exportées sous l'espace de noms ${apiName}_${version} . Par exemple, les types d'API Drive V3 sont tous disponibles dans l'espace de noms drive_v3 :
importer {
Google, // l'objet de niveau supérieur utilisé pour accéder aux services
Drive_V3, // Pour chaque client de service, il y a un espace de noms exporté
Auth, // Espace de noms pour les types liés aux autorités
Les types communs, // généraux utilisés dans la bibliothèque} à partir de 'googleapis'; // Remarque: L'utilisation de types explicites comme `auth.googleauth` ne sont ici qu'à des fins de démonstration. Généralement, avec TypeScript, ces types seraient // inférieurs.
Version: «V3»,
auth,}); // il existe des types générés pour chaque ensemble de paramètres de requête ListParams: Drive_V3.Params $ ressource $ fichiers $ list = {}; const res = wait drive.files.list (listParams); // il y a généré Types pour les champs de réponse ainsi que les listresults de bien-être: Drive_V3.Schema $ fileList = res.data; Cette bibliothèque prend en charge HTTP / 2. Pour l'activer, utilisez l'option http2 partout où les paramètres de demande sont acceptés:
const {google} = require ('googleapis'); google.options ({{
http2: true,});HTTP / 2 est souvent plus performant, car il permet le multiplexage de plusieurs demandes simultanées sur une seule prise. Dans une API HTTP / 2 traditionnelle, le client est directement responsable de l'ouverture et de la fermeture des sessions faites pour faire des demandes. Pour maintenir la compatibilité avec l'API existante, ce module réutilisera automatiquement les sessions existantes, qui sont collectées après le ralenti pendant 500 ms. Une grande partie des gains de performances sera visible dans les charges de travail de style lots et les boucles serrées.
Vous pouvez trouver une liste détaillée des modifications de rupture et de nouvelles fonctionnalités dans nos notes de publication. Si vous avez utilisé cette bibliothèque avant 25.x , consultez nos notes de publication pour en savoir plus sur la migration de votre code de 24.xx à 25.xx C'est assez facile :)
Cette bibliothèque est sous licence sous Apache 2.0. Le texte complet de licence est disponible en licence.
Nous aimons les contributions! Avant de soumettre une demande de traction, il est toujours bon de commencer par un nouveau problème en premier. Pour en savoir plus, voir la contribution.
Posez vos questions liées à votre développement sur Stackoverflow.
Si vous avez trouvé un bogue / problème, veuillez le déposer sur GitHub.
