google api nodejs client
v0.1.0
Клиентская библиотека Node.js для использования Google API. Включена поддержка авторизации и аутентификации с OAuth 2.0, API -ключами и токенами JWT.
Google API
Начиная
Установка
Использование клиентской библиотеки
Образцы
Ссылка на API
Аутентификация и разрешение
Oauth2 клиент
Используя клавиши API
Приложение по умолчанию
Учетные данные об услугах
Установка глобального или уровня обслуживания
Использование
Указание корпуса запроса
СМИ загружается
Запросить параметры
Используя прокси
Поддерживается API
Машинопись
Http/2
Лицензия
Внося
Вопросы/проблемы?
Полный список поддерживаемых API можно найти в Google APIS Explorer. Конечные точки API автоматически генерируются, поэтому, если API нет в списке, в настоящее время он не поддерживается этой клиентской библиотекой API.
При использовании API Google Cloud Platform Platform, таких как DataStore, облачное хранилище или паб/sub, рекомендуется использовать клиентские библиотеки @Google-Cloud. Эти библиотеки являются специально построенными, идиоматическими клиентами Node.js, разработанными для конкретных сервисов Google Cloud Platform. Мы рекомендуем установить отдельные пакеты API, такие как @google-cloud/storage . Чтобы изучить всеобъемлющий список пакетов Google Cloud Platform Platform Platform, пожалуйста, см.
Эти клиентские библиотеки официально поддерживаются Google. Тем не менее, эти библиотеки считаются завершенными и находятся в режиме обслуживания. Это означает, что мы будем решать критические ошибки и проблемы безопасности, но не добавим никаких новых функций. Для API Google Cloud Platform Platform мы рекомендуем использовать Google-Cloud-Node, который находится в активной разработке.
Эта библиотека поддерживает обслуживание LT, активные LTS и текущий выпуск Node.js. Смотрите график выпуска Node.js для получения дополнительной информации.
Эта библиотека распространяется на npm . Чтобы добавить его в качестве зависимости, запустите следующую команду:
$ npm установить GoogleApis
Если вам нужно сократить время запуска, вы можете альтернативно установить подмодуль в качестве собственной зависимости. Мы прилагаем усилия, чтобы опубликовать подмодули, которых нет в этом списке. Чтобы добавить его в качестве зависимости, запустите следующую команду образца, заменив на ваш предпочтительный API:
$ npm install @googleapis/docs
Вы можете запустить этот поиск на npm , чтобы найти список доступных подмодулей.
Это очень простой пример. Это создает клиента блоггера и получает подробную информацию о блоге, учитывая идентификатор блога:
const {Google} = require ('GoogleApis'); // Каждый API может поддерживать несколько версий. С помощью этого образца мы получаем // v3 API Blogger и используем ключ API для аутентификации. Const Blogger = Google.blogger ({{{{{{{{{{{
Версия: 'v3',
auth: 'your api key'}); const params = {
BlogId: '3213900'}; // Получить блог detailsblogger.blogs.get (params, (err, res) => {
if (err) {console.error (err); dish err;
}
console.log (`url блога $ {res.data.url}`);});Вместо использования обратных вызовов вы также можете использовать обещания!
blogger.blogs.get (params)
.then (res => {console.log (`url блога $ {res.data.url}`);
})
.catch (error => {console.error (error);
});Или асинхронно/ждать:
Async function runSample () {
const res = await 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'ty });; const ayclient = await auth.getclient (); const client = await docs.docs ({version:' v1 ', authclient }); const createresponse = await client.documents.create ({requestbody: {title: 'Ваш новый документ!',},}); console.log (createresponse.data);Есть много образцов? Если вы пытаетесь выяснить, как использовать API ... сначала посмотрите! Если есть образец, который вам нужен, не стесняйтесь подать проблему.
Эта библиотека имеет полный набор справочной документации API. Эта документация создана автоматически, и местоположение может измениться.
Есть несколько способов аутентификации в Google API. Некоторые услуги поддерживают все методы аутентификации, в то время как другие могут поддерживать только один или два.
OAuth2 - Это позволяет вам делать вызовы API от имени данного пользователя. В этой модели пользователь посещает ваше приложение, подписывает свою учетную запись Google и предоставляет ваше приложение авторизацию против набора областей. Узнать больше.
Ключ API - с помощью ключа API вы можете получить доступ к вашей службе от клиента или сервера. Как правило, менее безопасно, это доступно только на небольшом подмножестве услуг с ограниченными областями. Узнать больше.
Учетные данные по умолчанию по умолчанию - предоставляет автоматический доступ к API Google с использованием Google Cloud SDK для локальной разработки или сервера GCE Metadata для приложений, развернутых на платформе Google Cloud. Узнать больше.
Учетные данные учетной записи службы - В этой модели ваше приложение напрямую общается с API Google с помощью учетной записи службы. Это полезно, когда у вас есть бэкэнд -приложение, которое будет говорить напрямую с API Google из бэкэнда. Узнать больше.
Чтобы узнать больше о клиенте аутентификации, см. Библиотеку Google Auth.
Этот модуль поставляется с клиентом OAuth2, который позволяет вам получить токен доступа, обновить его и беспрепятственно повторить запрос. Основы реализации Google OAuth2 объясняются в документации по авторизации Google и аутентификации.
В следующих примерах вам может понадобиться CLIENT_ID , CLIENT_SECRET и REDIRECT_URL . Вы можете найти эти фрагменты информации, перейдя на консоли разработчика, щелкнув ваш проект -> APIS & Auth -> учетные данные.
Перейдите к облачной консоли и создайте новый идентификатор клиента OAuth2
Выберите Web Application для типа приложения
Добавьте авторизованный redirect uri со значением http://localhost:3000/oauth2callback (или применимое значение для вашего сценария)
Нажмите Create и Ok на следующем экране
Щелкните значок Download рядом с недавно созданным идентификатором клиента OAuth2
Обязательно храните этот файл в безопасном месте и не проверяйте этот файл в управлении источником!
Для получения дополнительной информации о 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 Scopesconst Scopes = [
'https://www.googleapis.com/auth/blogger',
'https://www.googleapis.com/auth/calendar'];const url = oauth2client.generateauthurl ({
// 'Online' (по умолчанию) или «офлайн» (Gets Refresh_token)
access_type: 'offline',
// Если вам нужна только один пример, вы можете передать его как строку
Применение: области}); Важное примечание - refresh_token возвращается только на первом разрешении. Подробнее здесь.
После того, как пользователь дал разрешения на странице согласия, Google перенаправляет страницу на URL -адрес перенаправления, который вы предоставили с помощью параметра запроса кода.
GET /oauthcallback?code={authorizationCode}С возвращенным кодом вы можете попросить токен доступа, как показано ниже:
// Это предоставит объект с помощью Access_token и refresh_token.// Сохранить их где -то безопасно, чтобы их можно было использовать в более позднее время. Const {tokens} = await oauth2client.getToken (code) oauth2client.setcredentials (tokens);С учетными данными, установленными на вашем клиенте OAuth2 - вы готовы к работе!
Доступ токенов истекает. Эта библиотека автоматически использует токен обновления для получения нового токена доступа, если он собирается истекать. Простой способ убедиться, что вы всегда храните самые последние жетоны, - это использовать событие tokens :
oauth2client.on ('tokens', (tokens) => {
if (tokens.refresh_token) {// хранить represh_token в моей базе данных! Консоль.log (tokens.refresh_token);
}
console.log (tokens.access_token);}); Это событие токенов происходит только в первом авторизации, и вам необходимо установить свой access_type на offline при вызове метода generateAuthUrl для получения токена обновления. Если вы уже предоставили своему приложению необходимые разрешения без установки соответствующих ограничений для получения токена обновления, вам нужно будет повторно создать приложение, чтобы получить свежий токен обновления. Вы можете отозвать доступ к своей учетной записи.
Чтобы установить refresh_token позже, вы можете использовать метод setCredentials :
oauth2client.setcredentials ({
refresh_token: `stordord_refresh_token`});После того, как у клиента появится токен обновления, доступные токены будут приобретены и автоматически обновляться при следующем вызове API.
Токены обновления могут перестать работать после того, как они будут предоставлены, либо потому, что:
Пользователь отменил доступ вашего приложения
Токен обновления не использовался в течение 6 месяцев
Пользователь изменил пароли, а токен обновления содержит Gmail Scopes
Учетная запись пользователя превысила максимальное количество токенов в прямом эфире
Приложение имеет статус «тестирования», а экран согласия настроен для внешнего типа пользователя, что приводит к истечению срок действия токена через 7 дней
Как разработчик, вы должны написать свой код, чтобы справиться с тем, когда токен обновления больше не работает.
Вам может потребоваться отправить ключ API по запросу, который вы собираетесь сделать. Следующее использует ключ API, чтобы сделать запрос в службу API Blogger, чтобы получить имя блога, URL и общее количество сообщений:
const {Google} = require ('GoogleApis'); const blogger = Google.blogger_v3 ({
Версия: 'v3',
auth: 'your_api_key' // укажите свой клавиш API здесь}); const params = {
BlogId: '3213900'}; асинхронная функция main (params) {
const res = await blogger.blogs.get ({blogid: params.blogid});
console.log (`$ {res.data.name} имеет $ {res.data.posts.totalitems} posts! URL блога $ {res.data.url}`)}; main (). Catch (консоль. ошибка);Чтобы узнать больше о ключах API, см. Документацию.
Вместо того, чтобы вручную создавать клиента OAuth2, клиент JWT или вычислять клиент, библиотека Auth может создать для вас правильный тип учетных данных, в зависимости от среды, под которым работает ваш код.
Например, клиент JWT Auth будет создан, когда ваш код будет запущен на вашем локальном машине разработчика, а клиент Compute будет создан, когда тот же код будет запущен в настроенном экземпляре Google Compute Engine. Приведенный ниже код показывает, как получить тип учетных данных по умолчанию, в зависимости от среды выполнения.
Чтобы использовать учетные данные по умолчанию локально с Google Cloud SDK, запустите:
$ gcloud Auth Auth Application Default
При запуске в GCP Service Authorize автоматически предоставляется через сервер GCE Metadata.
const {Google} = require ('googleapis'); const compute = Google.compute ('v1'); Async function main () {
const auth = new Google.auth.googleauth ({// Scopes можно указать либо как массив, либо в виде единого, распределенного пространства string.scopes: ['https://www.googleapis.com/auth/compute']
});
const autlient = await auth.getClient ();
// Получить текущий идентификатор проекта
const project = await auth.getProjectId ();
// Извлекать список зон GCE в рамках проекта.
const res = await compute.zones.list ({project, auth: autlient});
console.log (res.data);} main (). Catch (console.error);Учетные записи услуг позволяют выполнять аутентификацию на уровне приложений с использованием учетной записи робота. Вы создадите учетную запись службы, загрузите файл ключа и используете ее для аутентификации в Google API. Для создания учетной записи службы:
Перейдите на страницу ключа Create Service Account
Выберите New Service Account в выпадении
Нажмите кнопку Create
Сохраните файл учетных данных Service Account где -нибудь в безопасности, и не проверяйте этот файл в управление источником ! Чтобы ссылаться на файл учетных данных Service, у вас есть несколько вариантов.
GOOGLE_APPLICATION_CREDENTIALS env var Вы можете начать процесс с переменной среды с именем GOOGLE_APPLICATION_CREDENTIALS . Значение этого Env Var должно быть полным путем к файлу учетных данных учетной записи службы:
$ Google_application_credentials =./Your-secret-key.json node server.js
keyFile В качестве альтернативы, вы можете указать путь к файлу учетной записи учетной записи службы через свойство keyFile в конструкторе 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'],}); Вы можете установить 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 запроса. Корпус указан как объект JavaScript с парами ключей/значения. Например, этот образец создает наблюдателя, который публикует уведомления в паб Google Cloud Pub/Sub Topic, когда электронные письма отправляются в учетную запись Gmail:
const res = ждать gmail.users.watch ({
userId: «я»,
requestBody: {// заменить на `projects/$ {project_id}/thepics/$ {topic_name}` topicname: `projects/el-gato/thepics/gmail`
}}); console.log (res.data); Этот клиент поддерживает загрузки Multipart Media. Параметры ресурса указаны в объекте параметра requestBody , и сама среда указана в параметре media.body С помощью MIME-типа, указанного в media.mimeType .
Этот пример загружает простой текстовый файл в Google Drive с заголовком «Тест» и содержимое «Hello World».
const drive = Google.Drive ({
Версия: 'v3',
auth: oauth2client}); const res = await drive.files.create ({
Запрос Cody: {name: 'test', mimeType: 'text/plain'
},
Media: {mimeType: 'text/plain', body: «Привет, мир»
}}); Вы также можете загрузить носитель, указав media.body как читаемый поток. Это может позволить вам загружать очень большие файлы, которые не могут вписаться в память.
const fs = require ('fs'); const drive = google.drive ({
Версия: 'v3',
auth: oauth2client}); async function 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); Для получения дополнительных примеров запросов на создание и модификации с помощью вложений носителя, взгляните на образцы samples/drive/upload.js .
Для более тонкого контроля над тем, как выполняются ваши вызовы API, мы предоставляем вам возможность указать дополнительные параметры, которые могут быть применены непосредственно к объекту «Gaxios», используемому в этой библиотеке, чтобы сделать сетевые вызовы в API.
Вы можете указать дополнительные параметры в глобальном объекте google или на основе обслуживания. Указанные вами параметры прикреплены к объекту gaxios , поэтому любая поддержка gaxios поддерживает, эта библиотека поддерживает. Вы также можете указать глобальные параметры запроса или запроса на услуги, которые будут прикреплены ко всем вызовам API, которые вы делаете.
Полный список поддерживаемых вариантов можно найти здесь.
Вы можете выбрать параметры по умолчанию, которые будут отправлены с каждым запросом. Эти параметры будут использоваться для каждой службы, созданной клиентом Google. В этом примере свойство timeout GaxiosOptions будет установлено для каждого запроса:
const {Google} = require ('GoogleApis'); Google.options ({
// Все запросы, сделанные с этим объектом, будут использовать эти настройки, если не переопределены.
Тайм -аут: 1000,
auth: auth});Вы также можете изменить параметры, отправленные с каждым запросом:
const {Google} = require ('GoogleApis'); Google.options ({
// Все запросы из всех служб будут содержать вышеуказанный параметр запроса
// Если не переопределяется ни в сервисном клиенте, ни в отдельных вызовах API.
PARAMS: {QUATAUSER: '[email protected]'
}});Вы также можете указать параметры при создании сервисного клиента.
const blogger = Google.blogger ({
Версия: 'v3',
// Все запросы, сделанные с помощью этого объекта, будут использовать указанную AUTH.
auth: 'api -ключ';}); Делая это, каждый вызов API, выполненный с этим сервисным клиентом, будет использовать 'API KEY' для аутентификации.
Примечание. Созданные клиенты неизменны , поэтому вы должны создать новый, если вы хотите указать разные параметры.
Аналогично примерам выше, вы также можете изменить параметры, используемые для каждого вызова данной службы:
const blogger = Google.blogger ({
Версия: 'v3',
// все запросы, сделанные с этим сервисным клиентом
// Параметр запроса BlogID, если не переопределяется в отдельных вызовах API.
Params: {blogyid: '3213900'
}}); // вызовы с этим дипломом клиент не будет содержать параметр запроса blogid.const Drive = Google.Drive ('v3'); ... Вы можете указать объект auth , который будет использоваться в соответствии с запросом. Каждый запрос также наследует опции, указанные на уровне обслуживания и глобального уровня.
Например:
const {google} = require ('googleapis'); const bigquery = Google.bigquery ('v2'); Async function main () {
// Этот метод ищет gcloud_project и google_application_credentials
// переменные среды.
const auth = new Google.auth.googleauth ({scopes: ['https://www.googleapis.com/auth/cloud-platform']
});
const autlient = await auth.getClient ();
const projectId = await auth.getProjectId ();
const request = {projectId, dataSetid: '<your_dataset_id>', // Это "level-level" OptionAuth: Authclient
};
const res = ждать bigquery.datasets.delete (запрос);
console.log (res.data);} main (). Catch (console.error); Вы также можете переопределить параметры Gaxios по запросу, такие как url , method и responseType .
Например:
const res = await drive.files.export ({
FileId: 'asxkjod9s79', // Google Doc
MimeType: 'Application/pdf'}, {
// Убедитесь, что мы получаем двоичные данные
responseType: 'Stream'});Вы можете использовать следующие переменные среды для прокси -запросов HTTP и HTTPS:
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
При установке HTTP_PROXY / HTTP_PROXY они будут использоваться для прокси-не-SSL-запросов, которые не имеют явной опции конфигурации прокси. Аналогичным образом, HTTPS_PROXY / HTTPS_PROXY будет уважаться для запросов SSL, которые не имеют явной опции конфигурации прокси. Это действительно определить прокси в одной из переменных среды, но затем переопределить его для конкретного запроса, используя опцию конфигурации прокси.
Вы можете программно получить список поддерживаемых API и все доступные версии:
const {Google} = require ('GoogleApis'); const apis = Google.getSupportEdapis ();Это вернет объект с именем API в качестве имен объекта и массивом строк версий в качестве значений объекта;
Эта библиотека написана в TypeScript и предоставляет типы из коробки. Все классы и интерфейсы, сгенерированные для каждого API, экспортируются в соответствии с ${apiName}_${version} пространство имен. Например, все типы API Drive V3 доступны в пространстве имен drive_v3 :
Импорт {
Google, // объект верхнего уровня, используемый для доступа к службам
Drive_v3, // Для каждого клиента службы есть экспортируемое пространство имен
Auth, // Пространство имен для типов, связанных с аутами
Общие, // Общие типы, используемые по всей библиотеке} из «GoogleApis»; // Примечание. Использование явных типов, таких как `auth.googleauth`, представляют собой только здесь для // демонстрационных целей. Как правило, с помощью TypeScript эти типы // были выведены. Const Auth: auth.googleauth = new Google.auth.googleauth (); const drive: drive_v3.drive = google.drive ({{{{{{{{{{{{{{{{{{{
Версия: 'v3',
Auth,}); // Существуют сгенерированные типы для каждого набора запросов parametersconst listparams: drive_v3.params $ resource $ files $ list = {}; const res = await drive.files.list (listparams); // Сгенерированы Типы для полей ответа, как и Listresults: drive_v3.schema $ filelist = res.data; Эта библиотека имеет поддержку HTTP/2. Чтобы включить его, используйте параметры http2 в любом месте. Параметры запроса приняты:
const {Google} = require ('GoogleApis'); Google.options ({
http2: true,});HTTP/2 часто более эффективен, так как позволяет мультиплексирование нескольких параллельных запросов через одну розетку. В традиционном API HTTP/2 клиент непосредственно отвечает за открытие и закрытие сеансов, сделанных для выполнения запросов. Чтобы поддерживать совместимость с существующим API, этот модуль автоматически повторно использует существующие сеансы, которые собираются после холостого хода на 500 мс. Большая часть повышения производительности будет видна в рабочей нагрузке в партийном стиле и узких петлях.
Вы можете найти подробный список разбитых изменений и новых функций в наших примечаниях. Если вы использовали эту библиотеку до 25.x , см. Наши заметки о выпуске, чтобы узнать о переносе вашего кода с 24.xx до 25.xx Это довольно легко :)
Эта библиотека лицензирована в соответствии с Apache 2.0. Полный текст лицензии доступен в лицензии.
Мы любим вклад! Перед тем, как отправить запрос на привлечение, всегда полезно сначала начать с новой проблемы. Чтобы узнать больше, см. Вклад.
Задайте ваши вопросы, связанные с разработкой, на Stackoverflow.
Если вы нашли ошибку/проблему, пожалуйста, подайте ее на GitHub.
