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 como complemento do Google Sala de Aula. Cada etapa do tutorial aborda conceitos básicos, implementando-os em um único aplicativo da Web. O objetivo é ajudar você para configurar e lançar um complemento funcional.

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

Neste guia, abordamos os seguintes tópicos:

Usar o Google Cloud para criar uma página que será exibida em um iframe em 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ê tenha familiaridade com programação e noções básicas de programação conceitos de desenvolvimento de software. É altamente recomendável ler o documento Configuração do projeto guia antes de iniciar os tutoriais. Esta página contém informações de configuração do Terraform que não são abordados em todos os 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 código de exemplo encontradas 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:

Arquivo Node.js

Pré-requisitos

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

Certificado HTTPS

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

É possível usar localhost com um certificado SSL. use mkcert se você precisa criar um certificado para desenvolvimento local.

Projeto do Google Cloud

Você precisa configurar um projeto do Google Cloud para usar com esses exemplos. Consulte a guia de criação de projetos do Google Cloud para uma visão geral do que etapas para começar. A página Configurar um projeto do Google Cloud do primeiro tutorial também aborda as etapas de configuração ações a serem tomadas.

Quando terminar, faça o download do seu ID do cliente OAuth 2.0 como um arquivo JSON. você precisa adicionar esse arquivo de credencial para o diretório de exemplo descompactado. Consulte Entender o 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. Garanta se o projeto correto está selecionado na parte superior da tela.
Clique em CRIAR CREDENCIAIS e escolha o ID do cliente OAuth no 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 path de uma rota de callback para seu aplicativo. Por exemplo: https://my.domain.com/auth-callback ou https://localhost:5000/callback. Você cria e processa 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 o opção FAZER O DOWNLOAD DO JSON. Copie o arquivo JSON transferido por download para seu servidor diretório.

Pré-requisitos específicos da linguagem

Veja o arquivo README em cada repositório para acessar a lista mais atualizada de pré-requisitos.

Python

Nosso exemplo de Python usa o framework Flask. Você pode baixar código-fonte completo dos 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 uma nova biblioteca de nuvem.

python3 -m venv .classroom-addon-env
source .classroom-addon-env/bin/activate

Há um requirements.txt em cada subdiretório do tutorial nos 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 do Node.js usa o framework Express (em inglês). Você pode fazer o download todo o código-fonte dos 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 todo o código-fonte dos links fornecidos.

Instale o Java 11+ se ainda não tiver feito isso na sua máquina.

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

No diretório em que você fez o download ou clonou o projeto, execute o comando 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 aplicativo da web totalmente funcional que implementa os recursos descritas em um tutorial específico. Por exemplo, o /01-basic-app/ contém a implementação final do módulo 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. Especificar o servidor que você quer usar neste arquivo. Em seguida, execute-o 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 baixado do Google Google Cloud. Observe que isso não está incluído no arquivo de exemplo. você deve renomear e copiar seu arquivo de credenciais baixado em cada raiz do diretório.
  
  Importante: você precisa fornecer o arquivo de chave secreta do cliente da sua projeto do Google Cloud antes de executar os exemplos.
config.py: opções de configuração do servidor Flask.
O diretório webapp tem 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 JavaScript auxiliar .
routes.py: os métodos do gerenciador para as rotas do aplicativo da Web.
__init__.py: o inicializador do módulo webapp. Isso O inicializador inicia o servidor Flask e carrega as opções de configuração. definido em config.py.
Arquivos adicionais conforme exigido por uma etapa específica do tutorial.

Node.js

Cada etapa do passo a passo pode ser encontrada em seu próprio <step> subpasta. Cada etapa contém:

Arquivos estáticos como JavaScript, CSS e imagens são encontrados na ./<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 a serem executados o aplicativo. Esse diretório inclui o seguinte: + java.com.addons.spring contém o Application.java e Controller.java. O Application.java é responsável por executar do servidor de aplicativos, enquanto o arquivo Controller.java processa lógica de endpoint da API. + O diretório resources contém o diretório templates com Arquivos HTML e JavaScript. Ele também contém Arquivo application.properties que especifica a porta para executar o do servidor, o caminho para o arquivo do keystore e o caminho templates. Este exemplo inclui o arquivo de keystore diretório resources. Você pode armazená-lo onde quer preferir, mas atualize application.properties com o caminho correspondente.
- pom.xml contém as informações necessárias para criar o projeto e define 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 propósito do é discutido na seção abaixo). Para o tutorial 2 e além disso, você também deve incluir o caminho para seu client_secret.json para garantir que você não inclua secrets em um repositório remoto. No passo a passo 3 e além, deve adicionar o caminho para o arquivo de banco de dados H2 e o repositório de dados de arquivos fábrica Mais informações sobre a configuração desses repositórios de dados podem ser no terceiro tutorial sobre como gerenciar visitas repetidas.
- mvnw e mvnw.cmd são os executáveis do wrapper Maven para Unix e Windows, respectivamente. Por exemplo, executar ./mvnw --version em O 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 execute o servidor de exemplo na linguagem que preferir:

Python

Credenciais do OAuth

Crie e faça o download das credenciais do OAuth, conforme descrito anteriormente. Lugar o arquivo JSON no diretório raiz junto com o servidor do aplicativo arquivo de inicialização.

Configurar o servidor

Há várias opções para executar o servidor da Web. Ao final da sua Python, adicione uma das seguintes opções:

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

Proteja 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)

Gunicorn (link em inglês). Isso é adequado para um servidor pronto para produção ou implantação na nuvem. Recomendamos definir uma variável de ambiente PORT para usar com essa opção de lançamento.

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 seu aplicativo Python para iniciar o servidor conforme configurado no etapa anterior.

python main.py

Clique no URL que aparece para visualizar seu app da Web em um navegador para confirmar se para que ele seja executado corretamente.

Node.js

Configurar o servidor

Para executar o servidor por HTTPS, crie um certificado próprio. que é usado para executar o aplicativo por HTTPS. Essas credenciais devem ser salva como sslcert/cert.pem e sslcert/key.pem na raiz do repositório. do Compute Engine. Pode ser necessário adicionar essas chaves à cadeia de chaves do SO para seu navegador para aceitá-los.

Verifique se *.pem está no arquivo .gitignore porque você não quer fazer commit do arquivo no git.

Iniciar o servidor

É possível executar o aplicativo com o seguinte comando substituindo step01 para a etapa correta que você quer executar como servidor (por exemplo, step01 para 01-basic-app e step02 para 02-login).

npm run step01

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, crie um certificado próprio. que é 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 que será executado HTTPS.

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

Este exemplo inclui o arquivo de keystore no diretório de recursos. Você pode armazene-o onde quiser, mas atualize o application.properties com o caminho correspondente. O nome de domínio é o domínio no qual você executa o projeto (por exemplo, localhost).

Verifique se *.p12 está no arquivo .gitignore porque você não quer fazer commit do arquivo no git.

Iniciar o servidor

Inicie o servidor executando o método main no Application.java. . No IntelliJ, por exemplo, você pode clicar com o botão direito Application.java > Run 'Application' na src/main/java/com/addons/spring ou abra o Application.java para clicar na seta verde à esquerda do main(String[] args) assinatura do método. Como alternativa, execute o projeto em um terminal janela:

./mvnw spring-boot:run

ou no Windows:

mvnw.cmd spring-boot:run

Isso inicia o servidor em https://localhost:5000 ou na porta em que você especificado em application.properties.