google api nodejs client
v0.1.0
Node.js客户库库用于使用Google API。包括OAUTH 2.0，API密钥和JWT令牌的授权和身份验证的支持。
Google API
入门
安装
使用客户端库
样品
API参考
身份验证和授权
OAuth2客户端
使用API键
应用程序默认凭据
服务帐户凭据
设置全球或服务级验证
用法
指定请求主体
媒体上传
请求选项
使用代理
支持的API
打字稿
http/2
执照
贡献
问题/问题？
可以在Google API Explorer上找到支持的API的完整列表。 API端点会自动生成，因此，如果API不在列表中，则该API客户端库当前不支持它。
当使用Google Cloud Platform API（例如数据存储，云存储或Pub/sub）时，建议利用 @Google-Cloud客户端库。这些库是专门构建的，惯用的node.js客户端，专为特定的Google云平台服务设计。我们建议安装单个API软件包，例如@google-cloud/storage 。要探索Google Cloud Platform API特定软件包的全面列表，请参阅https://cloud.google.com/nodejs/docs/reference。
这些客户库由Google正式支持。但是，这些库被认为是完整的，并且处于维护模式。这意味着我们将解决关键的错误和安全问题，但不会添加任何新功能。对于Google Cloud Platform API，我们建议使用正在积极开发的Google-Cloud节点。
该库支持Node.js的维护LTS，Active LTS和当前版本。 有关更多信息，请参见Node.js发布时间表。
该库分布在npm上。为了将其添加为依赖项，请运行以下命令：
$ npm安装googleapis
如果您需要减少启动时间，则可以将子模块安装为自己的依赖性。我们努力发布不在此列表中的子模型。为了将其添加为依赖项，请运行以下示例命令，替换您的首选API：
$ npm install @googleapis/docs
您可以在npm上运行此搜索，以找到可用的子模型列表。
这是一个非常简单的例子。这将创建一个博客客户端并检索给定博客ID的博客的详细信息：
const {google} = require（'googleapis'）; //每个API可能支持多个版本。使用此示例，我们将获取Blogger API的// V3，并使用API键来authenticate.const blogger = google.blogger（{{
版本：'v3'，
auth：'您的api键'}）; const params = {
blogid：'3213900'}; //获取博客详细信息blogger.blogs.get（params，（err，res）=> {
if（err）{console.error（err）; throw err;
}
console.log（`博客URL为$ {res.data.url}`）;}）;而不是使用回调，您也可以使用承诺！
Blogger.blogs.get（参数）
。
}））
.catch（error => {console.error（error）;
}）;或异步/等待：
异步函数runsample（）{
const res =等待blogger.blogs.get（params）;
console.log（`博客URL为$ {res.data.url}`）;} runsample（）。catch（console.error）;另外，您可以通过安装子模块直接对API进行呼叫：
const docs = require（'@googleapis/docs'）const auth = new docs.auth.googleauth（{{
keyfileName：'path_to_service_account_key.json'，//示波器可以指定为数组或单个空格限制的字符串。
示波器：['https://www.googleapis.com/auth/documents']}; conconst authclient =等待auth.getClient（）; const client =等待docs.docss.docssss.docs（{version：'v1'，auth，auth：authclient：authclient：authclient：authclient：authclient：authclient：authclient }）; const createSponse =等待client.documents.create（{requestBody：{title：'您的新文档！'，}，}，}）; console.log（createresponse.data）;有很多样本吗？ 如果您想弄清楚如何使用API ...首先看！如果您需要丢失样本，请随时提出问题。
该库具有完整的API参考文档。该文档是自动生成的，位置可能会更改。
有多种方法可以对Google API进行身份验证。一些服务支持所有身份验证方法，而另一些服务可能只支持一两个。
OAuth2-这使您可以代表给定用户拨打API呼叫。 在此模型中，用户访问您的应用程序，使用其Google帐户登录，并为您的应用程序提供针对一组范围的授权。 了解更多。
API键- 使用API密钥，您可以从客户端或服务器访问您的服务。 通常，安全性较低，仅在范围有限的一小部分服务中可用。 了解更多。
应用程序默认凭据- 使用用于本地开发的Google Cloud SDK或用于部署到Google Cloud Platform的应用程序的GCE Metadata Server提供对Google API的自动访问。了解更多。
服务帐户凭据- 在此模型中，您的应用程序使用服务帐户直接与Google API对话。当您有一个后端应用程序可以直接与后端与Google API交谈时，这很有用。了解更多。
要了解有关身份验证客户端的更多信息，请参见Google Auth库。
该模块带有一个OAuth2客户端，可让您检索访问令牌，刷新它并无缝重试该请求。 Google授权和身份验证文档中解释了Google OAuth2实现的基础知识。
在以下示例中，您可能需要CLIENT_ID ， CLIENT_SECRET和REDIRECT_URL 。您可以通过转到开发人员控制台，单击您的项目 - > APIS＆AUTH->凭据来找到这些信息。
导航到云控制台并创建一个新的OAuth2客户端ID
选择应用程序类型的Web Application
将授权的重定向URI添加为http://localhost:3000/oauth2callback （或方案适用的值）
单击Create ，然后在以下屏幕上Ok
单击您新创建的OAuth2客户端ID旁边的Download图标
确保将此文件存储在安全的位置，并且不要将此文件检查到源控制中！
有关OAuth2及其工作原理的更多信息，请参见此处。
授权和对OAuth2客户端进行身份验证的完整示例应用程序可在samples/oauth2.js上找到。
要索取从用户检索访问令牌的权限，您可以将其重定向到同意页面。创建同意页面URL：
const {google} = require（'googleapis'）; const oauth2client = new Google.auth.oauth2（
your_client_id，
your_client_secret，
your_redirect_url）; //生成一个向博客询问许可的URL和Google Calendar scopesConstscopes = [
'https://www.googleapis.com/auth/blogger'，
'https://www.googleapis.com/auth/calendar']; Conconst url = oauth2client.generateauthurl（{{
//'在线'（默认）或“离线”（获取refresh_token）
access_type：'离线'，
//如果只需要一个范围，就可以将其作为字符串传递
范围：范围}）;重要说明- refresh_token仅在第一个授权上返回。更多详细信息。
用户在同意页面上给出了权限后，Google将将页面重定向到您提供的代码查询参数的重定向URL。
GET /oauthcallback?code={authorizationCode}返回代码后，您可以要求提供一个访问令牌，如下所示：
//这将为对象提供一个access_token和refresh_token.///将其保存在安全的地方，以便在以后使用它们。
在您的OAuth2客户端设置的凭证 - 您已经准备好了！
访问令牌过期。如果该库将自动使用刷新令牌，以获取新的访问令牌，如果它即将到期。确保您始终存储最新令牌的一种简单方法是使用tokens事件：
oauth2client.on（'tokens'，（tokens）=> {
if（tokens.refresh_token）{//在我的数据库！console.log（tokens.refresh_token）中存储refresh_token;
}
console.log（tokens.access_token）;}）;该令牌事件仅发生在第一个授权中，并且在调用generateAuthUrl方法以接收刷新令牌时，您需要将access_type设置为offline 。如果您已经为您的应用程序提供了必要的权限，而没有设置接收刷新令牌的适当约束，则需要重新授权该应用程序以接收新的刷新令牌。您可以在此处撤销应用程序对帐户的访问。
要在以后设置refresh_token ，您可以使用setCredentials方法：
oauth2client.setcredentials（{
refresh_token：`stored_refresh_token`}）;一旦客户端具有刷新令牌，将在下一个呼叫API中自动获取访问令牌并刷新。
刷新令牌可能会在被授予后停止工作，要么是因为：
用户已撤销了您的应用程序的访问
刷新令牌已有6个月尚未使用
用户更改了密码，刷新令牌包含gmail范围
用户帐户超过了最大数量的实时刷新令牌
该应用程序具有“测试”状态，并为外部用户类型配置了同意屏幕，导致令牌在7天内过期
作为开发人员，您应该编写代码以处理刷新令牌不再起作用的情况。
您可能需要在要提出的请求中发送一个API键。以下使用API密钥向Blogger API服务提出请求，以检索博客的名称URL及其帖子总量：
const {google} = require（'googleapis'）; const blogger = google.blogger_v3（{{
版本：'v3'，
auth：'your_api_key'//在此处指定您的API键}）; const params = {
blogid：'3213900'}; async函数main（params）{
const res =等待blogger.blogs.get（{blogid：params.blogid}）;
console.log（`$ {res.data.name}具有$ {res.data.posts.totalitems} posts！blog url is $ {res.data.url}`）}; main（）; main（）。错误）;要了解有关API键的更多信息，请参阅文档。
根据您的代码正在运行的环境，而不是手动创建OAuth2客户端，JWT客户端或计算客户端，而是可以为您创建正确的凭据类型。
例如，当您的代码在本地开发人员计算机上运行时，将创建一个JWT Auth客户端，并且当在配置的Google计算引擎的配置实例上运行相同的代码时，将创建计算客户端。下面的代码显示了如何根据运行时环境检索默认的凭据类型。
要使用Google Cloud SDK本地使用应用程序默认凭据，请运行：
$ gcloud auth应用程序默认登录
在GCP运行时，通过GCE元数据服务器自动提供服务授权。
const {google} = require（'googleapis'）; const compute = google.compute（'v1'）; async函数main（）{
const auth = new Google.auth.googleauth（{// scopes可以指定为数组或单个，空格删除的字符串。
}）;
const authclient =等待auth.getClient（）;
//获取当前项目ID
const project =等待auth.getProjectId（）;
//获取项目中的GCE区域列表。
const res =等待compute.zones.list（{project，auth：authclient}）;
console.log（res.data）;} main（）。catch（console.error）;服务帐户允许您使用机器人帐户执行服务器到服务器的应用程序级身份验证。您将创建一个服务帐户，下载密钥文件，然后使用它来对Google API进行身份验证。创建服务帐户：
转到创建服务帐户密钥页面
在下拉中选择New Service Account
单击Create按钮
将服务帐户凭据文件保存在安全的地方，不要将此文件检查到源控件中！ 要引用服务帐户凭据文件，您有一些选项。
GOOGLE_APPLICATION_CREDENTIALS env var您可以使用名为GOOGLE_APPLICATION_CREDENTIALS的环境变量启动进程。该env var的值应该是服务帐户凭据文件的完整途径：
$ Google_application_credentials =。/your-secret-key.json节点server.js
keyFile属性另外，您可以通过GoogleAuth构造函数中的keyFile属性指定服务帐户凭据文件的路径：
const {google} = require（'googleapis'）; const auth = new google.auth.googleauth（{{
keyfile：'/path/to/your-secret-key.json'，
范围：['https://www.googleapis.com/auth/cloud-platform']，}）;您可以将auth设置为全局或服务级选项，因此您无需指定每个请求。例如，您可以将auth设置为全局选项：
const {google} = require（'googleapis'）; const oauth2client = new Google.auth.oauth2（
your_client_id，
your_client_secret，
your_redirect_url）; //将auth设置为全局defaultgoogle.options（{{
auth：oauth2client}）;您还可以在服务级别设置身份验证客户端，而不是全球设置该选项：
const {google} = require（'googleapis'）; const oauth2client = new Google.auth.oauth2（
your_client_id，
your_client_secret，
your_redirect_url）; const drive = google..drive（{
版本：'v2'，
auth：oauth2client}）;有关更多信息，请参见“选项”部分。
请求的正文在请求的requestBody Body参数对象中指定。主体被指定为具有键/值对的JavaScript对象。例如，此示例创建了一个观察者，该观察者将电子邮件发送到Gmail帐户时，向Google Cloud Pub/sub主题发布通知：
const res =等待gmail.users.watch（{{
用户：“我”，
requestBody：{//用`projects/$ {project_id}/topics/$ {topic_name}替换
}}）; console.log（res.data）;该客户端支持多部分媒体上传。资源参数在requestBody参数对象中指定，并且媒体本身在media.body中指定。Body参数用Mime-type在media.mimeType中指定的。
此示例将纯文本文件上传到Google驱动器，其中标题为“测试”和内容“ Hello World”。
const drive = google..drive（{
版本：'v3'，
auth：oauth2client}）; const res =等待drive.files.create（{
RequestBody：{name：'test'，mimeType：'text/plain'
}，，
媒体：{mimeType：'text/plain'，身体：'Hello world'
}}）;您还可以通过将media.body指定为可读流来上传媒体。这可以使您可以上传非常大的文件，这些文件无法适应内存。
const fs = require（'fs'）; const drive = google..drive（{
版本：'v3'，
auth：oauth2client}）; async函数main（）{
const res =等待drive.files.create（{requestBody：{name：'testimage.png'，mimeType：'image/png'}，媒体：{mimeType：'image/png'，身体：fs.createreaterream（'很棒（'很棒） .png'）}}
}）;
console.log（res.data）;} main（）。catch（console.error）;有关使用媒体附件的创建和修改请求的更多示例，请查看samples/drive/upload.js示例。
为了对您的API调用如何进行更微调的控制，我们为您提供了指定可以直接应用于此库中使用的“ Gaxios”对象的其他选项，以对API进行网络调用。
您可以在全局google对象或服务客户端中指定其他选项。您指定的选项附加到gaxios对象上，因此无论gaxios支持什么，该库支持。您还可以指定将附加到所有API呼叫的全局或服务请求参数。
可以在此处找到支持选项的完整列表。
您可以选择每个请求将发送的默认选项。这些选项将用于Google客户端实例化的每个服务。在此示例中，将为每个请求设置GaxiosOptions的timeout属性：
const {google} = require（'googleapis'）; google.options（{
//除非覆盖，否则使用此对象提出的所有请求将使用这些设置。
超时：1000，
auth：auth}）;您还可以通过每个请求修改发送的参数：
const {google} = require（'googleapis'）; google.options（{
//所有服务中的所有请求都将包含上述查询参数
//除非在服务客户端或单个API调用中覆盖。
参数：{quotauser：'[email protected]'
}}）;创建服务客户端时，您还可以指定选项。
const blogger = google.blogger（{
版本：'v3'，
//使用此对象提出的所有请求将使用指定的auth。
auth：'api键';}）;通过这样做，使用此服务客户端进行的每个API调用都将使用'API KEY'来验证。
注意：创建的客户端是不可变的，因此如果要指定不同的选项，则必须创建一个新客户。
与上面的示例类似，您还可以修改给定服务的每个呼叫的参数：
const blogger = google.blogger（{
版本：'v3'，
//此服务客户端提出的所有请求将包含
// Blogid查询参数，除非在各个API调用中覆盖。
参数：{blogid：'3213900'
}}）; //使用此驱动器客户端的呼叫将不包含blogid Query参数。constdrive = google..drive（'v3'）; ...您可以根据请求指定要使用的auth对象。每个请求还继承了在服务级别和全局级别指定的选项。
例如：
const {google} = require（'googleapis'）; const bigquery = google.bigquery（'v2'）; async函数main（）{
//此方法寻找gcloud_project和google_application_credentials
//环境变量。
const auth = new google.auth.googleauth（{scopes：['https://www.googleapis.com/auth/cloud-platform']
}）;
const authclient =等待auth.getClient（）;
const projectID =等待auth.getProjectId（）;
const request = {projectid，datasetId：'<your_dataset_id>'，//这是“ request-level” optionauth：authclient
};
const res =等待bigquery.datasets.delete（request）;
console.log（res.data）;} main（）。catch（console.error）;您还可以根据请求覆盖Gaxios选项，例如url ， method和responseType 。
例如：
const res =等待drive.files.export（{{
fileid：'asxkjod9s79'，// Google Doc
mimeType：'application/pdf'}，{
//确保我们获取二进制数据
响应类型：'stream'}）;您可以使用以下环境变量来代理HTTP和HTTPS请求：
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
设置HTTP_Proxy / HTTP_Proxy时，它们将用于代理没有明确代理配置选项的非SSL请求。同样，对于没有明确代理配置选项的SSL请求，将尊重HTTPS_Proxy / HTTPS_PROXY。在环境变量之一中定义代理是有效的，然后使用代理配置选项将其覆盖以作为特定请求覆盖。
您可以通过编程方式获取受支持的API的列表，以及所有可用版本：
const {google} = require（'googleapis'）; const apis = google.getSupportedApis（）;这将返回以API名称为对象属性名称的对象，以及一个版本字符串作为对象值的数组；
该库用打字稿编写，并提供开箱即用的类型。为每个API生成的所有类和接口都在${apiName}_${version}名称空间下导出。例如，驱动器V3 API类型都可以从drive_v3名称空间中获得：
进口 {
Google，//用于访问服务的顶级对象
drive_v3，//对于每个服务客户端，都有一个导出的名称空间
auth，//相关类型的名称空间
common，//整个库中使用的常规类型}来自'googleapis''; //注意：使用``auth.googleauth''之类的显式类型仅用于//用于演示目的。 通常，使用Typescript，这些类型将//被推断。
版本：'v3'，
auth，}）; // // //每组请求parametersconst listParams有生成类型：drive_v3.params $ resource $ files $ list $ list = {}; const res = eagait drive.files.list.list（listParams）; //有生成的生成响应字段的类型以及wellconst listreSults：drive_v3.schema $ filelist = res.data;该库支持HTTP/2。要启用它，请使用http2选项在任何地方接受请求参数：
const {google} = require（'googleapis'）; google.options（{
http2：true，}）;HTTP/2通常更具性能，因为它允许在单个插座上多路复用多个并发请求。在传统的HTTP/2 API中，客户直接负责打开和关闭提出请求的会话。 为了保持与现有API的兼容性，该模块将自动重新使用现有会话，该会话是在空转500ms后收集的。 在批处理样式工作负载和紧密的循环中，大部分性能增长将是可见的。
您可以在我们的发行说明中找到破坏更改和新功能的详细列表。如果您在25.x之前使用了此库，请参见我们的发行说明，以了解有关将代码从24.xx迁移到25.xx这很容易:)
该库是根据Apache 2.0许可的。完整的许可文本可在许可证中使用。
我们喜欢贡献！在提交拉动请求之前，首先从新问题开始总是很好。要了解更多信息，请参阅贡献。
在Stackoverflow上询问与开发相关的问题。
如果您找到了错误/问题，请在Github上提交。
