google api nodejs client
v0.1.0
Biblioteca de clientes Node.js para usar o Google APIs. Suporte à autorização e autenticação com OAuth 2.0, as chaves da API e os tokens JWT estão incluídos.
Google APIs
Começando
Instalação
Usando a biblioteca do cliente
Amostras
Referência da API
Autenticação e autorização
Cliente OAuth2
Usando teclas de API
Credenciais padrão do aplicativo
Credenciais da conta de serviço
Definindo autenticação global ou de nível de serviço
Uso
Especificando o corpo de solicitação
Uploads de mídia
Opções de solicitação
Usando um proxy
APIs suportadas
TypeScript
Http/2
Licença
Contribuindo
Perguntas/problemas?
A lista completa de APIs suportadas pode ser encontrada no Google APIS Explorer. Os terminais da API são gerados automaticamente; portanto, se a API não estiver na lista, ela não será suportada por esta biblioteca de clientes da API.
Ao utilizar as APIs do Google Cloud Platform, como DataStore, Cloud Storage ou Pub/Sub, é aconselhável aproveitar as bibliotecas de clientes @google-cloud. Essas bibliotecas são clientes Node.JS de Node.js, criados para propósitos, projetados para serviços específicos do Google Cloud Platform. Recomendamos a instalação de pacotes de API individuais, como @google-cloud/storage . Para explorar uma lista abrangente de pacotes específicos da plataforma do Google Cloud, consulte https://cloud.google.com/nodejs/docs/reference.
Essas bibliotecas de clientes são oficialmente suportadas pelo Google. No entanto, essas bibliotecas são consideradas completas e estão no modo de manutenção. Isso significa que abordaremos bugs críticos e problemas de segurança, mas não adicionaremos novos recursos. Para as APIs da plataforma do Google Cloud, recomendamos o uso do Google-Cloud Node, que está em desenvolvimento ativo.
Esta biblioteca suporta os LTs de manutenção, LTS ativo e lançamento atual do Node.JS. Consulte o cronograma de lançamento do Node.js para obter mais informações.
Esta biblioteca está distribuída no npm . Para adicioná -lo como uma dependência, execute o seguinte comando:
$ npm install googleapis
Se você precisar reduzir os horários de inicialização, pode instalar alternativamente um submódulo como sua própria dependência. Fazemos um esforço para publicar submódulos que não estão nesta lista. Para adicioná -lo como uma dependência, execute o seguinte comando de amostra, substituindo pela sua API preferida:
$ npm install @googleapis/docs
Você pode executar essa pesquisa no npm , para encontrar uma lista dos submódulos disponíveis.
Este é um exemplo muito simples. Isso cria um cliente do blogueiro e recupera os detalhes de um blog, dado o ID do blog:
const {google} = requer ('googleapis'); // cada API pode suportar várias versões. Com esta amostra, estamos obtendo // v3 da API do Blogger e usando uma chave da API para autenticar.const blogger = google.blogger ({
versão: 'v3',
Auth: 'Your Api Key'}); const params = {
BlogId: '3213900'}; // Obtenha o blog Dethetalhesblogger.blogs.get (params, (err, res) => {
if (err) {console.error (err); lança err;
}
console.log (`O url do blog é $ {res.data.url}`);});Em vez de usar retornos de chamada, você também pode usar promessas!
blogger.blogs.get (params)
.Then (res => {console.log (`O url do blog é $ {res.data.url}`);
})
.catch (error => {console.error (erro);
});Ou assíncrono/aguardar:
função assíncrona runSample () {
const Res = Await blogger.blogs.get (params);
console.log (`O url do blog é $ {res.data.url}`);} runSample (). Catch (console.error);Como alternativa, você pode fazer chamadas diretamente para as APIs instalando um submódulo:
const docs = requer ('@googleapis/docs') const auth = new docs.auth.googleauth ({
keyfilename: 'path_to_service_account_key.json', // escopos podem ser especificados como uma matriz ou como uma única string delimitada espacial.
Escopos: ['https://www.googleapis.com/auth/documents'bem- }) ;const authclient = aguart auth.getclient (); const client = wait Docs.docs ({versão:' v1 ', auth: authclient }); const creeaterSponse = Await client.documents.create ({requestbody: {title: 'Seu novo documento!',},}); console.log (createresponse.data);Existem muitas amostras? Se você está tentando descobrir como usar uma API ... olhe lá primeiro! Se houver uma amostra que você precisar, fique à vontade para apresentar um problema.
Esta biblioteca possui um conjunto completo de documentação de referência da API. Esta documentação é gerada automaticamente e o local pode mudar.
Existem várias maneiras de se autenticar para o Google APIs. Alguns serviços suportam todos os métodos de autenticação, enquanto outros podem suportar apenas um ou dois.
OAuth2 - Isso permite fazer chamadas de API em nome de um determinado usuário. Neste modelo, o usuário visita seu aplicativo, assina a conta do Google e fornece à sua aplicativo autorização contra um conjunto de escopos. Saber mais.
Chave da API - Com uma chave da API, você pode acessar seu serviço de um cliente ou do servidor. Normalmente menos seguro, isso só está disponível em um pequeno subconjunto de serviços com escopos limitados. Saber mais.
Credenciais padrão do aplicativo - fornece acesso automático às APIs do Google usando o Google Cloud SDK para desenvolvimento local ou o servidor de metadados GCE para aplicativos implantados na plataforma do Google Cloud. Saber mais.
Credenciais da conta de serviço - Neste modelo, seu aplicativo fala diretamente com o Google APIs usando uma conta de serviço. É útil quando você possui um aplicativo de back -end que converse diretamente com as APIs do Google do back -end. Saber mais.
Para saber mais sobre o cliente de autenticação, consulte a biblioteca do Google Auth.
Este módulo vem com um cliente OAuth2 que permite recuperar um token de acesso, atualizar e tentar novamente a solicitação sem problemas. O básico da implementação do OAuth2 do Google é explicado na documentação de autorização e autenticação do Google.
Nos exemplos a seguir, você pode precisar de um CLIENT_ID , CLIENT_SECRET e REDIRECT_URL . Você pode encontrar essas informações indo ao console do desenvolvedor, clicando em seu projeto -> APIs & Auth -> Credenciais.
Navegue até o console da nuvem e crie um novo ID do cliente OAuth2
Selecione Web Application para o tipo de aplicativo
Adicione um URI de redirecionamento autorizado com o valor http://localhost:3000/oauth2callback (ou valor aplicável para o seu cenário)
Clique em Create e Ok na tela seguinte
Clique no ícone Download ao lado do seu recém -criado ID do cliente OAuth2
Certifique -se de armazenar esse arquivo em lugar seguro e não verifique esse arquivo no controle de origem!
Para mais informações sobre o OAuth2 e como funciona, consulte aqui.
Um aplicativo de amostra completo que autoriza e autentica com o cliente OAuth2 está disponível em samples/oauth2.js .
Para solicitar permissões de um usuário para recuperar um token de acesso, você as redireciona para uma página de consentimento. Para criar um URL da página de consentimento:
const {google} = requer ('googleapis'); const oauth2client = novo google.auth.oauth2 (
Your_client_id,
Your_client_secret,
Your_redirect_url); // gerar um URL que pede permissões para o blogger e o Google Calendar ScopoSconst Scopes = [
'https://www.googleapis.com/auth/blogger',
'https://www.googleapis.com/auth/calendar';
// 'Online' (padrão) ou 'offline' (Gets Refresh_token)
access_type: 'offline',
// Se você precisar apenas de um escopo, pode passar como uma string
escopo: escopos}); Nota importante - o refresh_token é retornado apenas na primeira autorização. Mais detalhes aqui.
Depois que um usuário tiver permissões na página de consentimento, o Google redirecionará a página para o URL de redirecionamento que você forneceu com um parâmetro de consulta de código.
GET /oauthcallback?code={authorizationCode}Com o código retornado, você pode pedir um token de acesso como mostrado abaixo:
// Isso fornecerá a um objeto o access_token e o refresh_token.// salvará -los em algum lugar seguro para que eles possam ser usados posteriormente.
Com as credenciais definidas no seu cliente OAuth2 - você está pronto para ir!
Tokens de acesso expirar. Esta biblioteca usará automaticamente um token de atualização para obter um novo token de acesso, se estiver prestes a expirar. Uma maneira fácil de garantir que você sempre armazene os tokens mais recentes é usar o evento tokens :
OAuth2Client.on ('Tokens', (tokens) => {
if (tokens.refresh_token) {// armazenar o refresh_token no meu banco de dados! console.log (tokens.refresh_token);
}
console.log (tokens.access_token);}); Este evento de tokens ocorre apenas na primeira autorização e você precisa definir seu access_type como offline ao chamar o método generateAuthUrl para receber o token de atualização. Se você já forneceu ao seu aplicativo as permissões necessárias sem definir as restrições apropriadas para receber um token de atualização, precisará re-autorizar o aplicativo para receber um novo token de atualização. Você pode revogar o acesso do seu aplicativo à sua conta aqui.
Para definir o refresh_token posteriormente, você pode usar o método setCredentials :
OAuth2Client.SetCredentials ({
refresh_token: `armazenado_refresh_token`});Depois que o cliente tiver um token de atualização, os tokens de acesso serão adquiridos e atualizados automaticamente na próxima chamada para a API.
Os tokens de atualização podem parar de funcionar depois de receberem, seja porque:
O usuário revogou o acesso do seu aplicativo
O token de atualização não foi usado há 6 meses
O usuário alterou as senhas e o token de atualização contém escopos de Gmail
A conta de usuário excedeu um número máximo de tokens de atualização ao vivo
O aplicativo tem um status de 'teste' e a tela de consentimento é configurada para um tipo de usuário externo, fazendo com que o token expire em 7 dias
Como desenvolvedor, você deve escrever seu código para lidar com o caso em que um token de atualização não está mais funcionando.
Pode ser necessário enviar uma chave da API com a solicitação que você fará. O seguinte usa uma chave da API para fazer uma solicitação ao Serviço de API do Blogger para recuperar o nome de um blog, URL e sua quantidade total de postagens:
const {google} = requer ('googleapis'); const blogger = google.blogger_v3 ({
versão: 'v3',
Auth: 'your_api_key' // Especifique sua chave da API aqui}); const params = {
BlogId: '3213900'}; função assíncrona main (params) {
const Res = Await blogger.blogs.get ({blogId: params.blogid});
console.log (`$ {res.data.name} possui $ {res.data.posts.totalitems} postagens! O url do blog é $ {res.data.url}`)}; main (). Catch (console. erro);Para saber mais sobre as teclas da API, consulte a documentação.
Em vez de criar manualmente um cliente OAuth2, cliente JWT ou cliente de computação, a Biblioteca de Auth pode criar o tipo de credencial correto para você, dependendo do ambiente em que seu código estiver em execução.
Por exemplo, um cliente de autenticação JWT será criado quando seu código estiver em execução na máquina de desenvolvedor local e um cliente de computação será criado quando o mesmo código estiver em execução em uma instância configurada do Google Compute Engine. O código abaixo mostra como recuperar um tipo de credencial padrão, dependendo do ambiente de tempo de execução.
Para usar as credenciais padrão do aplicativo localmente com o Google Cloud SDK, Run:
$ GCLOUD AUTH APLICACE-APPERACE-PEFAULT LOGIN
Ao executar no GCP, o Serviço Authorize é fornecido automaticamente através do servidor de metadados GCE.
const {google} = requer ('googleapis'); const compute = google.compute ('v1'); função assíncrona main () {
const auth = new google.auth.googleauth ({// escopos pode ser especificado como uma matriz ou como um único string.scopes de delimitados espaciais: ['https://www.googleapis.com/auth/compute']
});
const authclient = aguardar auth.getClient ();
// Obtenha o ID do projeto atual
const Project = aguart auth.getProjectId ();
// busca a lista de zonas GCE dentro de um projeto.
const Res = Await Compute.Zones.List ({Project, Auth: Authclient});
console.log (res.data);} main (). Catch (console.error);As contas de serviço permitem que você execute a autenticação de nível de servidor para servidor, usando uma conta de robô. Você criará uma conta de serviço, baixará um keyfile e o usará para autenticar para o Google APIs. Para criar uma conta de serviço:
Vá para a página Chave da conta Create Service
Selecione New Service Account na suspensão
Clique no botão Create
Salve o arquivo de credencial da conta de serviço em algum lugar seguro e não verifique esse arquivo no controle de origem ! Para fazer referência ao arquivo de credencial da conta de serviço, você tem algumas opções.
GOOGLE_APPLICATION_CREDENTIALS Env var Você pode iniciar o processo com uma variável de ambiente chamada GOOGLE_APPLICATION_CREDENTIALS . O valor desse Env var deve ser o caminho completo para o arquivo de credencial da conta de serviço:
$ Google_application_credentials =./Yoursecret-key.json node server.js
keyFile Como alternativa, você pode especificar o caminho para o arquivo de credencial da conta de serviço por meio da propriedade keyFile no construtor GoogleAuth :
const {google} = requer ('googleapis'); const auth = new google.auth.googleauth ({
keyfile: '/path/to/your-secret-key.json',
escopos: ['https://www.googleapis.com/auth/cloud-platform'],}); Você pode definir o auth como uma opção global ou de nível de serviço para não precisar especificá-la todas as solicitações. Por exemplo, você pode definir auth como uma opção global:
const {google} = requer ('googleapis'); const oauth2client = novo google.auth.oauth2 (
Your_client_id,
Your_client_secret,
Your_redirect_url); // Defina a autenticação como um Global DefaultGoogle.Options ({
Auth: OAuth2Client});Em vez de definir a opção globalmente, você também pode definir o cliente de autenticação no nível de serviço:
const {google} = requer ('googleapis'); const oauth2client = novo google.auth.oauth2 (
Your_client_id,
Your_client_secret,
Your_redirect_url); const drive = google.drive ({
versão: 'v2',
Auth: OAuth2Client});Consulte a seção de opções para obter mais informações.
O corpo da solicitação é especificado no objeto de parâmetro de requestBody da solicitação. O corpo é especificado como um objeto JavaScript com pares de chave/valor. Por exemplo, esta amostra cria um observador que publica notificações em um pub/sub tópico do Google Cloud quando os emails são enviados para uma conta do Gmail:
const res = aguarda gmail.users.watch ({
UserID: 'eu',
requestbody: {// substitua por `Projects/$ {Project_id}/tópicos/$ {tópico_name}` tópicoName: `Projects/el-gato/tópicos/gmail`
}}); console.log (res.data); Este cliente suporta uploads de mídia multipart. Os parâmetros do recurso são especificados no objeto Parâmetro requestBody , e a própria mídia é especificada no parâmetro media.mimeType media.body .
Este exemplo carrega um arquivo de texto sem formatação para o Google Drive com o título "Teste" e o conteúdo "Hello World".
const drive = google.drive ({
versão: 'v3',
Auth: OAuth2Client}); const res = Await drive.files.create ({
Solicitação de corpo: {Nome: 'Test', Mimetype: 'Texto/Plano'
},
Mídia: {Mimetype: 'Text/Plain', Body: 'Hello World'
}}); Você também pode fazer upload de mídia especificando media.body como um fluxo legível. Isso pode permitir que você faça upload de arquivos muito grandes que não podem se encaixar na memória.
const fs = requer ('fs'); const drive = google.drive ({
versão: 'v3',
Auth: Oauth2Client}); Função assíncrona main () {
const res = aguait drive.files.create ({requestbody: {name: 'testimage.png', mimeType: 'image/png'}, mídia: {Mimetype: 'image/png', corpo: fs.creteadstream ('impressionante .png ')}
});
console.log (res.data);} main (). Catch (console.error); Para obter mais exemplos de solicitações de criação e modificação com anexos de mídia, consulte a amostra samples/drive/upload.js .
Para um controle mais ajustado sobre como suas chamadas de API são feitas, fornecemos a capacidade de especificar opções adicionais que podem ser aplicadas diretamente ao objeto 'gaxios' usado nesta biblioteca para fazer chamadas de rede para a API.
Você pode especificar opções adicionais no objeto global google ou em um cliente de serviço. As opções que você especifica são anexadas ao objeto gaxios , para que o que gaxios suporta, esta biblioteca suporta. Você também pode especificar parâmetros de solicitação global ou por serviço que serão anexados a todas as chamadas de API que você faz.
Uma lista completa de opções suportadas pode ser encontrada aqui.
Você pode escolher opções padrão que serão enviadas com cada solicitação. Essas opções serão usadas para cada serviço instanciado pelo Google Client. Neste exemplo, a propriedade timeout das GaxiosOptions será definida para cada solicitação:
const {google} = requer ('googleapis'); google.options ({
// Todas as solicitações feitas com este objeto usarão essas configurações, a menos que seja substituído.
Tempo limite: 1000,
Auth: auth});Você também pode modificar os parâmetros enviados com cada solicitação:
const {google} = requer ('googleapis'); google.options ({
// Todas as solicitações de todos os serviços conterão o parâmetro de consulta acima
//, a menos que seja substituído em um cliente de serviço ou em chamadas individuais da API.
params: {cotaUser: '[email protected]'
}});Você também pode especificar opções ao criar um cliente de serviço.
const blogger = google.blogger ({
versão: 'v3',
// Todas as solicitações feitas com este objeto usarão a autenticação especificada.
Auth: 'API Key';}); Ao fazer isso, todas as chamadas da API feitas com este cliente de serviço usarão 'API KEY' para autenticar.
NOTA: Os clientes criados são imutáveis , portanto, você deve criar um novo se desejar especificar opções diferentes.
Semelhante aos exemplos acima, você também pode modificar os parâmetros usados para cada chamada de um determinado serviço:
const blogger = google.blogger ({
versão: 'v3',
// Todas as solicitações feitas com este cliente de serviço conterão o
// O parâmetro de consulta blogid, a menos que seja substituído em chamadas individuais da API.
Params: {blogId: '3213900'
}}); // chamadas com este cliente Drive não conterá o parâmetro de consulta blogid.CONST Drive = Google.Drive ('V3'); ... Você pode especificar um objeto auth a ser usado por solicitação. Cada solicitação também herda as opções especificadas no nível de serviço e no nível global.
Por exemplo:
const {google} = requer ('googleapis'); const bigquery = google.bigquery ('v2'); função assíncrona main () {
// Este método procura o gcloud_project e o google_application_credentials
// variáveis de ambiente.
const auth = novo google.auth.googleauth ({scopes: ['https://www.googleapis.com/auth/cloud-platform']
});
const authclient = aguardar auth.getClient ();
const ProjectId = aguart auth.getProjectId ();
const request = {projectId, DataSETID: '<your_dataset_id>', // é uma opção de "solicitação-nivelada": authclient
};
const res = aguart bigquery.datasets.delete (solicitação);
console.log (res.data);} main (). Catch (console.error); Você também pode substituir as opções Gaxios por solicitação, como url , method e responseType .
Por exemplo:
const res = aguarda drive.files.export ({
FileId: 'ASXKJOD9S79', // Um Google Doc
Mimetype: 'Application/pdf'}, {
// Verifique se obtemos os dados binários
ResponseType: 'stream'});Você pode usar as seguintes variáveis de ambiente para procurar solicitações HTTP e HTTPS:
HTTP_PROXY / http_proxy
HTTPS_PROXY / https_proxy
Quando http_proxy / http_proxy estiverem definidos, eles serão usados para proxy solicitações não-SSL que não possuem uma opção de configuração de proxy explícita presente. Da mesma forma, https_proxy / https_proxy será respeitado pelas solicitações SSL que não possuem uma opção de configuração de proxy explícita. É válido definir um proxy em uma das variáveis de ambiente, mas substituí -la para uma solicitação específica, usando a opção de configuração de proxy.
Você pode obter programaticamente a lista de APIs suportadas e todas as versões disponíveis:
const {google} = requer ('googleapis'); const apis = google.getSupportedapis ();Isso retornará um objeto com o nome da API como nomes de propriedades do objeto e uma matriz de strings de versão como valores do objeto;
Esta biblioteca está escrita no TypeScript e fornece tipos fora da caixa. Todas as classes e interfaces geradas para cada API são exportadas sob o espaço de nome ${apiName}_${version} . Por exemplo, os tipos de API da unidade V3 estão todos disponíveis no espaço de nome drive_v3 :
importar {
Google, // o objeto de nível superior usado para acessar serviços
drive_v3, // para cada cliente de serviço, há um espaço para nome exportado
Auth, // namespace para tipos relacionados de autenticação
Comum, // Tipos gerais usados em toda a biblioteca} de 'Googleapis'; // Nota: Usando tipos explícitos como `auth.googleauth` estão aqui apenas para // fins de demonstração. Geralmente com o TypeScript, esses tipos seriam inferidos.
versão: 'v3',
auth,}); // Existem tipos gerados para todos os conjuntos de parâmetros de solicitação listParams: drive_v3.params $ resource $ arquivos $ list = {}; const res = wait drive.files.list (listParams); // são gerados Tipos para os campos de resposta como listresults: drive_v3.schema $ filelist = res.data; Esta biblioteca tem suporte para HTTP/2. Para ativá -lo, use a opção http2 em qualquer lugar que os parâmetros de solicitação sejam aceitos:
const {google} = requer ('googleapis'); google.options ({
http2: true,});O HTTP/2 geralmente é mais executado, pois permite a multiplexação de múltiplas solicitações simultâneas em um único soquete. Em uma API HTTP/2 tradicional, o cliente é diretamente responsável por abrir e fechar as sessões feitas para fazer solicitações. Para manter a compatibilidade com a API existente, este módulo reutilizará automaticamente as sessões existentes, que são coletadas após 500 ms. Muitos dos ganhos de desempenho serão visíveis em cargas de trabalho em estilo em lote e loops apertados.
Você pode encontrar uma lista detalhada de mudanças de quebra e novos recursos em nossas notas de lançamento. Se você usou esta biblioteca antes de 25.x , consulte nossas notas de lançamento para aprender sobre a migração de seu código de 24.xx para 25.xx É muito fácil :)
Esta biblioteca está licenciada no Apache 2.0. O texto completo da licença está disponível na licença.
Adoramos contribuições! Antes de enviar uma solicitação de tração, é sempre bom começar com um novo problema primeiro. Para saber mais, consulte contribuindo.
Faça suas perguntas relacionadas ao desenvolvimento no StackOverflow.
Se você encontrou um bug/problema, registre -o no Github.
