1. Como usar as APIs do Google Workspace
Este codelab apresenta o uso das APIs RESTful baseadas em HTTP do Google Workspace (antigo G Suite). O exemplo será feito em Python por brevidade e disponibilidade, mas você também pode usar sua linguagem de desenvolvimento favorita. Você vai conhecer tópicos introdutórios, como usar o console do desenvolvedor para criar/gerenciar projetos, conseguir credenciais de autorização e instalar as bibliotecas de cliente da API. Depois de cuidar das formalidades, você vai escrever um app para mostrar os cem primeiros arquivos e pastas no seu Google Drive usando a API dele.
O que você vai aprender
- Criar um projeto usando o console de desenvolvedores do Google/Cloud
- Receber e usar credenciais de aplicativo OAuth2 no seu app
- Saiba como usar as bibliotecas de cliente das APIs do Google
- Escrever aplicativos usando as APIs do Google e do Google Workspace
- Receber informações de arquivos e pastas com a API Google Drive
O que é necessário
- Acesso à Internet e a um navegador da Web
- Uma Conta do Google (as contas do Google Workspace podem exigir a aprovação do administrador).
- Familiaridade com sistemas compatíveis com POSIX, como Linux e Mac OS X
- Capacidade de criar arquivos de origem com um editor de código ou comandos do shell.
- Habilidades básicas em Python (2 ou 3), mas você pode usar qualquer linguagem compatível
- Alguns arquivos e/ou pastas no seu Google Drive
2. Pesquisa
Como você vai usar este tutorial do codelab?
Como você classificaria sua experiência com as ferramentas e APIs para desenvolvedores do Google Workspace?
3. Visão geral
Neste codelab, você vai aprender a:
- Baixar a biblioteca de cliente de APIs do Google para Python
- Crie um projeto no Google/Cloud Developers Console.
- Receber as credenciais necessárias para seu app
- Use essas credenciais para acessar a API Google Drive.
Se preferir não usar Python, implemente o codelab na sua ferramenta de desenvolvimento favorita. As bibliotecas de cliente das linguagens compatíveis estão disponíveis aqui. Consulte os exemplos em Python como pseudocódigo executável.
4. Confirmar ambiente Python
Esse codelab requer o uso da linguagem Python (embora muitas linguagens sejam compatíveis pelas bibliotecas cliente das APIs do Google, portanto, sinta-se à vontade para criar algo equivalente em sua ferramenta de desenvolvimento favorita e simplesmente usar o Python como pseudocódigo). Esse codelab é compatível com o Python 2 e 3, mas recomendamos migrar para o 3.x assim que possível.
O Cloud Shell é uma conveniência disponível para usuários diretamente no console do Cloud e não requer um ambiente de desenvolvimento local. Portanto, este tutorial pode ser feito na nuvem com um navegador da Web. O Cloud Shell será útil principalmente se você estiver desenvolvendo ou planejando continuar com os produtos e as APIs do GCP. Mais especificamente para este codelab, o Cloud Shell já instalou as duas versões do Python.
O Cloud Shell também tem o IPython instalado... é um interpretador Python interativo de nível superior que recomendamos, especialmente se você fizer parte da comunidade de ciência de dados ou machine learning. Se você estiver, o IPython é o interpretador padrão para o Jupyter Notebooks e o Colab, os notebooks do Jupyter hospedados pelo Google Research.
O IPython favorece um interpretador do Python 3 primeiro, mas retorna para o Python 2, caso 3.x não esteja disponível. O IPython pode ser acessado no Cloud Shell, mas também pode ser instalado em um ambiente de desenvolvimento local. Saia com ^D (Ctrl-d) e aceite a oferta para sair. A saída de exemplo de ipython terá esta aparência:
$ ipython Python 3.7.3 (default, Mar 4 2020, 23:11:43) Type 'copyright', 'credits' or 'license' for more information IPython 7.13.0 -- An enhanced Interactive Python. Type '?' for help. In [1]:
Se IPython não for sua preferência, o uso de um interpretador interativo padrão do Python (o Cloud Shell ou seu ambiente de desenvolvimento local) é perfeitamente aceitável (também saia com ^D):
$ python Python 2.7.13 (default, Sep 26 2018, 18:42:22) [GCC 6.3.0 20170516] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> $ python3 Python 3.7.3 (default, Mar 10 2020, 02:33:39) [GCC 6.3.0 20170516] on linux Type "help", "copyright", "credits" or "license" for more information. >>>
O codelab também pressupõe que você tenha a ferramenta de instalação pip (gerenciador de pacotes Python e resolvedor de dependências). Ele vem com as versões 2.7.9 ou superiores ou 3.4+. Se você tiver uma versão mais antiga do Python, consulte este guia para ver instruções de instalação. Dependendo das suas permissões, talvez seja necessário ter sudo ou acesso de superusuário, mas esse não é o caso. Também é possível usar explicitamente pip2 ou pip3 para executar pip para versões específicas do Python.
O restante do codelab considera que você está usando o Python 3. Instruções específicas serão fornecidas para o Python 2 se forem muito diferentes de 3.x.
*Crie e use ambientes virtuais
Esta seção é opcional e só é necessária para as pessoas que devem usar um ambiente virtual para este codelab (conforme a barra lateral de aviso acima). Se você tiver apenas o Python 3 no seu computador, basta emitir este comando para criar um virtualenv chamado my_env (você pode escolher outro nome, se quiser):
virtualenv my_env
No entanto, se você tiver o Python 2 e o 3 no computador, recomendamos instalar um virtualenv Python 3, que você pode fazer com o -p flag da seguinte maneira:
virtualenv -p python3 my_env
Insira o virtualenv recém-criado "ativando" assim:
source my_env/bin/activate
Para confirmar que você está no ambiente, observe que o prompt do shell agora está precedido pelo nome do seu ambiente, ou seja,
(my_env) $
Agora, você deverá ser capaz de pip install quaisquer pacotes necessários, executar o código nessa e assim por diante etc. Outro benefício é que, se você expuser o conteúdo completamente, entrar em uma situação em que a instalação do Python esteja corrompida etc., poderá explodir esse ambiente inteiro sem afetar o restante do sistema.
5. Instalar a biblioteca de cliente de APIs do Google para Python
Esse codelab requer o uso da biblioteca de cliente de APIs do Google para Python. Portanto, é um processo de instalação simples ou você não precisa fazer nada.
Recomendamos que você use o Cloud Shell por conveniência. É possível concluir todo o tutorial em um navegador da Web na nuvem. Outro motivo para usar o Cloud Shell é que muitas ferramentas de desenvolvimento conhecidas e as bibliotecas necessárias já estão pré-instaladas.
Instalar bibliotecas de cliente
(opcional): é possível pular essa etapa se você estiver usando o Cloud Shell ou um ambiente local onde já instalou as bibliotecas de cliente. Só será necessário fazer isso se você estiver desenvolvendo localmente e não tiver instalado (ou tiver certeza). A maneira mais fácil é usar pip (ou pip3) para fazer a instalação (incluindo a atualização de pip se necessário):
pip install -U pip google-api-python-client oauth2client
Confirmar instalação
Esse comando instala a biblioteca de cliente e os pacotes de que ela depende. Se você está usando o Cloud Shell ou seu próprio ambiente, verifique se a biblioteca de cliente está instalada importando os pacotes necessários e confirme se não há erros de importação (ou saída):
python3 -c "import googleapiclient, httplib2, oauth2client"
Se você usar o Python 2 no Cloud Shell, verá um aviso de que o uso dele foi suspenso:
******************************************************************************* Python 2 is deprecated. Upgrade to Python 3 as soon as possible. See https://cloud.google.com/python/docs/python2-sunset To suppress this warning, create an empty ~/.cloudshell/no-python-warning file. The command will automatically proceed in seconds or on any key. *******************************************************************************
Agora que você pode executar o comando "test" de importação (sem erros/saída), estará pronto para começar a falar com as APIs do Google.
Resumo
Como este é um codelab introdutório, presumimos que você não tem experiência com as APIs do Google e do Google Workspace. Se você já tem experiência em criar projetos e autorização de usuários "IDs de cliente OAuth". Se sim, crie ou reutilize um projeto e um ID do cliente OAuth. Depois, pule os dois módulos seguintes e vá direto para "Como mostrar seu aplicativo de arquivos e pastas do Drive" ou para "Uso avançado do devconsole" para revisar essas etapas com menos orientação.
6. Especificar o projeto no console do Cloud
Um aplicativo que usa as APIs do Google precisa de um projeto. Eles são gerenciados no console de desenvolvedores do Google Cloud ou simplesmente "devconsole". Neste codelab, vamos usar apenas a API Google Drive. Por isso, temos um link mágico (abaixo, na etapa 1) que:
- Leva você ao devconsole
- Mostra como criar um projeto (ou escolher um existente) e
- Ativa automaticamente a API Drive
Vamos lá!
- Acesse console.developers.google.com/start/api?id=drive e faça login na sua Conta do Google.
- Se você ainda não tiver projetos, vai aparecer esta tela para aceitar os Termos de Serviço das APIs do Google:
Depois que você aceitar os termos, um novo projeto chamado "Meu projeto" será criado, e a API Drive será ativada automaticamente. 3. Se você já criou um projeto (talvez no codelab anterior?), esta tela vai aparecer: 
. Ao clicar no menu suspenso Criar um projeto, escolha um projeto atual ou crie um novo. 
Depois de fazer sua seleção (projeto novo ou atual), a API Drive será ativada automaticamente para você. 4. Você vai saber que a API Drive foi ativada com esta confirmação: 
5. Clique em Acessar credenciais para ir para a próxima etapa.
7. *Autorizar solicitações de API (autorização do usuário)
Você pode pular esta seção se já tiver criado as credenciais de autorização da conta de usuário e estiver familiarizado com o processo. Isso é diferente da autorização da conta de serviço cuja técnica é diferente. Continue abaixo.
Introdução à autorização (além de alguma autenticação)
Para fazer solicitações às APIs, seu aplicativo precisa ter a autorização adequada. Autenticação, uma palavra semelhante, descreve credenciais de login. Você se autentica ao fazer login na sua Conta do Google com um login e uma senha. Após a autenticação, a próxima etapa é seu código é autorizado para acessar dados, como arquivos blob no Cloud Storage ou os arquivos pessoais de um usuário no Google Drive.
As APIs do Google permitem vários tipos de autorização, mas o mais comum para os usuários da API Google Workspace é a autorização do usuário, porque o aplicativo de exemplo neste codelab acessa dados pertencentes a usuários finais. Esses usuários finais precisam permitir que seu app acesse os dados. Isso significa que seu código precisa receber as credenciais do OAuth2 da conta de usuário.
Para obter as credenciais do OAuth2 para autorização do usuário, volte para o gerenciador de API e selecione a guia "Credenciais" no painel de navegação à esquerda:
Quando chegar lá, você verá todas as suas credenciais em três seções separadas:
O primeiro é para chaves de API, os dois IDs de cliente do OAuth 2.0 e as últimas contas de serviço do OAuth2,que são usadas no do meio.
Como criar credenciais
Na página "Credenciais", clique no botão + Criar credenciais na parte superior. Você verá uma caixa de diálogo em que escolheria "ID do cliente OAuth":
Na tela seguinte, você tem duas ações: configurar a "tela de consentimento" de autorização do seu aplicativo e escolher o tipo de aplicativo:
Se você não definiu uma tela de consentimento, verá o aviso no console e precisará fazer isso agora. (Ignore esta etapa se a tela de consentimento já tiver sido configurada.)
Tela de permissão OAuth
Clique em "Configurar tela de permissão" onde você seleciona um app "Externo" (ou "Interno", se você for cliente do Google Workspace [antigo "Google Workspace"]):
Para este exercício, não importa qual você escolher, porque você não está publicando seu exemplo de codelab. A maioria das pessoas seleciona a opção "Externo" para acessar uma tela mais complexa. No entanto, você só precisa preencher o campo "Nome do aplicativo" na parte superior:
Agora, você só precisa do nome de um aplicativo. Escolha alguém que reflita o codelab que você está fazendo e clique em Salvar.
Como criar um ID do cliente OAuth (autenticação de conta de usuário)
Volte para a guia "Credenciais" para criar um ID do cliente do OAuth2. Aqui você verá vários IDs de cliente OAuth que podem ser criados:
Estamos desenvolvendo uma ferramenta de linha de comando, que é Outro. Portanto, escolha essa opção e clique no botão Criar. Escolha o nome de um ID de cliente que reflita o aplicativo que você está criando ou simplesmente use o nome padrão, que geralmente é "Outro cliente N".
Salvar suas credenciais
- Será exibida uma caixa de diálogo com as novas credenciais. Clique em OK para fechar.
- Na página "Credenciais", role para baixo até a seção "IDs de cliente do OAuth2" e clique no ícone de download
, na parte inferior direita do seu ID do cliente recém-criado.
- Isso abre uma caixa de diálogo para salvar um arquivo chamado
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, provavelmente na pasta Downloads. Recomendamos encurtar para um nome mais fácil, comoclient_secret.json, que é o que o app de exemplo usa. Em seguida, salve-o no diretório/pasta em que você criará o app de amostra neste codelab.
Resumo
Com as credenciais em mãos, você já pode acessar a API Drive no seu app. Não se esqueça de que o objetivo do ID do cliente OAuth é que os usuários concedam permissão ao seu app para acessar os dados deles no Google Drive.
NOTE: mais detalhes sobre como criar projetos, ativar APIs e conseguir credenciais manualmente, ou seja, sem usar o "assistente" acima, estão disponíveis após a conclusão deste codelab para estudo adicional.
8. Mostrando o aplicativo de arquivos e pastas do Drive
No ambiente de desenvolvimento local ou no Cloud Shell, no mesmo diretório em que o arquivo de credenciais client_id.json está localizado, crie um arquivo Python chamado drive_list.py e adicione as linhas de código abaixo:
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
Estrutura do aplicativo
Há três seções principais neste aplicativo:
- Importações do Python para trazer a funcionalidade da biblioteca
- Como conseguir credenciais de aplicativos
- Buscar e mostrar nomes de arquivos e pastas e MIMEtypes no Google Drive do usuário.
NOTE: uma análise mais detalhada do código e uma explicação linha por linha estão disponíveis após a conclusão deste codelab para estudo adicional.
Como executar o aplicativo
Nomeie esse arquivo como drive_list.py. Na primeira vez que você executar o script, ele não terá autorização para acessar os arquivos do usuário no Google Drive. O resultado será assim com a execução pausada:
$ python3 ./drive_list.py /usr/local/lib/python3.6/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Your browser has been opened to visit: https://accounts.google.com/o/oauth2/auth?client_id=LONG-STRING.apps.googleusercontent.com&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2F&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Do ambiente de desenvolvimento local
O script de linha de comando é pausado quando uma janela do navegador é aberta e apresenta a caixa de diálogo de permissões do OAuth2:
É aqui que o aplicativo pede ao usuário as permissões que o código está solicitando (pela variável SCOPES). Nesse caso, ele pode visualizar os metadados do arquivo no Google Drive do usuário. Sim, no seu código, esses escopos de permissão aparecem como URIs, mas são traduzidos para o idioma especificado pela sua localidade na janela de diálogo do fluxo OAuth2. O usuário precisa conceder autorização explícita para as permissões solicitadas. Caso contrário, a parte "run flow" do código vai gerar uma exceção, e o script não vai prosseguir.
NOTE: alguns usuários têm vários navegadores, e a solicitação de autorização pode aparecer em um navegador não preferencial. Se for esse o caso, copie todo o URL da janela do navegador que você não quer usar e cole na barra de endereço de um navegador que você quer usar.
No Cloud Shell
Se você não prestou atenção e executou o programa no Cloud Shell, nenhuma janela do navegador foi aberta, deixando você travado. Na parte inferior, você recebeu esta mensagem de diagnóstico:
If your browser is on a different machine then exit and re-run this application with the command-line parameter --noauth_local_webserver
Ao executá-lo dessa forma, você receberá a seguinte resposta:
$ python3 drive_list.py --noauth_local_webserver /usr/local/lib/python3.7/site-packages/oauth2client/_helpers.py:255: UserWarning: Cannot access storage.json: No such file or directory warnings.warn(_MISSING_FILE_MESSAGE.format(filename)) Go to the following link in your browser: https://accounts.google.com/o/oauth2/auth?client_id=xxx.apps.googleusercontent.com&redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.readonly.metadata&access_type=offline&response_type=code Enter verification code:
Seguindo as instruções e acessando outra guia do navegador com esse URL, você terá uma experiência quase idêntica à descrita acima para ambientes de desenvolvimento local. A principal diferença está no final, quando você recebe mais uma tela com o código de verificação para inserir no Cloud Shell:
Recorte e cole esse código na janela do terminal.
Resumo
Depois que o usuário clicar em "Permitir" e/ou o código de verificação for colado no prompt, o app vai (continuar) sendo executado. Portanto, espere ver uma saída com arquivos/pastas do Drive e seus MIMEtypes. Confira um exemplo de uma das nossas contas de teste:
$ python3 ./drive_list.py Travel expenses application/vnd.google-apps.spreadsheet Gmail Add-ons codelab application/vnd.google-apps.script Google Workspace Developer Intro application/vnd.google-apps.presentation Baseball Sheets application/vnd.google-apps.folder My Resume application/vnd.google-apps.document . . .
Observe que, em execuções sucessivas, não será mais necessário pedir autorização, já que ela foi armazenada em cache pelas bibliotecas de autenticação, e você vai direto para a saída. Não é incrível ver seus documentos em um terminal pela primeira vez? Acreditamos que sim.
9. Conclusão
Agora você pode aprender mais recursos da API Google Drive ou conhecer outras APIs do Google Workspace (Gmail, Documentos, Planilhas, Apresentações, Agenda) e do Google (Maps, Analytics, YouTube etc.). Parabéns por chegar até o fim!
O código apresentado neste codelab também está disponível no repositório do GitHub em github.com/googlecodelabs/gsuite-apis-intro. Procuramos manter este codelab sincronizado com o repositório. Quer continuar? Confira abaixo diversos recursos que você pode acessar para se aprofundar no assunto deste codelab ou desafiar sua mente e explorar outras maneiras de acessar as tecnologias do Google programaticamente.
Como já mencionamos, se você não é um desenvolvedor Python regular, refaça este exemplo de codelab na sua linguagem de desenvolvimento favorita. As bibliotecas de cliente para linguagens compatíveis estão disponíveis aqui.
Estudo adicional
Agora que você já tem alguma experiência com a API Drive, confira alguns exercícios recomendados para desenvolver ainda mais suas habilidades:
- Arquivos ZIP: escreva um aplicativo que faça backup de vários arquivos ZIP no Drive, descompactando-os na hora para que cada nome de arquivo ZIP seja o nome da pasta em que esses arquivos serão armazenados. CRÉDITO EXTRA: compatibilidade com arquivos ZIP recursivos dentro de outros arquivos ZIP com pastas do Drive incorporadas em outras pastas. Se você desistir, consulte este app de exemplo do Node.js.
- Álbuns de fotos: escreva o início de uma ferramenta de geração de álbuns de fotos que faz upload de várias imagens para o Google Drive, organizando-as em pastas separadas por carimbo de data/hora e geolocalização. EXTRA: encontre uma biblioteca de manipulação de imagens de código aberto e junte todas as fotos em cada pasta para representar eventos que você pode ter vivido (uma viagem, um jantar etc.).
- Conheça o GCP: escreva um app que conecte o Google Workspace e o Google Cloud Platform (GCP). Escreva uma ferramenta que faça backup de arquivos de imagem do Google Drive para o Google Cloud Storage (GCS), outra solução de "armazenamento de arquivos na nuvem". Acredite se quiser, usar o GCS é mais simples do que o Drive devido às bibliotecas de cliente avançadas.
- Analisar e gravar: estenda sua solução para a etapa 3 analisando cada imagem salva em backup. Para isso, transmita a imagem para a API Cloud Vision do Google e receba os principais rótulos (3, 5, 10) do que a API Cloud Vision vê nessas imagens. Para cada imagem, escreva uma linha em uma planilha Google contendo a análise do Cloud Vision e o local de backup no GCS. Se você desistir, consulte este codelab do Python.
10. Outros recursos
Documentação
- Documentação da API Google Drive (API REST e SDK/API nativo do Android)
- Documentação de outras APIs do Google Workspace
- Documentação de outras APIs do Google
- Bibliotecas de cliente das APIs do Google
- Documentação do OAuth2
Vídeos relacionados e gerais
- Como criar projetos da API Google ( postagem do blog e vídeo)
- Revisão de código boilerplate de autorização do Python ( vídeo)
- Listar seus arquivos no Google Drive ( vídeo, postagem do blog)
- Biblioteca de vídeos da API Google Drive
- Série de vídeos Launchpad Online (anterior)
- Série de vídeos Google Workspace Dev Show
Notícias e atualizações
- Blog dos desenvolvedores do Google Workspace
- Twitter dos desenvolvedores do Google Workspace (@GSuiteDevs)
- Newsletter mensal para desenvolvedores do Google Workspace
Outros codelabs
Básico
- [Apps Script] Introdução ao Google Apps Script
Intermediário
- [Apps Script] Ferramenta de linha de comando CLASP do Apps Script
- [Apps Script] Complementos do Gmail
- [Apps Script] Complemento do Google Docs e API Natural Language do GCP
- [Apps Script] Estrutura do bot do Hangouts Chat
- [APIs REST] Ferramenta de relatórios personalizados (API Sheets)
- [APIs REST] Gerador de slides personalizados para o analisador do BigQuery de licenças do GitHub (APIs Slides e BigQuery)
Avançado
- [APIs REST] Fluxo de trabalho de processamento de imagens na nuvem (APIs do Drive, Cloud Storage, Cloud Vision e Planilhas)
Apps de referência
- Conversor de Markdown para Apresentações Google (API REST do Apresentações)
11. *Explicação detalhada do aplicativo
Essa seção opcional deve ser usada como autoestudo após o término da sessão para preencher lacunas que possam ter surgido ou para mais pesquisas.
Importações do Python para trazer a funcionalidade da biblioteca
from __future__ import print_function
from googleapiclient import discovery
from httplib2 import Http
from oauth2client import file, client, tools
- A primeira instrução
importpermite que esse código seja executado no Python 2. Ela pode ser totalmente descartada se você estiver usando apenas o Python 3. - Uma diretriz de estilo do Python é separar as importações de bibliotecas padrão e módulos de terceiros. É para isso que serve a linha em branco.
- As três importações a seguir trazem as classes e funções necessárias da biblioteca de cliente das APIs do Google. Todas são necessárias para escrever este app. Em resumo, veja o que elas fazem:
googleapiclientse concentra na conexão com as APIs do Google- O
httplib2fornece um cliente HTTP para o app usar. - O
oauth2clientajuda a gerenciar credenciais OAuth2.
Autorização e como receber credenciais de aplicativos
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
store = file.Storage('storage.json')
creds = store.get()
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
creds = tools.run_flow(flow, store)
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
- As permissões
SCOPESsão as que um app pede ao usuário que o executa. Para manter os dados do usuário seguros, os apps não podem ser executados sem permissão - A prática recomendada é usar as permissões mais restritivas necessárias para o funcionamento do app. Por quê?
- Não é irritante quando um app pede um grande conjunto de permissões ao ser instalado ou executado? Adivinhem? Agora você está do outro lado da moeda, pedindo todas essas permissões aos usuários. Usar escopos mais restritivos faz com que os usuários se sintam mais à vontade para instalar seu app, porque você está pedindo menos acesso.
- A maioria dos escopos parece URLs longos, e o escopo de metadados do Drive não é exceção.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- Um token é necessário para que os apps se comuniquem com os servidores do Google. Os tokens válidos retornados pelo Google serão salvos no arquivo de armazenamento de tokens,
storage.json. Se você não salvar esses tokens, será necessário autorizar o app novamente a cada execução.
store = file.Storage('storage.json')
- Primeiro, o app verifica se já temos credenciais válidas no armazenamento (consulte a condição da instrução
if).
creds = store.get()
if not creds or creds.invalid:
- Se você não tiver credenciais ou elas estiverem expiradas, um novo fluxo de autorização precisará ser criado [via
oauth2client.client.flow_from_clientsecrets()] com base no ID do cliente e no segredo do cliente OAuth no arquivoclient_id.jsonque você baixou.
if not creds or creds.invalid:
flow = client.flow_from_clientsecrets('client_id.json', SCOPES)
- Depois que o app tiver um fluxo, ele precisará ser executado para apresentar a tela de permissões do OAuth2 ao usuário [via
oauth2client.tools.run_flow()], conforme descrito e ilustrado acima.
creds = tools.run_flow(flow, store)
- Ao clicar em Permitir, os usuários consentem que seu app acesse os metadados dos arquivos do Google Drive, e os servidores do Google retornam tokens para acessar a API. Eles são retornados como
credse armazenados em cache no arquivostorage.json. - Neste ponto, seu app tem credenciais válidas para fazer chamadas de API. Chamar
googleapiclient.discovery.build()cria um endpoint de serviço para a API que você está usando. - Para usar
build(), transmita o nome da API ('drive') e a versão desejada (atualmente'v3'). - O parâmetro final é um cliente HTTP a ser usado para chamadas de API criptografadas.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
Buscar e mostrar os primeiros 100 arquivos/pastas do Drive e MIMEtypes
files = DRIVE.files().list().execute().get('files', [])
for f in files:
print(f['name'], f['mimeType'])
- A próxima linha de código chama o método
list()na coleçãofiles()da API Drive para criar a solicitação, que é chamada imediatamente comexecute(). Umdictdo Python é retornado, e pedimos a chave'files'para receber os nomes de 100 arquivos e pastas do Google Drive do usuário (ou menos, se você tiver menos arquivos). - Por que 100? Esse é o padrão do
DRIVE.files().list(). Se você quiser mudar esse número, por exemplo, para apenas 10 arquivos ou 1.000, adicione o parâmetropageSizeà sua solicitação:DRIVE.files().list(pageSize=10). Confira a documentação para mais opções. - A parte final do script faz um loop em cada arquivo e mostra os nomes e os MIMEtypes deles.
Você escreveu seu primeiro aplicativo que usa uma API REST do Google. Parabéns! Além das importações e do código de autorização, esse script é apenas algumas linhas de código (o que você vê acima). A maioria das APIs do Google funciona de maneira semelhante, e você só precisa criar endpoints de serviço para cada uma que quiser usar.
Usar mais de uma API do Google em um app
Sim, você pode usar mais de uma API no mesmo app. Confira um snippet de código Python para um app que reutiliza o mesmo cliente HTTP e cria endpoints de serviço para três APIs do Google (sim, também com três SCOPES diferentes):
SCOPES = (
'https://www.googleapis.com/auth/drive',
'https://www.googleapis.com/auth/spreadsheets.readonly',
'https://www.googleapis.com/auth/presentations',
)
. . .
HTTP = creds.authorize(Http())
DRIVE = discovery.build('drive', 'v3', http=HTTP)
SHEETS = discovery.build('sheets', 'v4', http=HTTP)
SLIDES = discovery.build('slides', 'v1', http=HTTP)
Imaginamos que esse código possa fazer parte de um app que gera várias apresentações (API Slides) com base em dados de planilhas (API Sheets) e usa um modelo de slide copiado (API Drive) para cada apresentação gerada. Embora esse app não exista, você pode criar algo semelhante usando duas amostras criadas pela equipe do Google Workspace como blocos de construção:
- Substituir texto e imagens em slides ( postagem do blog e vídeo): usa a API Drive para copiar um conjunto de modelos de slides e emprega a API Slides para mudar os marcadores de posição de texto e imagem.
- Gerar slides com dados de planilha ( postagem do blog e vídeo): lê dados de uma planilha (API Sheets) e cria slides (API Slides) com base nesses dados.
Seu desafio: criar esse app!
12. *Uso avançado do console de desenvolvimento
Nesta seção opcional, descrevemos como criar projetos no devconsole, ativar APIs e conseguir credenciais, tudo sem usar o assistente, como no codelab acima. Isso é para usuários intermediários que se sentem à vontade para fazer isso manualmente ou querem aprender a fazer.
Especificar o projeto no console do Cloud
Sempre que você escreve um aplicativo usando as APIs do Google, é necessário ter um projeto. Você pode reutilizar um projeto existente ou criar um novo. Isso acontece no console do Cloud. Alguns codelabs oferecem um link mágico (como um assistente de configuração) que permite começar rapidamente, pulando muitas das etapas necessárias. Mas nem todos fazem isso. Portanto, estas são instruções gerais sobre como criar projetos.
É possível criar projetos na maioria das telas do Console do Cloud, desde que você tenha feito login com suas credenciais do Google e veja um menu suspenso de projetos na parte de cima do console. A maioria das capturas de tela aqui são do API Manager, também conhecido como Developers Console. Para acessar, clique em "API Manager" na navegação à esquerda ou aponte o navegador diretamente para console.developers.google.com.
- Se você ainda não tiver projetos, poderá acessar...
- a página Painel:
- a página Biblioteca:
- ou uma página completamente em branco:
. Se isso acontecer com você, atualize o navegador para acessar a página Biblioteca.
- Nas páginas Painel ou Biblioteca, clique no seletor de projetos na parte de cima da página:
- Em seguida, você vai receber a caixa de diálogo do seletor. Clique no "+" à direita para criar um projeto:
- Depois de clicar no "+", a página Novo projeto vai aparecer. Todas as contas pessoais recebem 12 projetos por padrão. Antes de criar seu primeiro projeto, você precisa aceitar os Termos de Serviço das APIs do Google:
Depois disso, as solicitações por e-mail e as perguntas sobre os Termos de Serviço não vão mais aparecer ao criar projetos futuros:
Você criou um projeto e agora pode escolher as APIs que quer usar nele.
ativar as APIs do Google
Antes de começar a usar as APIs do Google, você precisa ativá-las. No exemplo abaixo, mostramos o que você faria para ativar a API Cloud Vision. Neste codelab, você pode estar usando uma ou mais APIs e deve seguir etapas semelhantes para ativá-las antes do uso.
No Cloud Shell
Com o Cloud Shell, é possível ativar a API com o seguinte comando:
gcloud services enable vision.googleapis.com
No Console do Cloud
Você também pode ativar a API Vision no Gerenciador de API. No console do Cloud, acesse o Gerenciador de APIs e selecione "Biblioteca".
Na barra de pesquisa, comece a digitar "vision" e selecione a API Vision quando ela aparecer. Ao digitar, você pode ter esta aparência:
Selecione a API Cloud Vision para acessar a caixa de diálogo que aparece abaixo e clique no botão "Ativar":
Custo
Muitas APIs do Google podem ser usadas sem taxas, mas o uso de GCP (produtos e APIs) não é sem custo financeiro. Ao ativar a API Vision (conforme descrito acima), você será solicitado a fornecer uma conta de faturamento ativa. As informações de preços da API Vision precisam ser referenciadas pelo usuário antes da ativação. Lembre-se de que determinados produtos do Google Cloud Platform (GCP) têm um nível"Sempre sem custo financeiro" que você precisa exceder para incorrer no faturamento. Para os fins do codelab, cada chamada para a API Vision é contabilizada nesse nível sem custo financeiro. Desde que você permaneça dentro dos limites agregados (em cada mês), não haverá cobranças.
Algumas APIs do Google, por exemplo, O Google Workspace tem o uso coberto por uma assinatura mensal, por isso não há cobrança direta para o uso das APIs Gmail, Google Drive, Agenda, Documentos, Planilhas e Apresentações, por exemplo. Diferentes produtos do Google são cobrados de maneira diferente. Portanto, consulte a documentação da sua API para obter essa informação.
Resumo
Neste codelab, você só precisa ativar a API Google Drive. Siga as instruções acima e pesquise "Drive". Continue depois que ele for ativado.
Autorizar solicitações de API (autorização do usuário)
Introdução à autorização (além de alguma autenticação)
Para fazer solicitações às APIs, seu aplicativo precisa ter a autorização adequada. Autenticação, uma palavra semelhante, descreve credenciais de login. Você se autentica ao fazer login na sua Conta do Google com um login e uma senha. Após a autenticação, a próxima etapa é seu código é autorizado para acessar dados, como arquivos blob no Cloud Storage ou os arquivos pessoais de um usuário no Google Drive.
As APIs do Google permitem vários tipos de autorização, mas o mais comum para os usuários da API Google Workspace é a autorização do usuário, porque o aplicativo de exemplo neste codelab acessa dados pertencentes a usuários finais. Esses usuários finais precisam permitir que seu app acesse os dados. Isso significa que seu código precisa receber as credenciais do OAuth2 da conta de usuário.
Para obter as credenciais do OAuth2 para autorização do usuário, volte para o gerenciador de API e selecione a guia "Credenciais" no painel de navegação à esquerda:
Quando chegar lá, você verá todas as suas credenciais em três seções separadas:
O primeiro é para chaves de API, os dois IDs de cliente do OAuth 2.0 e as últimas contas de serviço do OAuth2,que são usadas no do meio.
Como criar credenciais
Na página "Credenciais", clique no botão + Criar credenciais na parte superior. Você verá uma caixa de diálogo em que escolheria "ID do cliente OAuth":
Na tela seguinte, você tem duas ações: configurar a "tela de consentimento" de autorização do seu aplicativo e escolher o tipo de aplicativo:
Se você não definiu uma tela de consentimento, verá o aviso no console e precisará fazer isso agora. (Ignore esta etapa se a tela de consentimento já tiver sido configurada.)
Tela de permissão OAuth
Clique em "Configurar tela de permissão" ao selecionar um app "Externo" (ou "Interno", se você for cliente do Google Workspace):
Para este exercício, não importa qual você escolher, porque você não está publicando seu exemplo de codelab. A maioria das pessoas seleciona a opção "Externo" para acessar uma tela mais complexa. No entanto, você só precisa preencher o campo "Nome do aplicativo" na parte superior:
Agora, você só precisa do nome de um aplicativo. Escolha alguém que reflita o codelab que você está fazendo e clique em Salvar.
Como criar um ID do cliente OAuth (autenticação de conta de usuário)
Volte para a guia "Credenciais" para criar um ID do cliente do OAuth2. Aqui você verá vários IDs de cliente OAuth que podem ser criados:
Estamos desenvolvendo uma ferramenta de linha de comando, que é Outro. Portanto, escolha essa opção e clique no botão Criar. Escolha o nome de um ID de cliente que reflita o aplicativo que você está criando ou simplesmente use o nome padrão, que geralmente é "Outro cliente N".
Salvar suas credenciais
- Será exibida uma caixa de diálogo com as novas credenciais. Clique em OK para fechar.
- Na página "Credenciais", role para baixo até a seção "IDs de cliente do OAuth2" e clique no ícone de download
- Isso abre uma caixa de diálogo para salvar um arquivo chamado
client_secret-LONG-HASH-STRING.apps.googleusercontent.com.json, provavelmente na pasta Downloads. Recomendamos encurtar para um nome mais fácil, comoclient_secret.json, que é o que o app de exemplo usa. Em seguida, salve-o no diretório/pasta em que você criará o app de amostra neste codelab.