google api nodejs client
v0.1.0
Biblioteca de clientes node.js para usar las API de Google. Se incluye el soporte para la autorización y la autenticación con OAuth 2.0, las claves API y los tokens JWT.
API de Google
Empezando
Instalación
Uso de la biblioteca de clientes
Muestras
Referencia de API
Autenticación y autorización
Cliente OAuth2
Usando las teclas API
Credenciales predeterminadas de la aplicación
Credenciales de la cuenta de servicio
Configuración de autenticación global o de nivel de servicio
Uso
Especificando el cuerpo de solicitud
Cargas de medios
Opciones de solicitud
Usando un proxy
API compatibles
Mecanografiado
Http/2
Licencia
Que contribuye
Preguntas/problemas?
La lista completa de API compatibles se puede encontrar en Google API Explorer. Los puntos finales de la API se generan automáticamente, por lo que si la API no está en la lista, actualmente no es compatible con esta biblioteca de clientes API.
Al utilizar API de plataforma en la nube de Google como DataStore, Cloud Storage o Pub/Sub, es recomendable aprovechar las bibliotecas de clientes @Google-Cloud. Estas bibliotecas son clientes de Node.js de Node.js especialmente diseñados especialmente diseñados para servicios específicos de la plataforma de Google Cloud. Recomendamos instalar paquetes API individuales, como @google-cloud/storage . Para explorar una lista completa de los paquetes específicos de la API de Google Cloud Platform, consulte https://cloud.google.com/nodejs/docs/reference.
Estas bibliotecas de clientes son compatibles oficialmente por Google. Sin embargo, estas bibliotecas se consideran completas y están en modo de mantenimiento. Esto significa que abordaremos errores críticos y problemas de seguridad, pero no agregaremos ninguna característica nueva. Para las API de la plataforma de Google Cloud, recomendamos usar Google Cloud-Node, que está en desarrollo activo.
Esta biblioteca admite el mantenimiento LTS, los LT activos y la versión actual de Node.js. Consulte el cronograma de lanzamiento de Node.js para obtener más información.
Esta biblioteca se distribuye en npm . Para agregarlo como dependencia, ejecute el siguiente comando:
$ npm instalación googleapis
Si necesita reducir los tiempos de inicio, alternativamente puede instalar un submódulo como su propia dependencia. Hacemos un esfuerzo por publicar submódulos que no están en esta lista. Para agregarlo como dependencia, ejecute el siguiente comando de muestra, reemplazando con su API preferida:
$ npm instalación @googleapis/docs
Puede ejecutar esta búsqueda en npm , para encontrar una lista de los submódulos disponibles.
Este es un ejemplo muy simple. Esto crea un cliente blogger y recupera los detalles de un blog dado la identificación del blog:
const {Google} = require ('Googleapis'); // Cada API puede admitir múltiples versiones. Con esta muestra, estamos obteniendo // v3 de la API de Blogger y utilizando una clave API para autenticar.const blogger = google.blogger ({{
Versión: 'V3',
Auth: 'Your API Key'}); const params = {
BlogID: '3213900'}; // Obtenga el blog Detallesblogger.blogs.get (params, (err, res) => {
if (err) {console.error (err); tirar err;
}
console.log (`la url del blog es $ {res.data.url}`);});¡En lugar de usar devoluciones de llamada, también puede usar promesas!
Blogger.blogs.get (Params)
.Then (res => {console.log (`La url del blog es $ {res.data.url}`);
})
.catch (error => {console.error (error);
});O async/espera:
function async runSample () {
const res = ALEA BLECGER.BLOGS.GET (params);
console.log (`la url del blog es $ {res.data.url}`);} runSample (). Catch (console.error);Alternativamente, puede hacer llamadas directamente a las API instalando un submódulo:
const docs = require ('@googleapis/docs') const auth = new docs.auth.googleauth ({
KeyFileName: 'Path_to_service_account_key.json', // Los ámbitos se pueden especificar como una matriz o como una sola cadena delimitada de espacio.
Scopes: ['https://www.googleapis.com/auth/documents'font>) ;Const authClient = await auth.getClient (); const client = await docs.docs ({versión:' v1 ', authclient }); const creatreponse = await client.documents.create ({requestbody: {title: 'su nuevo documento!',},}); console.log (createraponse.data);¿Hay muchas muestras? Si está tratando de descubrir cómo usar una API ... ¡Mire allí primero! Si hay una muestra que necesita falta, no dude en presentar un problema.
Esta biblioteca tiene un conjunto completo de documentación de referencia de API. Esta documentación se generó automáticamente y la ubicación puede cambiar.
Hay múltiples formas de autenticarse en las API de Google. Algunos servicios admiten todos los métodos de autenticación, mientras que otros solo pueden admitir uno o dos.
OAUTH2 : esto le permite hacer llamadas API en nombre de un usuario determinado. En este modelo, el usuario visita su aplicación, inicia sesión con su cuenta de Google y proporciona a su aplicación autorización a un conjunto de ámbitos. Aprende más.
Clave API : con una clave API, puede acceder a su servicio desde un cliente o del servidor. Por lo general, menos seguro, esto solo está disponible en un pequeño subconjunto de servicios con ámbitos limitados. Aprende más.
Credenciales predeterminadas de la aplicación : proporciona acceso automático a las API de Google utilizando el SDK de Google Cloud para el desarrollo local, o el servidor de metadatos GCE para aplicaciones implementadas en Google Cloud Platform. Aprende más.
Credenciales de cuenta de servicio : en este modelo, su aplicación habla directamente con las API de Google utilizando una cuenta de servicio. Es útil cuando tiene una aplicación de backend que hablará directamente con las API de Google desde el backend. Aprende más.
Para obtener más información sobre el cliente de autenticación, consulte la biblioteca de Google Auth.
Este módulo viene con un cliente OAuth2 que le permite recuperar un token de acceso, actualizarlo y volver a intentar la solicitud sin problemas. Los conceptos básicos de la implementación de OAUTH2 de Google se explica sobre la documentación de autorización y autenticación de Google.
En los siguientes ejemplos, es posible que necesite un CLIENT_ID , CLIENT_SECRET y REDIRECT_URL . Puede encontrar estas piezas de información yendo a la consola de desarrolladores, haciendo clic en su proyecto -> API y Auth -> Credenciales.
Navegue a la consola de la nube y cree una nueva ID de cliente OAuth2
Seleccione Web Application para el tipo de aplicación
Agregue un URI de redirección autorizado con el valor http://localhost:3000/oauth2callback (o valor aplicable para su escenario)
Haga clic en Create y Ok en la siguiente pantalla
Haga clic en el icono Download junto a su ID de cliente OAuth2 recientemente creado
¡Asegúrese de almacenar este archivo en un lugar seguro y no verifique este archivo al control de origen!
Para obtener más información sobre OAuth2 y cómo funciona, vea aquí.
Una solicitud de muestra completa que autoriza y se autentica con el cliente OAUTH2 está disponible en samples/oauth2.js .
Para solicitar permisos de un usuario para recuperar un token de acceso, los redirige a una página de consentimiento. Para crear una URL de la página de consentimiento:
const {Google} = require ('googleapis'); const oauth2client = new Google.auth.oauth2 (
You_client_id,
You_client_secret,
Your_redirect_url); // Generar una URL que solicite permisos para Blogger y Google Calendar Scopesconst Scopes = [
'https://www.googleapis.com/auth/blogger',,
'https://www.googleapis.com/auth/calendar'font>Const url = oauth2client.generateAuthurl ({{
// 'en línea' (predeterminado) o 'fuera de línea' (obtiene refresh_token)
access_type: 'fuera de línea',
// Si solo necesita un alcance, puede pasarlo como una cadena
alcance: alcances}); Nota importante : el refresh_token solo se devuelve en la primera autorización. Más detalles aquí.
Una vez que un usuario ha dado permisos en la página de consentimiento, Google redirigirá la página a la URL de redirección que ha proporcionado un parámetro de consulta de código.
GET /oauthcallback?code={authorizationCode}Con el código devuelto, puede solicitar un token de acceso como se muestra a continuación:
// Esto proporcionará un objeto con Access_Token and Refresh_token.// Guardarlos en algún lugar seguros para que puedan usarse en un momento posterior.const {tokens} = ALEAT OAUTH2CLIENT.GETTOKen (código) oauth2client.setCredententials (tokens);Con las credenciales establecidas en su cliente OAuth2, ¡está listo para comenzar!
Los tokens de acceso caducan. Esta biblioteca usará automáticamente un token de actualización para obtener un nuevo token de acceso si está a punto de caducar. Una manera fácil de asegurarse de que siempre almacene los tokens más recientes es usar el evento tokens :
oauth2client.on ('tokens', (tokens) => {
if (tokens.refresh_token) {// almacenar el refresh_token en mi base de datos! console.log (tokens.refresh_token);
}
console.log (tokens.access_token);}); Este evento de tokens solo ocurre en la primera autorización, y debe haber configurado su access_type en offline al llamar al método generateAuthUrl para recibir el token de actualización. Si ya le ha dado a su aplicación los permisos requeridos sin establecer las restricciones apropiadas para recibir un token de actualización, deberá volver a autorizar la aplicación para recibir un token de actualización fresca. Puede revocar el acceso de su aplicación a su cuenta aquí.
Para establecer el refresh_token en un momento posterior, puede usar el método setCredentials :
oauth2client.setCredentials ({
refresh_token: `stored_refresh_token`});Una vez que el cliente tenga un token de actualización, los tokens de acceso se adquirirán y actualizarán automáticamente en la próxima llamada a la API.
Los tokens de actualización pueden dejar de funcionar después de que se les otorgue, ya sea porque:
El usuario ha revocado el acceso de su aplicación
El token de actualización no se ha utilizado durante 6 meses
El usuario cambió de contraseña y el token de actualización contiene ámbitos de Gmail
La cuenta de usuario ha excedido un número máximo de tokens de actualización en vivo
La aplicación tiene un estado de 'prueba' y la pantalla de consentimiento está configurada para un tipo de usuario externo, lo que hace que el token expire en 7 días
Como desarrollador, debe escribir su código para manejar el caso donde un token de actualización ya no funciona.
Es posible que deba enviar una clave API con la solicitud que va a hacer. Lo siguiente utiliza una clave API para hacer una solicitud al Servicio de API de Blogger para recuperar el nombre de un blog, URL y su cantidad total de publicaciones:
const {google} = require ('googleapis'); const blogger = google.blogger_v3 ({
Versión: 'V3',
Auth: 'Your_api_Key' // Especifique su clave API aquí}); const params = {
BlogID: '3213900'}; Async Function Main (Params) {
const res = await blogger.blogs.get ({blogID: params.blogid});
console.log (`$ {res.data.name} tiene $ {res.data.posts.totalitems} publicaciones! La url del blog es $ {res.data.url}`)}; main (). Catch (console. error);Para obtener más información sobre las claves API, consulte la documentación.
En lugar de crear manualmente un cliente OAuth2, un cliente JWT o un cliente de computa, la biblioteca de autores puede crear el tipo de credencial correcto para usted, dependiendo del entorno en el que se ejecute su código.
Por ejemplo, se creará un cliente de Auth JWT cuando su código se ejecute en su máquina de desarrollador local, y se creará un cliente de cómputo cuando el mismo código se ejecute en una instancia configurada de Google Compute Engine. El siguiente código muestra cómo recuperar un tipo de credencial predeterminado, dependiendo del entorno de tiempo de ejecución.
Para usar las credenciales predeterminadas de la aplicación localmente con el SDK de Google Cloud, ejecute:
$ GCLOUD AUTH APLICACIÓN DE APLICACIÓN DE ALTACIÓN
Cuando se ejecuta en GCP, el servicio Autorize se proporciona automáticamente a través del servidor GCE Metadata.
const {Google} = require ('googleapis'); const compute = google.compute ('v1'); function async main () {
const auth = new Google.auth.googleauth ({// Scopes se puede especificar como una matriz o como una sola string.scopes de espacio-space: ['https://www.googleapis.com/auth/compute']]
});
const authClient = await auth.getClient ();
// Obtener la ID de proyecto actual
const proyecto = ASHAIT AUTH.GETPROJECTID ();
// Obtener la lista de zonas de GCE dentro de un proyecto.
const res = await compute.zones.list ({proyecto, auth: authclient});
console.log (res.data);} main (). Catch (console.error);Las cuentas de servicio le permiten realizar la autenticación de nivel de servidor a nivel de aplicaciones utilizando una cuenta de robot. Creará una cuenta de servicio, descargará un perfil de teclas y lo usará para autenticarse en las API de Google. Para crear una cuenta de servicio:
Vaya a la página Crear clave de cuenta de servicio
Seleccione New Service Account en el menú desplegable
Haga clic en el botón Create
¡Guarde el archivo de credencial de cuenta de servicio en algún lugar seguro y no verifique este archivo en el control de origen ! Para hacer referencia al archivo de credencial de cuenta de servicio, tiene algunas opciones.
GOOGLE_APPLICATION_CREDENTIALS Env VAR Puede iniciar el proceso con una variable de entorno llamada GOOGLE_APPLICATION_CREDENTIALS . El valor de esta var debe ser la ruta completa al archivo de credencial de cuenta de servicio:
$ Google_application_Credentials =./Your-Secret-Key.json Node Server.js
keyFile Alternativamente, puede especificar la ruta al archivo de credencial de cuenta de servicio a través de la propiedad keyFile en el constructor GoogleAuth :
const {Google} = require ('googleapis'); const auth = new Google.auth.googleauth ({
KeyFile: '/path/to/your-secret-key.json',
Scopes: ['https://www.googleapis.com/auth/cloud-platform'],}); Puede establecer la auth como una opción global o de nivel de servicio para que no necesite especificarlo en todas las solicitudes. Por ejemplo, puede configurar auth como una opción global:
const {Google} = require ('googleapis'); const oauth2client = new Google.auth.oauth2 (
You_client_id,
You_client_secret,
Your_redirect_url); // Establezca la auth como un global defaultGoogle.options ({
auth: oauth2client});En lugar de configurar la opción a nivel mundial, también puede establecer el cliente de autenticación en el nivel de servicio:
const {Google} = require ('googleapis'); const oauth2client = new Google.auth.oauth2 (
You_client_id,
You_client_secret,
Your_Redirect_url); const Drive = Google.drive ({
Versión: 'V2',
auth: oauth2client});Consulte la sección Opciones para obtener más información.
El cuerpo de la solicitud se especifica en el objeto de parámetro requestBody de la solicitud. El cuerpo se especifica como un objeto JavaScript con pares de clave/valor. Por ejemplo, esta muestra crea un observador que publica notificaciones en un tema de pub/submarino de Google Cloud cuando los correos electrónicos se envían a una cuenta de Gmail:
const res = espera gmail.users.watch ({
UserID: 'Yo',
requestBody: {// reemplazar con `proyectos/$ {proyect_id}/topics/$ {topic_name}` topicName: `proyectos/el-gato/temas/gmail`
}}); console.log (res.data); Este cliente admite cargas de medios multipart. Los parámetros de recursos se especifican en el objeto de parámetro requestBody , y los medios en sí se especifican en el media.mimeType media.body
Este ejemplo carga un archivo de texto sin formato en Google Drive con el título "Prueba" y contenido "Hello World".
Const Drive = Google.Drive ({
Versión: 'V3',
Auth: Oauth2client}); const res = ALEAIT DRIVE.FILES.CREATE ({
requestBody: {nombre: 'test', mImetype: 'Text/Plain'
},
Medios: {MIMETYPE: 'Text/Plain', Body: 'Hello World'
}}); También puede cargar medios especificando media.body como una transmisión legible. Esto puede permitirle cargar archivos muy grandes que no pueden caber en la memoria.
const fs = require ('FS'); const Drive = Google.drive ({
Versión: 'V3',
auth: oauth2client}); async función main () {
const res = await drive.files.create ({requestbody: {name: 'testimage.png', mImetype: 'Image/png'}, Media: {Mimetype: 'Image/png', Body: Fs.CreateReadStream ('Awesome .png ')}
});
console.log (res.data);} main (). Catch (console.error); Para obtener más ejemplos de solicitudes de creación y modificación con archivos adjuntos de medios, eche un vistazo a la muestra de samples/drive/upload.js .
Para un control más ajustado sobre cómo se realizan sus llamadas API, le brindamos la capacidad de especificar opciones adicionales que se pueden aplicar directamente al objeto 'Gaxios' utilizado en esta biblioteca para realizar llamadas de red a la API.
Puede especificar opciones adicionales, ya sea en el objeto Global google o en una base de cliente de servicio. Las opciones que especifique se adjunta al objeto gaxios , por lo que cualquier gaxios admite, esta biblioteca admite. También puede especificar parámetros de solicitud global o por servicio que se adjuntarán a todas las llamadas de API que realiza.
Aquí puede encontrar una lista completa de opciones compatibles.
Puede elegir opciones predeterminadas que se enviarán con cada solicitud. Estas opciones se utilizarán para cada servicio instanciado por el cliente de Google. En este ejemplo, la propiedad timeout de GaxiosOptions se establecerá para cada solicitud:
const {Google} = require ('googleapis'); google.options ({
// Todas las solicitudes realizadas con este objeto utilizarán estas configuraciones a menos que se anule.
Tiempo de espera: 1000,
auth: auth});También puede modificar los parámetros enviados con cada solicitud:
const {Google} = require ('googleapis'); google.options ({
// Todas las solicitudes de todos los servicios contendrán el parámetro de consulta anterior
// a menos que se anule en un cliente de servicio o en llamadas de API individuales.
Params: {CuotaUser: '[email protected]'
}});También puede especificar opciones al crear un cliente de servicio.
const blogger = google.blogger ({
Versión: 'V3',
// Todas las solicitudes hechas con este objeto utilizarán la autenticación especificada.
auth: 'Key API';}); Al hacer esto, cada llamada de API realizada con este cliente de servicio utilizará 'API KEY' para autenticarse.
Nota: Los clientes creados son inmutables , por lo que debe crear uno nuevo si desea especificar diferentes opciones.
Similar a los ejemplos anteriores, también puede modificar los parámetros utilizados para cada llamada de un servicio determinado:
const blogger = google.blogger ({
Versión: 'V3',
// Todas las solicitudes hechas con este cliente de servicio contendrán el
// Parámetro de consulta BlogID a menos que se anule en las llamadas de API individuales.
Params: {BlogID: '3213900'
}}); // Las llamadas con este cliente de unidad no contendrán el parámetro de consulta BlogID.const Drive = Google.drive ('v3'); ... Puede especificar un objeto auth que se use por solicitud. Cada solicitud también hereda las opciones especificadas a nivel de servicio y nivel global.
Por ejemplo:
const {google} = request ('googleapis'); const bigQuery = google.bigQuery ('v2'); function async main () {
// Este método busca el gcloud_project y google_application_credentials
// Variables de entorno.
const auth = new Google.auth.googleauth ({Scopes: ['https://www.googleapis.com/auth/cloud-platform']
});
const authClient = await auth.getClient ();
const ProjectId = await auth.getProjectId ();
const solicitud = {ProjectId, DataSEtID: '<Your_DataSet_id>', // Esta es una opción "nivel de solicitud": AuthClient
};
const res = espera bigQuery.datasets.delete (solicitud);
console.log (res.data);} main (). Catch (console.error); También puede anular las opciones de Gaxios por solicitud, como url , method y responseType .
Por ejemplo:
const res = await drive.files.export ({
fileid: 'asxkjod9s79', // un documento de Google
MIMETYPE: 'Aplicación/PDF'}, {
// asegúrese de obtener los datos binarios
ResponseType: 'stream'});Puede usar las siguientes variables de entorno para solicitudes proxy http y https:
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
Cuando se establezcan http_proxy / http_proxy, se utilizarán para proxy de solicitudes no SSL que no tienen una opción de configuración de proxy explícita presente. Del mismo modo, https_proxy / https_proxy se respetará para las solicitudes SSL que no tienen una opción de configuración de proxy explícita. Es válido definir un proxy en una de las variables de entorno, pero luego anularlo para una solicitud específica, utilizando la opción de configuración de proxy.
Puede obtener mediante programación la lista de API compatibles y todas las versiones disponibles:
const {Google} = require ('googleapis'); const apis = google.getSupportedapis ();Esto devolverá un objeto con el nombre de la API como nombres de propiedad del objeto y una matriz de cadenas de versión como valores de objeto;
Esta biblioteca está escrita en TypeScript y proporciona tipos fuera de la caja. Todas las clases e interfaces generadas para cada API se exportan bajo el espacio de nombres ${apiName}_${version} . Por ejemplo, los tipos de API de unidad V3 están disponibles desde el espacio de nombres drive_v3 :
importar {
Google, // El objeto de nivel superior utilizado para acceder a los servicios
Drive_v3, // Para cada cliente de servicio, hay un espacio de nombres exportado
Auth, // espacio de nombres para tipos relacionados con autenticación
Common, // Los tipos generales utilizados en toda la biblioteca} de 'Googleapis'; // Nota: el uso de tipos explícitos como `Auth.googleauth` solo están aquí para // fines de demostración. Generalmente con TypeScript, estos tipos se inferirían.
Versión: 'V3',
auth,}); // Hay tipos generados para cada conjunto de parámetros de solicitud de listParams: Drive_V3.Params $ recursos $ archivos $ list = {}; const res = await drive.files.list (listParams); // se generan tipos para los campos de respuesta y listresults: drive_v3.schema $ fileList = res.data; Esta biblioteca cuenta con soporte para HTTP/2. Para habilitarlo, use la opción http2 en cualquier lugar que se acepten los parámetros de solicitud:
const {Google} = require ('googleapis'); google.options ({
http2: true,});HTTP/2 a menudo es más desempeñado, ya que permite la multiplexación de múltiples solicitudes concurrentes en un solo enchufe. En una API HTTP/2 tradicional, el cliente es directamente responsable de abrir y cerrar las sesiones hechas para realizar solicitudes. Para mantener la compatibilidad con la API existente, este módulo reutilizará automáticamente las sesiones existentes, que se recopilan después de ralentí durante 500 ms. Gran parte de las ganancias de rendimiento serán visibles en cargas de trabajo de estilo por lotes y bucles ajustados.
Puede encontrar una lista detallada de cambios de ruptura y nuevas características en nuestras notas de versión. Si ha usado esta biblioteca antes 25.x , consulte nuestras notas de versión para aprender sobre la migración de su código de 24.xx a 25.xx Es bastante fácil :)
Esta biblioteca tiene licencia bajo Apache 2.0. El texto completo de la licencia está disponible en licencia.
¡Nos encantan las contribuciones! Antes de enviar una solicitud de extracción, siempre es bueno comenzar con un nuevo problema primero. Para obtener más información, ver contribución.
Haga sus preguntas relacionadas con el desarrollo en StackOverflow.
Si ha encontrado un error/problema, preséntelo en GitHub.
