Os complementos do Google Sala de Aula já estão disponíveis para desenvolvedores. Consulte a documentação sobre complementos para mais informações.

Esta página foi traduzida pela API Cloud Translation.

Tutoriais

Esta série de tutoriais ilustra todas as partes móveis de um complemento funcional do Google Sala de Aula. Cada etapa do tutorial aborda conceitos específicos e os implementa em um único aplicativo da Web. O objetivo é ajudar você a instalar, 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 ler os guias para iniciantes. Você gerencia 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 de instruções da página de listagem do Google Workspace Marketplace.

Neste guia, abordamos os seguintes tópicos:

Use o Google Cloud para criar uma página a ser mostrada em um iframe no Classroom.
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 e recursos obrigatórios do complemento.

Neste guia, pressupomos que você já conheça a programação e os conceitos fundamentais de desenvolvimento da Web. Recomendamos ler o Guia de configuração do projeto antes de começar as orientações. Esta página contém detalhes importantes de configuração que não são abordados totalmente nas instruções.

Exemplos de implementações

Um exemplo de referência completo está disponível em Python. Implementações parciais também estão disponíveis no Java e no Node.js. Essas implementações são as fontes do código de exemplo encontrado nas páginas seguintes.

Onde fazer o download

Os exemplos em Python e Java estão disponíveis nos repositórios do GitHub:

O exemplo do Node.js pode ser baixado como um arquivo zip:

Arquivo do Node.js

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, o complemento do Google Sala de Aula só está disponível pelo https://. Portanto, é necessário ter um servidor com criptografia SSL para implantar ou testar seu app no iframe do complemento.

É possível usar localhost com um certificado SSL. Use mkcert se 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 Criação de projetos do Google Cloud para ter 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 descreve as ações de configuração específicas.

Quando terminar, faça o download do ID do cliente OAuth 2.0 como um arquivo JSON. Você precisa adicionar esse arquivo de credenciais ao diretório de exemplo descompactado. Consulte Noções básicas sobre 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 certo está selecionado na parte de cima da tela.
Clique em CRIAR CREDENCIAIS e escolha ID do cliente OAuth no menu suspenso.
Na próxima página:
- Defina o Tipo de aplicativo como Aplicativo da Web.
- Em URIs de redirecionamento autorizados, clique em ADICIONAR URI. Adicione o caminho completo para uma rota de callback do seu aplicativo. Por exemplo, https://my.domain.com/auth-callback ou https://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ê recebe uma caixa de diálogo com as credenciais recém-criadas. Escolha a opção DOWNLOAD JSON. Copie o arquivo JSON transferido por download para o 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 em Python usa o framework Flask. Faça o download do código-fonte completo nos links fornecidos.

Se necessário, instale o Python 3.7 ou mais recente e verifique se o 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 a primeira apresentação.

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

Node.js

Nosso exemplo de Node.js usa o framework Express. Faça o download do código-fonte completo nos links fornecidos.

Este exemplo requer o Node.js v16.13 ou mais recente.

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

npm install

Java

Nosso exemplo em Java usa o framework do Spring Boot. Faça o download do código-fonte completo nos links fornecidos.

Instale o Java 11 ou mais recente, se ainda não tiver feito isso.

Os aplicativos 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 Maven.

No diretório em que você fez o download ou clonou o projeto, execute os comandos abaixo para garantir que você tenha os pré-requisitos para executar o projeto.

java --version
./mvnw --version

Ou no Windows:

java -version
mvnw.cmd --version

Entender os arquivos

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

Nomes de diretórios

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

O diretório raiz contém os seguintes arquivos:
- main.py: o ponto de entrada do aplicativo Python. Especifique a configuração do servidor que você quer usar neste arquivo e execute-o 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: o arquivo de chave secreta do cliente baixado do Google Cloud. Ele não está incluído no arquivo de exemplo. É necessário renomear e copiar o arquivo de credenciais baixado em cada diretório raiz.
  
  Importante: é necessário fornecer o arquivo de segredo 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 contém o conteúdo do aplicativo da Web. Ele 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 de manipulador 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 necessário em 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 expressos estão nas pastas ./<step>/routes.
Os modelos HTML estão 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: + O diretório 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 do keystore e o caminho para o diretório templates. Este exemplo inclui o arquivo de keystore no diretório resources. Você pode armazená-lo onde quiser, mas atualize o arquivo application.properties com o caminho correto.
- O 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 o keystore neste .gitignore. No exemplo fornecido, é secrets/*.p12. A finalidade do keystore é discutida na seção abaixo. Para a demonstração 2 e demais, também é necessário incluir o caminho para o arquivo client_secret.json para garantir que os segredos não sejam incluídos em um repositório remoto. Para a demonstração 3 e outras, adicione o caminho ao arquivo de banco de dados H2 e à fábrica de repositório de arquivos. Mais informações sobre a configuração desses repositórios de dados podem ser encontradas na terceira etapa de como lidar com visitas repetidas.
- mvnw e mvnw.cmd são os executáveis do wrapper do Maven para Unix e Windows, respectivamente. Por exemplo, a execução de ./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 exemplo

É necessário iniciar o servidor para testá-lo. Siga estas instruções para executar o servidor de exemplo no idioma de sua escolha:

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 com o arquivo de inicialização do servidor do aplicativo.

Configurar o servidor

Você tem várias opções para executar o servidor da Web. No final do arquivo Python, adicione uma das seguintes opções:

localhost não segura. Isso é adequado para testes diretos em uma janela do navegador. Domínios não seguros não podem ser carregados no iFrame do complemento 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)

Proteger o localhost. É necessário especificar 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)

Servidor Gunicorn. Isso é adequado para um servidor pronto para produção ou implantação na nuvem. Recomendamos definir 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

Execute o aplicativo Python para iniciar o servidor conforme configurado na etapa anterior.

python main.py

Clique no URL que aparece para conferir se o app da Web está sendo executado corretamente em um navegador.

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. Talvez seja necessário adicionar essas chaves à cadeia de chaves 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

É 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-sign-in).

npm run step01

npm run step02

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

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 o mkcert para desenvolvimento local. Depois de instalar o mkcert, os comandos abaixo geram um certificado armazenado localmente para execução em HTTPS.

mkcert -install
mkcert -pkcs12 -p12-file <path_to_keystore> <domain_name>

Este exemplo inclui o arquivo de chaves no diretório de recursos. Você pode armazená-lo onde preferir, mas atualize o arquivo application.properties com o caminho correto. 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

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 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, é possível executar 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.