Nesta série de tutoriais, ilustramos todas as partes móveis de um complemento funcional do Google Sala de Aula. Cada etapa do tutorial aborda conceitos específicos, implementando-os em um único aplicativo da Web. O objetivo é ajudar você a definir, configurar e lançar um complemento funcional.
Seu complemento precisa interagir com um projeto do Google Cloud. Se você não conhece o Google Cloud, recomendamos a leitura dos Guias para iniciantes. Gerencie as credenciais, o acesso à API e o SDK do Google Workspace Marketplace no Console do Google Cloud. Para mais informações sobre o SDK do Marketplace, acesse a página do guia de listagem do Google Workspace Marketplace.
Neste guia, abordamos os seguintes tópicos:
- Use o Google Cloud para criar uma página que será exibida em um iframe no Google Sala de Aula.
- Adicionar o Logon único (SSO) do Google e permitir que os usuários façam login.
- Fazer chamadas de API para anexar o complemento a uma atividade
- Atenda aos principais requisitos de envio de complementos e recursos obrigatórios.
Este guia pressupõe que você esteja familiarizado com a programação e os conceitos fundamentais de desenvolvimento da Web. É altamente recomendável ler o Guia de configuração do projeto antes de iniciar os tutoriais. Esta página contém detalhes de configuração importantes que não são totalmente abordados nos tutoriais.
Exemplos de implementações
Um exemplo de referência completo está disponível em Python. Implementações parciais também estão disponíveis em Java e Node.js. Essas implementações são as fontes do exemplo de código encontrado nas páginas subsequentes.
Onde fazer o download
Os exemplos de Python e Java estão disponíveis nos repositórios do GitHub:
É possível fazer o download da amostra do Node.js como um arquivo ZIP:
Pré-requisitos
Confira as seções a seguir para preparar um novo projeto de complementos.
Certificado HTTPS
Embora você possa hospedar seu app em qualquer ambiente de desenvolvimento, o
complemento do Google Sala de Aula está disponível apenas pelo https://
. Portanto, você precisa de um servidor com criptografia SSL para implantar o app ou testá-lo no iframe do complemento.
É possível usar localhost
com um certificado SSL. Considere mkcert se
você precisar criar um certificado para desenvolvimento local.
Projeto do Google Cloud
Você precisa configurar um projeto do Google Cloud para usar com esses exemplos. Consulte o guia de criação de projetos do Google Cloud e tenha uma visão geral das etapas necessárias para começar. A seção Configurar um projeto do Google Cloud no primeiro tutorial também aborda as ações de configuração específicas a serem realizadas.
Quando terminar, faça o download do ID do cliente OAuth 2.0 como um arquivo JSON. Você precisa adicionar esse arquivo de credencial ao diretório de exemplo descompactado. Consulte Entender os arquivos para locais específicos.
Credenciais do OAuth
Siga estas etapas para criar novas credenciais do OAuth:
- Acesse a página Credenciais do Google Cloud. Verifique se o projeto correto está selecionado na parte de cima da tela.
- Clique em CRIAR CREDENCIAIS e escolha o ID do cliente OAuth no menu suspenso.
- Na próxima página, faça o seguinte:
- Defina o Tipo de aplicativo como Aplicativo da Web.
- Em URIs de redirecionamento autorizados, clique em ADICIONAR URI. Adicione o caminho
completo de uma rota de callback para seu aplicativo. Por exemplo,
https://my.domain.com/auth-callback
ouhttps://localhost:5000/callback
. Você vai criar e processar essa rota mais adiante neste tutorial. Você pode editar ou adicionar mais rotas a qualquer momento. - Clique em CRIAR.
- Em seguida, você vai receber uma caixa de diálogo com as credenciais recém-criadas. Escolha a opção FAZER O DOWNLOAD DO JSON. Copie o arquivo JSON salvo no diretório do servidor.
Pré-requisitos específicos da linguagem
Consulte o arquivo README em cada repositório para conferir a lista mais atualizada de pré-requisitos.
Python
Nosso exemplo de Python usa o framework Flask. Você pode fazer o download de todo o código-fonte nos links fornecidos.
Se necessário, instale o Python 3.7+ e verifique se pip
está disponível.
python3 -m ensurepip --upgrade
Também recomendamos que você configure e ative um novo ambiente virtual do Python.
python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate
Há um requirements.txt
em cada subdiretório de tutorial nos
exemplos transferidos por download. É possível instalar rapidamente as bibliotecas necessárias usando
pip
. Use os comandos abaixo para instalar as bibliotecas necessárias para o
primeiro tutorial.
cd flask/01-basic-app
pip install -r requirements.txt
Node.js
Nosso exemplo do Node.js usa o framework Express (em inglês). Você pode fazer o download do código-fonte completo nos links fornecidos.
Este exemplo requer o Node.js v16.13 ou versões mais recentes.
Instale os módulos de nó necessários usando npm
.
npm install
Java
Nosso exemplo do Java usa o framework Spring Boot. Você pode fazer o download do código-fonte completo nos links fornecidos.
Instale o Java 11+ se ainda não tiver feito isso na sua máquina.
Os aplicativos do Spring Boot podem usar o Gradle ou Maven para processar builds e gerenciar dependências. Esse exemplo inclui o wrapper do Maven que garante um build bem-sucedido sem exigir a instalação do próprio Maven.
No diretório em que você fez o download ou clonou o projeto, execute os comandos a seguir para garantir que você tenha os pré-requisitos para executar o projeto.
java --version
./mvnw --version
Ou no Windows:
java -version
mvnw.cmd --version
Noções básicas sobre os arquivos
As seções a seguir descrevem o layout dos diretórios de exemplo.
Nomes de diretório
Cada repositório contém vários diretórios com nomes que começam com um número,
como /01-basic-app/
. Os números correspondem a etapas específicas do tutorial.
Cada diretório contém um app da Web totalmente funcional que implementa os recursos
descritos em um tutorial específico. Por exemplo, o diretório /01-basic-app/
contém a implementação final do tutorial
Criar um complemento.
Conteúdo do diretório
O conteúdo do diretório varia de acordo com a linguagem de implementação:
Python
A raiz do diretório contém os seguintes arquivos:
main.py
: o ponto de entrada do aplicativo Python. Especifique a configuração do servidor que você quer usar nesse arquivo e execute-a para iniciar o servidor.requirements.txt
: os módulos Python necessários para executar o app da Web. Eles podem ser instalados automaticamente usandopip install -r requirements.txt
.client_secret.json
: o arquivo de chave secreta do cliente baixado do Google Cloud. Observe que isso não está incluído no arquivo de exemplo. Renomeie e copie o arquivo de credenciais salvo em cada raiz de diretório.
config.py
: opções de configuração do servidor Flask.O diretório
webapp
tem o conteúdo do aplicativo da Web. Inclui o seguinte:O diretório
/templates/
com modelos Jinja para várias páginas.O diretório
/static/
com imagens, CSS e arquivos JavaScript complementares.routes.py
: os métodos do gerenciador para as rotas do aplicativo da Web.__init__.py
: o inicializador do módulowebapp
. Esse inicializador inicia o servidor Flask e carrega as opções de configuração definidas emconfig.py
.Arquivos adicionais conforme exigido por uma etapa específica do tutorial.
Node.js
Cada etapa do passo a passo pode ser encontrada na própria subpasta <step>
. Cada etapa contém:
- Arquivos estáticos, como JavaScript, CSS e imagens, são encontrados na pasta
./<step>/public
. - Os roteadores expressos ficam nas pastas
./<step>/routes
. - Os modelos HTML são encontrados nas pastas
./<step>/views
. - O aplicativo de servidor é
./<step>/app.js
.
Java
O diretório do projeto inclui o seguinte:
- O diretório
src.main
contém o código-fonte e a configuração para executar o aplicativo com êxito. Esse diretório inclui o seguinte: + O diretóriojava.com.addons.spring
contém os arquivosApplication.java
eController.java
. O arquivoApplication.java
é responsável por executar o servidor de aplicativos, enquanto o arquivoController.java
processa a lógica do endpoint. + O diretórioresources
contém o diretóriotemplates
com arquivos HTML e JavaScript. Ele também contém o arquivoapplication.properties
, que especifica a porta para executar o servidor, o caminho para o arquivo de keystore e o caminho para o diretóriotemplates
. Esse exemplo inclui o arquivo de keystore no diretórioresources
. Você pode armazená-lo onde preferir, mas atualize o arquivoapplication.properties
com o caminho adequado.pom.xml
contém as informações necessárias para criar o projeto e definir as dependências necessárias..gitignore
contém nomes de arquivos que não devem ser enviados ao git. Adicione o caminho para seu keystore nesse.gitignore
. No exemplo fornecido, ésecrets/*.p12
. O objetivo do keystore é discutido na seção abaixo. No tutorial 2 e posteriores, inclua também o caminho para o arquivoclient_secret.json
para garantir que os secrets não sejam incluídos em um repositório remoto. Para o tutorial 3 e mais recentes, você precisa adicionar o caminho para o arquivo do banco de dados H2 e a fábrica do repositório de dados de arquivos. Mais informações sobre a configuração desses repositórios de dados podem ser encontradas no terceiro tutorial sobre como gerenciar visitas repetidas.mvnw
emvnw.cmd
são os executáveis do wrapper Maven para Unix e Windows, respectivamente. Por exemplo, executar./mvnw --version
em Unix gera a versão do Apache Maven, entre outras informações.- O diretório
.mvn
contém a configuração do wrapper do Maven.
Executar o servidor de amostra
Você precisa iniciar o servidor para testá-lo. Siga estas instruções para executar o servidor de exemplo na linguagem de sua preferência:
Python
Credenciais do OAuth
Crie e faça o download das credenciais do OAuth, conforme descrito anteriormente. Coloque o arquivo JSON no diretório raiz ao lado do arquivo de inicialização do servidor do aplicativo.
Configurar o servidor
Há várias opções para executar o servidor da Web. No final do arquivo Python, adicione uma das seguintes opções:
localhost
desprotegida. Isso é adequado para testes diretos apenas em uma janela do navegador. Domínios não seguros não podem ser carregados no iframe de complementos do Google Sala de Aula.if __name__ == "__main__": # Disable OAuthlib's HTTPs verification. os.environ["OAUTHLIB_INSECURE_TRANSPORT"] = "1" # Run the web app at http://localhost:5000. app.run(debug=True)
Proteja o
localhost
. É necessário especificar uma tupla de arquivos de chave SSL para o argumentossl_context
.if __name__ == "__main__": # Run the web app at https://localhost:5000. app.run(host="localhost", ssl_context=("localhost.pem", "localhost-key.pem"), debug=True)
Gunicorn (link em inglês). Isso é adequado para um servidor pronto para produção ou implantação em nuvem. Recomendamos definir uma variável de ambiente
PORT
para usar com essa opção de inicialização.if __name__ == "__main__": # Run the web app at https://<your domain>:<server_port>. # Defaults to https://<your domain>:8080. server_port = os.environ.get("PORT", "8080") app.run(debug=True, port=server_port, host="0.0.0.0")
Iniciar o servidor
Execute o aplicativo Python para iniciar o servidor conforme configurado na etapa anterior.
python main.py
Clique no URL que aparece para visualizar seu app da Web em um navegador para confirmar se ele está sendo executado corretamente.
Node.js
Configurar o servidor
Para executar o servidor por HTTPS, é necessário criar um autocertificado usado para executar o aplicativo por HTTPS. Essas credenciais precisam ser
salvas como sslcert/cert.pem
e sslcert/key.pem
na pasta raiz
do repositório. Talvez seja necessário adicionar essas chaves à cadeia de chaves do SO para
que o navegador as aceite.
Verifique se *.pem
está no seu arquivo .gitignore
, porque você não quer
confirmar o arquivo no git.
Iniciar o servidor
É possível executar o aplicativo com o comando a seguir, substituindo step01
pela etapa correta que você quer executar como servidor (por exemplo, step01
para 01-basic-app e step02
para 02-login).
npm run step01
ou
npm run step02
Isso inicia o servidor da Web em https://localhost:5000
.
É possível encerrar o servidor com Control + C
no seu terminal.
Java
Configurar o servidor
Para executar o servidor por HTTPS, é necessário criar um autocertificado usado para executar o aplicativo por HTTPS.
Considere usar o mkcert para desenvolvimento local. Depois de instalar o mkcert
,
os comandos a seguir geram um certificado armazenado localmente para ser executado por
HTTPS.
mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>
Este exemplo inclui o arquivo de keystore no diretório de recursos. É possível
armazenar o arquivo como preferir, mas atualize o
arquivo application.properties
com o caminho adequado. O nome de domínio é
o domínio em que você executa o projeto (por exemplo, localhost
).
Verifique se *.p12
está no seu arquivo .gitignore
, porque você não quer
confirmar o arquivo no git.
Iniciar o servidor
Inicie o servidor executando o método main
no arquivo
Application.java
. No IntelliJ, por exemplo, você pode clicar com o botão direito do mouse em
Application.java
> Run 'Application'
no
diretório src/main/java/com/addons/spring
ou abrir o arquivo Application.java
para clicar na seta verde à esquerda da assinatura do método
main(String[] args)
. Como alternativa, execute o projeto em uma janela
de terminal:
./mvnw spring-boot:run
ou no Windows:
mvnw.cmd spring-boot:run
Isso inicia o servidor em https://localhost:5000
ou na porta especificada em application.properties
.