Tutoriais

Esta série de tutoriais ilustram todas as partes móveis de um complemento funcional do Google Sala de Aula. Cada etapa aborda conceitos específicos, implementando-os em um único aplicativo da Web. O objetivo é ajudar você a definir, configurar e iniciar um complemento funcional.

O complemento precisa interagir com um projeto do Google Cloud. Se você não conhece o Google Cloud, recomendamos a leitura dos Guias para iniciantes. Você gerencia credenciais, o acesso à API e o SDK do GWM no console do Google Cloud. Para mais informações sobre o SDK do GWM, acesse a página do guia de listagens do Google Workspace Marketplace.

Neste guia, abordamos os seguintes tópicos:

• Use o Google Cloud para criar uma página a ser exibida em um iframe no Google Sala de Aula.
• Adicione o Logon único (SSO) do Google e permita que os usuários façam login.
• Faça 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ê conheça a programação e os conceitos fundamentais do 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

Há exemplos de referência completos disponíveis em JavaScript, Python e Java. Essas implementações são as origens do código de exemplo encontrado nas páginas seguintes.

Onde fazer o download

Os arquivos completos dos exemplos podem ser baixados usando os links abaixo.

• Arquivo Python
• Arquivo Node.js
• Arquivo Java

Pré-requisitos

Leia as seções a seguir para preparar um novo projeto de complementos.

Certificado HTTPS

Embora seja possível hospedar seu app em qualquer ambiente de desenvolvimento, seu complemento do Google Sala de Aula está disponível apenas pelo https://. Portanto, você precisa de um servidor com criptografia SSL para implantar seu app ou testá-lo no iframe do complemento.

É possível usar localhost com um certificado SSL. Considere mkcert se precisar criar um certificado para desenvolvimento local.

Projeto do Google Cloud

Você precisa configurar um projeto do Google Cloud para usar com estes exemplos. Consulte o guia Criação de projetos do Google Cloud para ter uma visão geral das etapas necessárias para começar. Na seção Configurar um projeto do Google Cloud no primeiro tutorial, você também verá 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. Adicione esse arquivo de credencial ao diretório de exemplo descompactado. Consulte Compreender os arquivos para locais específicos.

Credenciais de OAuth

Importante :seu app da Web precisa usar as credenciais do OAuth 2.0 gerenciadas no Google Cloud.

Siga estas etapas para criar novas credenciais do OAuth:

• Navegue até a página Credenciais do Google Cloud. Verifique se o projeto correto está selecionado na parte superior da tela.
• Clique em CRIAR CREDENCIAIS e escolha ID do cliente OAuth no menu suspenso.
• Na página 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 o aplicativo. Por exemplo, https://my.domain.com/auth-callback ou https://localhost:5000/callback. Você vai criar e processar essa rota posteriormente neste tutorial. É possível editar ou adicionar mais trajetos 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 do idioma

Consulte o arquivo README em cada arquivo para acessar a lista mais atualizada de pré-requisitos.

Python

Nosso exemplo em Python usa a biblioteca Flask. Você pode baixar o código-fonte completo no link acima.

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 baixados. É possível instalar rapidamente as bibliotecas necessárias usando pip. Use os seguintes comandos para instalar as bibliotecas necessárias para o primeiro tutorial.

cd flask/01-basic-app
pip install -r requirements.txt

Node.js

Nosso exemplo em Node.js usa o framework Express. Você pode baixar o código-fonte completo no link acima.

Este exemplo requer o Node.js v16.13 ou posterior.

Instale os módulos de nó necessários usando npm.

npm install

Java

Nosso exemplo em Java usa o framework Spring Boot (link em inglês). Você pode baixar o código-fonte completo no link acima.

Instale o Java 11+ se ele ainda não estiver instalado na máquina.

Os aplicativos do Spring Boot podem usar o Gradle ou o Maven para processar builds e gerenciar dependências. Este exemplo inclui o wrapper do Maven que garante um build bem-sucedido sem exigir que você instale o próprio Maven.

No diretório em que o projeto foi transferido por download ou clonado, execute os comandos a seguir para garantir que você tenha os pré-requisitos para executá-lo.

java --version
./mvnw --version

Ou no Windows:

java -version
mvnw.cmd --version

Entender os arquivos

As seções abaixo descrevem o layout dos diretórios de exemplo.

Nomes de diretório

Cada arquivo 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 de 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 usando pip install -r requirements.txt.

  • client_secret.json: arquivo de chave secreta do cliente transferido por download do Google Cloud. Observe que isso não está incluído no arquivo de exemplo. Você precisa renomear e copiar o arquivo de credenciais salvo em cada raiz do diretório.

    Importante: é necessário fornecer o arquivo de chave secreta do cliente do seu projeto do Google Cloud antes de executar os exemplos.

• config.py: opções de configuração para o 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ódulo webapp. Esse inicializador inicia o servidor Flask e carrega as opções de configuração definidas em config.py.

• Arquivos adicionais conforme exigido por uma etapa específica do tutorial.

Node.js

Cada etapa do tutorial 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 Express estão nas pastas ./<step>/routes.
• Os modelos HTML podem ser encontrados nas pastas ./<step>/views.
• O aplicativo do 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. Esse diretório inclui o seguinte: + java.com.addons.spring contém os arquivos Application.java e Controller.java. O arquivo Application.java é responsável por executar o servidor de aplicativos, enquanto o arquivo Controller.java processa a lógica do endpoint. + O diretório resources contém o diretório templates com arquivos HTML e JavaScript. Ele também contém o arquivo application.properties que especifica a porta para executar o servidor, o caminho para o arquivo de keystore e o caminho para o diretório templates. Este exemplo inclui o arquivo keystore no diretório resources. É possível armazená-lo onde você preferir, mas atualize o arquivo application.properties com o caminho de acordo.
  • 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 podem ser enviados por upload para o git. Adicione o caminho ao seu keystore neste .gitignore. No exemplo fornecido, é secrets/*.p12. O objetivo do keystore é discutido na seção abaixo. Para o tutorial 2 e além, você também precisa incluir o caminho para o arquivo client_secret.json para garantir que os secrets não sejam incluídos em um repositório remoto. Para o tutorial 3 e além, adicione o caminho para a fábrica do arquivo de banco de dados H2 e do repositório de dados de arquivos. Mais informações sobre a configuração desses armazenamentos de dados podem ser encontradas no terceiro tutorial sobre como processar visitas repetidas.
  • mvnw e mvnw.cmd são os executáveis do wrapper do Maven para Unix e Windows, respectivamente. Por exemplo, executar ./mvnw --version no 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

Importante :seu aplicativo da Web só pode ser aberto no Google Sala de Aula por HTTPS. Consulte a seção Certificado HTTPS acima para mais detalhes.

É necessário iniciar o servidor para testá-lo. Siga as instruções abaixo para executar o servidor de exemplo na linguagem de sua preferência:

Python

Credenciais do OAuth

Crie e faça o download das suas credenciais do OAuth, conforme descrito acima. 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 seu arquivo Python, adicione uma das seguintes opções:

1. localhost desprotegido. Esse recurso só é adequado para testes diretamente 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)
   

2. Proteja o localhost. Especifique uma tupla de arquivos de chave SSL para o argumento ssl_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)
   

3. Gunicorn (link em inglês). Isso é adequado para um servidor pronto para produção ou uma implantação na nuvem. Recomendamos configurar uma variável de ambiente PORT para uso 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

Aviso :antes de iniciar o servidor, você precisa configurar um projeto do Google Cloud para acessar a API Classroom e as credenciais necessárias.

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, você precisa 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. Pode ser necessário adicionar essas chaves à cadeia do SO para que o navegador as aceite.

Verifique se *.pem está no arquivo .gitignore, porque você não quer confirmar o arquivo no git.

Iniciar o servidor

Aviso :antes de iniciar o servidor, você precisa configurar um projeto do Google Cloud para acessar a API Classroom e as credenciais necessárias.

É 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 login 02).

npm run step01

ou

npm run step02

Isso inicia o servidor da Web em https://localhost:3000.

Você pode encerrar o servidor com Control + C no terminal.

Java

Configurar o servidor

Para executar o servidor por HTTPS, você precisa criar um autocertificado usado para executar o aplicativo por HTTPS.

Considere usar mkcert para desenvolvimento local. Depois que você instala 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 keystore no diretório de recursos. É possível armazená-lo onde preferir, mas atualize o arquivo application.properties com o caminho de acordo. O nome de domínio é o domínio em que você executa o projeto (por exemplo, localhost).

Verifique se *.p12 está no arquivo .gitignore, porque você não quer confirmar o arquivo no git.

Iniciar o servidor

Aviso :antes de iniciar o servidor, você precisa configurar um projeto do Google Cloud para acessar a API Classroom e as credenciais necessárias.

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.