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上提交。
