1. Como usar as APIs do Google Workspace
Este codelab apresenta as APIs RESTful baseadas em HTTP do Google Workspace (antigo G Suite). O exemplo será feito em Python por questões de brevidade e disponibilidade, mas você também pode usar sua linguagem de desenvolvimento favorita. Você verá tópicos introdutórios, por exemplo, como usar o console do desenvolvedor para criar/gerenciar projetos, obter credenciais de autorização e instalar as bibliotecas de cliente da API. Depois de cuidar das formalidades, você criará um app para exibir os 100 primeiros arquivos e pastas em seu Google Drive usando sua API.
O que você vai aprender
- Criar um projeto usando o Google Developers Console
- Obter e usar as credenciais do OAuth2 no seu app
- Saiba como usar as bibliotecas de cliente das APIs do Google
- Crie aplicativos usando o Google & APIs do Google Workspace
- Acessar 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
- Saber criar arquivos de origem com um editor de código ou comandos do shell.
- Habilidades básicas em Python (2 ou 3), mas é possível 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 para desenvolvedores do Google Workspace? APIs?
3. Visão geral
Neste codelab, você vai aprender a:
- Fazer o download da biblioteca de cliente de APIs do Google para Python
- Criar um novo projeto no Google Developers Console do Google
- Receber as credenciais necessárias para o app
- Use essas credenciais para acessar a API Google Drive.
Se você não quiser usar Python, implemente o codelab na sua ferramenta de desenvolvimento favorita (as bibliotecas de cliente das linguagens com suporte estão disponíveis aqui) e consulte os exemplos de Python como pseudocódigo (executável).
4. Confirmar ambiente Python
Este codelab exige o uso da linguagem Python, embora muitas linguagens tenham suporte (link em inglês) das bibliotecas de cliente das APIs do Google. Você pode criar algo equivalente na 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 exige um ambiente de desenvolvimento local. Portanto, este tutorial pode ser feito completamente na nuvem com um navegador da Web. O Cloud Shell é especialmente útil se você está desenvolvendo ou planeja continuar desenvolvendo com produtos do GCP APIs de terceiros. Mais especificamente para este codelab, o Cloud Shell já instalou as duas versões do Python.
O Cloud Shell também tem o IPython (em inglês) instalado. Ele é um interpretador de Python interativo de nível superior, que recomendamos, principalmente se você fizer parte da comunidade de ciência de dados ou machine learning. Se estiver, o IPython é o intérprete padrão dos Notebooks do Jupyter e do Colab, que são 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 em pacote com as versões 2.7.9+ 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
Este codelab requer o uso da biblioteca de cliente de APIs do Google para Python. Portanto, é um processo de instalação simples ou você pode não precisar fazer nada.
Já sugerimos usar 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 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, você supõe que nunca usou as APIs do Google e do Google Workspace. Caso já tenha experiência na criação de projetos e na criação de "IDs do cliente OAuth" de autorização de usuários. Em caso afirmativo, crie ou reutilize um projeto existente, crie ou reutilize um ID de cliente OAuth e pule os próximos dois módulos e vá direto para "Exibir seus arquivos do Drive e aplicativo de pastas" ou pular até "Uso avançado do devconsole" para revisar essas etapas com menos orientações.
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 Google Cloud Developers Console ou simplesmente em "devconsole". Neste codelab, vamos usar apenas a API Google Drive, então temos um link mágico (abaixo na Etapa 1) que:
- Vai para o devConsole.
- Mostra como criar um novo projeto (ou escolher um já 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, verá esta tela para aceitar os Termos de Serviço das APIs do Google:
Depois que você aceitar os termos, um novo projeto chamado My Project vai ser criado. será criada, e a API Drive será ativada automaticamente. 3. Se, em vez disso, você já tiver criado um projeto (talvez seu codelab anterior?), verá esta tela: 
. Ao clicar no menu suspenso Criar um projeto, escolha um projeto existente ou crie um novo. 
Depois que você selecionar um projeto novo ou existente, a API Drive será ativada automaticamente. 4. Você saberá que a API Drive foi ativada com esta confirmação: 
5. Clique em Acessar credenciais para passar 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 oferecem suporte a vários tipos de autorização, mas o mais comum para usuários da API Google Workspace é a autorização do usuário, porque o aplicativo de exemplo deste codelab acessa dados que pertencem aos 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 consentimento". em que você seleciona uma opção (ou "Interno" se você for um 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.
- De volta à página "Credenciais", role para baixo até "IDs do cliente OAuth2". localize 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. O objetivo do ID do cliente OAuth é que seus usuários precisem conceder permissão ao aplicativo para acessar os próprios dados no Google Drive.
OBSERVAÇÃO: mais detalhes sobre como criar projetos, ativar APIs e receber credenciais manualmente, ou seja, sem usar o "assistente" acima, está disponível após a conclusão deste codelab para estudos mais aprofundados.
8. Exibindo seus arquivos do Google Drive e aplicativo de pastas
No seu 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 novo 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 Python para oferecer a funcionalidade da biblioteca
- Como receber credenciais de aplicativos
- Buscar arquivo e nomes de pastas & Tipos MIME no Google Drive e exibir
OBSERVAÇÃO: uma explicação mais detalhada sobre o código e uma explicação linha por linha estarão disponíveis após a conclusão deste codelab para estudos mais aprofundados.
Como executar o aplicativo
Dê um nome ao 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 enquanto uma janela do navegador é aberta e apresenta a caixa de diálogo de permissões do OAuth2:
É aqui que o aplicativo solicita ao usuário as permissões que o código está solicitando (usando a variável SCOPES). Nesse caso, é a capacidade de visualizar os metadados do arquivo do 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 localidade na janela da caixa de diálogo do fluxo do OAuth2. O usuário precisa dar autorização explícita para as permissões solicitadas. Caso contrário, o "fluxo de execução" do código acionará uma exceção, e o script não prosseguirá.
OBSERVAÇÃO: alguns usuários têm vários navegadores, e a solicitação de autorização pode aparecer em um navegador que não seja o de preferência. Se esse for o caso, basta copiar todo o URL da janela do navegador que você não quer usar e colar na barra de endereço do navegador que você quer usar.
No Cloud Shell
Se você não estava prestando atenção e executou o programa no Cloud Shell, nenhuma janela do navegador se abriu, o que deixou 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 indo para uma guia diferente do navegador com esse URL, você terá uma experiência quase idêntica à descrita acima para ambientes de desenvolvimento locais. A principal diferença está no final, quando você tem mais uma tela com o código de verificação para inserir no Cloud Shell:
Copie e cole esse código na janela do terminal.
Resumo
Quando o usuário clicar em "Permitir" e/ou o código de verificação for colado no comando, o app continuará em execução. Portanto, a saída vai consistir em arquivos/pastas do Drive e os tipos MIME deles. Veja um exemplo de uma de 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 . . .
Nas execuções sucessivas, observe que não é mais solicitada autorização (já que foi armazenada em cache pelas bibliotecas de autenticação) e vai direto para a saída. Não é interessante ver seus documentos em um terminal pela primeira vez? Acreditamos que sim.
9. Conclusão
Agora você já pode conhecer mais recursos sobre a API Drive ou conhecer outros produtos do Google Workspace (Gmail, Documentos, Planilhas, Apresentações, Agenda) e outras APIs 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 (em inglês). Nosso objetivo é manter este codelab sincronizado com o repositório. Quer continuar? Confira abaixo vários recursos que podem ser acessados para ajudar você a se aprofundar mais no material abordado neste codelab ou se quiser alongar a mente e explorar outras maneiras de acessar as tecnologias do Google de maneira programática.
Como indicado anteriormente, se você não for um desenvolvedor regular de Python, 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ê tem alguma experiência com a API Drive, confira abaixo alguns exercícios recomendados para aprimorar ainda mais suas habilidades:
- Arquivos ZIP: crie um aplicativo que faça backup de vários arquivos ZIP no Drive, descompactando-os rapidamente para que cada nome de arquivo ZIP seja o nome da pasta em que esses arquivos estão. CRÉDITO EXTRA: oferece suporte a arquivos ZIP recursivos em outros arquivos ZIP com pastas do Drive incorporadas a outras pastas. Se você desistir, confira este app de amostra 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. geolocalização. EXTRA CRÉDITO: 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ê possa ter passado (uma viagem, um jantar etc.).
- Conheça o GCP: crie um app que conecte o Google Workspace e o Google Cloud Platform (GCP). Escrever uma ferramenta que faz backup de arquivos de imagem do Google Drive para o Google Cloud Storage (GCS), outro "armazenamento de arquivos na nuvem" solução. Acredite se quiser, mas usar o GCS é mais simples do que o Drive por causa das bibliotecas de cliente avançadas.
- Analisar e registro: amplie sua solução para o terceiro ao analisar cada imagem armazenada em backup, transmitindo-a para a API Google Cloud Vision e coletando os principais (3, 5, 10) "rótulos" do que a API vê nessas imagens. Para cada imagem, escreva uma linha em uma planilha Google que contenha a análise do Cloud Vision e o local de backup no GCS. Se você desistir, confira este codelab do Python.
10. Outros recursos
Documentação
- Documentação da API Google Drive (API REST e SDK/API nativo do Android)
- Outras documentação das APIs do Google Workspace
- Outras documentação das APIs do Google
- Bibliotecas de cliente das APIs do Google
- Documentação do OAuth2
Vídeos relacionados e gerais
- Como criar projetos de APIs do Google ( postagem do blog e vídeo)
- Revisão do 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 a...)
- Série de vídeos Google Workspace Dev Show
Notícias e atualizações
- Blog dos desenvolvedores do Google Workspace (em inglês)
- Twitter para desenvolvedores do Google Workspace (@GSuiteDevs)
- Newsletter mensal dos 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 Apps Script CLASP
- [Apps Script] Complementos do Gmail
- [Apps Script] Complemento do Documentos Google e API GCP Natural Language
- [Apps Script] Estrutura do bot do Hangouts Chat
- [APIs REST] Ferramenta de relatórios personalizados (API Sheets)
- [APIs REST] Gerador de slides personalizado para o analisador do BigQuery com licença do GitHub (Apresentações + APIs do BigQuery)
Avançado
- [APIs REST] Fluxo de trabalho de processamento de imagens na nuvem (Drive, Cloud Storage, Cloud Vision, APIs Sheets)
Apps de referência
- Conversor de Markdown para Apresentações Google (API REST Slides)
11. *Explicação detalhada do aplicativo
Esta seção opcional deve ser usada como autoestudo após a conclusão da sessão para preencher eventuais lacunas que possam ter surgido ou para pesquisas adicionais.
Importações Python para oferecer 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 descartada completamente se você estiver usando apenas o Python 3. - Uma diretriz de estilo do Python é separar as importações de módulos de terceiros e a biblioteca padrão. É para isso que serve a linha em branco.
- As próximas três importações trazem as classes e da biblioteca cliente de APIs do Google... todas são necessárias para criarmos este aplicativo. Em resumo, veja o que eles fazem:
- O foco do
googleapiclienté a conexão com as APIs do Google httplib2fornece um cliente HTTP para o app usar.oauth2clientnos ajuda a gerenciar as credenciais do OAuth2
Autorização e recebimento de 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()))
SCOPESsão as permissões que um app solicita ao usuário que o executa. Para proteger os dados do usuário, os apps não podem ser executados sem receber permissão- Uma prática recomendada é usar as permissões mais restritivas necessárias para o funcionamento do app. Por quê?
- Não é irritante quando um aplicativo pede um grande conjunto de permissões ao ser instalado ou executado? Adivinhe. Você está do outro lado da moeda agora e está solicitando todas essas permissões aos seus usuários. O uso de escopos mais restritivos faz com que os usuários se sintam melhor para instalar o app, porque você está solicitando menos acesso.
- A maioria dos escopos parecem URLs longos, e o escopo de metadados do Drive não é exceção.
SCOPES = 'https://www.googleapis.com/auth/drive.readonly.metadata'
- É necessário um token 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 novamente o app sempre que executá-lo.
store = file.Storage('storage.json')
- Primeiro, esse app verifica se já temos credenciais válidas no armazenamento. Consulte a condicional da instrução
if.
creds = store.get()
if not creds or creds.invalid:
- Se você não tem credenciais ou elas expiraram, será necessário criar um novo fluxo de autorização [via
oauth2client.client.flow_from_clientsecrets()] usando seu ID do cliente OAuth e secret no arquivoclient_id.jsonque você transferiu por download].
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 [usando o
oauth2client.tools.run_flow()] descrito e ilustrado acima.
creds = tools.run_flow(flow, store)
- Ao clicar em Permitir, os usuários autorizam o app a acessar os metadados de arquivos do Google Drive, e os servidores do Google retornam tokens para acessar a API. Elas são retornadas como
credse armazenadas em cache no arquivostorage.json. - Neste ponto, o 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 versão desejada (atualmente'v3'). - O parâmetro final é um cliente HTTP usado para chamadas de API criptografadas.
DRIVE = discovery.build('drive', 'v3', http=creds.authorize(Http()))
Buscar e exibir 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()para que a API Drive crie a solicitação, que é chamada imediatamente comexecute(). UmadictPython é retornada de onde pedimos a chave'files'para obter o arquivo 100 e nomes de pasta do Google Drive do usuário (ou menos, se você tiver menos arquivos). - Por que 100? Esse é o padrão de
DRIVE.files().list(). Se você quiser alterar esse número, digamos, para apenas 10 arquivos ou 1.000, adicione o parâmetropageSizeà sua solicitação:DRIVE.files().list(pageSize=10). Confira mais opções na documentação. - A parte final do script passa por cada arquivo e exibe os nomes e tipos MIME de arquivos.
Você criou seu primeiro aplicativo que usa uma API REST do Google. Parabéns! Além do código de importações e de autorização, o script tem apenas algumas linhas de código (como mostrado acima). A maioria das APIs do Google funciona de maneira semelhante, e você só precisa criar endpoints de serviço para cada um deles.
Usar mais de uma API do Google em um app
Sim, com certeza você pode usar mais de uma API no mesmo app. Este é um snippet de código em 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)
Imagine que esse código pode fazer parte de um app que gera vários slides (API Slides) com base nos dados da planilha (API Sheets) e usa um modelo de slide que é copiado (API Drive) para cada apresentação gerada. Embora esse app não exista, é possível criar algo semelhante usando dois exemplos que a equipe do Google Workspace criou como elementos básicos:
- Substituir texto e Imagens nos slides ( postagem do blog e vídeo): usa a API Drive para copiar uma apresentação de modelo e a API Slides para alterar o texto e espaços reservados para imagens
- Gerar slides com dados de planilhas ( postagem e vídeo do blog): lê dados de uma planilha (API Sheets) e cria slides (API Slides) com base nesses dados.
Seu desafio: criar o app!
12. *Uso avançado do DevConsole
Nesta seção opcional, descrevemos como criar projetos no devconsole, ativar APIs e receber credenciais, tudo sem usar o assistente, como mostrado acima no codelab. Ela é destinada a usuários intermediários que estejam confortáveis o suficiente para fazer isso manualmente ou que queiram aprender a fazer isso.
Especificar o projeto no console do Cloud
Sempre que você cria um aplicativo usando APIs do Google, precisa ter um projeto. É possível reutilizar um projeto existente ou criar um novo. Isso acontece no console do Cloud. Alguns codelabs fornecem um link mágico (por exemplo, um assistente de configuração) que permite que você comece rapidamente, pulando muitas das etapas necessárias. Mas nem todos eles fazem, então estas são apenas instruções gerais sobre como criar projetos.
É possível criar projetos a partir da maioria das telas no console do Cloud, desde que você tenha feito login com suas credenciais do Google e veja um menu suspenso de projetos na parte superior do console. A maioria das capturas de tela aqui foram retiradas do Gerenciador de APIs, também conhecido como Developers Console, e pode ser acessado facilmente clicando em "Gerenciador de API" na navegação à esquerda ou apontando diretamente o navegador para console.developers.google.com.
- Se você ainda não tem projetos, pode ser direcionado para...
- Página Painel:
- Na página Biblioteca:
- ou uma página completamente em branco:
Se este terceiro acontecer com você, basta atualizar o navegador para ser direcionado à página Biblioteca.
- Se você estiver nas páginas Painel ou Biblioteca, clique no seletor de projetos na parte de cima da página:
- Em seguida, você verá a caixa de diálogo de seleção. Clique em "+" no lado direito para criar um novo projeto:
- Depois que você clicar em "+", a página Novo projeto será exibida. Todas as contas pessoais recebem 12 projetos por padrão. Antes de criar seu primeiro projeto, é preciso aceitar os Termos de Serviço das APIs do Google:
Depois disso, as solicitações por e-mail e as perguntas dos Termos de Serviço desaparecerão ao criar projetos futuros:
Você criou um projeto e está pronto para prosseguir escolhendo as APIs que quer usar.
ative 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 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 é gratuito. 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 consultadas pelo usuário antes da ativação. Alguns produtos do Google Cloud Platform (GCP) têm a opção "Sempre sem custo financeiro" camada para a qual você precisa exceder esse limite para receber faturamento. Para os fins do codelab, cada chamada para a API do Vision é contabilizada nesse nível gratuito. 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á faturamento direto 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, então siga as instruções acima e pesquise "Drive". Prossiga após a ativação.
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 oferecem suporte a vários tipos de autorização, mas o mais comum para usuários da API Google Workspace é a autorização do usuário, porque o aplicativo de exemplo deste codelab acessa dados que pertencem aos 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 consentimento". em que você seleciona uma opção app (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.
- De volta à página "Credenciais", role para baixo até "IDs do cliente OAuth2". localize 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.