Criar um complemento do Google Sala de Aula

Este é o primeiro tutorial sobre os complementos do Google Sala de Aula série de tutoriais.

Neste tutorial, você estabelece as bases para desenvolver um aplicativo da Web e e publicá-lo como um complemento do Google Sala de Aula. Etapas das próximas instruções expandir o app.

Neste tutorial, você vai:

• Crie um projeto do Google Cloud para seu complemento.
• Criar um esqueleto de app da Web com botões de login de marcador de posição.
• Publique uma página "Detalhes do app" do Google Workspace Marketplace para seu complemento.

Quando terminar, você pode instalar seu complemento e carregá-lo no Iframe de complementos do Google Sala de Aula.

Importante: antes de seguir estes tutoriais, leia a configuração do projeto e conclua as etapas de integração da jornada do desenvolvedor. Pagar configuração de visibilidade do aplicativo, já que ela não pode ser mudou depois.

Pré-requisitos

Escolha um idioma para ver os pré-requisitos apropriados:

Python

Nosso exemplo de Python usa o framework Flask. Você pode fazer o download código-fonte de todos os tutoriais da Página de visão geral. O código para isso um tutorial específico pode ser encontrado no diretório /flask/01-basic-app/.

Se necessário, instale o Python 3.7+ e verifique se pip está disponível.

python -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

Cada subdiretório de tutorial nos exemplos transferidos por download contém um requirements.txt: É possível instalar rapidamente as bibliotecas necessárias usando pip: Use o código abaixo para instalar as bibliotecas necessárias .

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

Node.js

Nosso exemplo do Node.js usa o framework Express. Você pode baixar completo do código-fonte de todos os tutoriais da Página de visão geral.

Se necessário, instale o NodeJS v16.13+.

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 o código-fonte completo de todos os tutoriais da Página de visão geral.

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.

Para executar o exemplo fornecido, execute os seguintes comandos no em que você fez o download do projeto para garantir que você tenha o arquivo pré-requisitos para executá-lo.

java --version
./mvnw --version

Ou no Windows:

java -version
mvnw.cmd --version

Configure um projeto do Google Cloud

Acesso à API Classroom e aos métodos de autenticação obrigatórios são controladas por projetos do Google Cloud. As instruções a seguir orientam você as etapas mínimas para criar e configurar um novo projeto para uso com seu .

Criar o projeto

Acesse a página de criação de projetos para criar um novo projeto do Google Cloud. Você pode forneça qualquer nome para o novo projeto. Clique em Criar.

A criação do novo projeto leva alguns instantes. Depois, comece selecione o projeto; escolha essa opção no seletor de projetos no menu suspenso na parte superior da tela ou clique em SELECIONAR PROJETO no no canto superior direito.

Importante :verifique se você selecionou o projeto correto antes de continuar.

Anexar o SDK do Google Workspace Marketplace ao projeto do Google Cloud

Acesse o navegador da Biblioteca de APIs. Pesquisar por Google Workspace Marketplace SDK: O SDK deve aparecer na lista de resultados.

Selecione o card "SDK do Google Workspace Marketplace" e clique em Ativar.

Configurar o SDK do Google Workspace Marketplace

O Google Workspace Marketplace oferece uma lista para os usuários e os administradores instalarem o complemento. Configure o Configuração do app e Loja do SDK do Marketplace listagem e a Tela de consentimento OAuth para continuar.

Configuração do app

Navegue até a página Configuração do aplicativo do SDK do Marketplace. Forneça as seguintes informações:

• Defina a Visibilidade do app como Public ou Private.

  • A configuração pública é destinada a apps que serão lançados para os usuários finais. Um aplicativo público precisa passar por um processo de aprovação antes de ser publicados para usuários finais, mas é possível especificar usuários que podem instalar e teste-o como um Rascunho. Este é um estado de pré-publicação que permitirá para você testar e desenvolver o complemento antes de enviá-lo para aprovação.
  • A configuração particular é adequada para testes e desenvolvimento internos. Um o app particular só pode ser instalado por usuários no mesmo domínio o projeto foi criado. Portanto, você deve definir a visibilidade como privada somente se o projeto tiver sido criado em um domínio com uma conta do Google Workspace for Education assinatura. Caso contrário, os usuários de teste não vão poder lançar Complementos do Google Sala de Aula.
  .
  Aviso: verifique se a configuração Visibilidade do app está correta antes os dados. Não é possível alterar a visibilidade do app depois de defini-la. Você precisa criar um novo projeto do Google Cloud para definir uma visibilidade diferente do app.

• Defina as Configurações de instalação como Admin Only install se quiser restringir a instalação aos administradores do domínio.

• Em Integração de apps, selecione Complemento do Google Sala de Aula. Você está será solicitado o URI de configuração de anexo secure; esse é o URL que você devem ser carregados quando um usuário abrir o complemento. Para os fins deste que precisa ser https://<your domain>/addon-discovery.

• Os Prefixos URI de anexo permitidos são usados para validar os URIs definidos em AddOnAttachment usando o courses.*.addOnAttachments.create e o courses.*.addOnAttachments.patch. A validação é um comando do prefixo de string correspondente e não permite o uso de curingas neste tempo de resposta. Adicione pelo menos o domínio raiz do seu servidor de conteúdo, como https://localhost:5000/ ou https://cdn.myedtech.com/.

• Adicione os mesmos escopos do OAuth que aparecem na tela de consentimento do OAuth. na etapa anterior.

  Importante: a lista de escopos do OAuth especificados na configuração do app precisa correspondam aos listados na tela de permissão OAuth.

• Preencha os campos conforme apropriado para sua organização em Desenvolvedor Links:

Detalhes do app

Acesse a página Detalhes do app do SDK do Marketplace. Forneça as seguintes informações:

• Em Detalhes do app, adicione um idioma ou expanda o menu suspenso ao lado do idioma já listado. Informe o nome e as descrições do aplicativo. esses aparecer na página "Detalhes do app" do Google Workspace Marketplace do seu complemento. Clique em Concluído para salvar.
• Escolha uma Categoria para o complemento.
• Em Recursos gráficos, forneça imagens para os campos obrigatórios. Elas podem ser alterado mais tarde e podem ser espaços reservados por enquanto.
• Em Links de suporte, forneça os URLs solicitados. Eles podem ser marcadores de posição se você definir a visibilidade do app como Particular no etapa.

Se você definiu a visibilidade do app como Particular na etapa anterior, clique em PUBLICAR seu app fica disponível imediatamente para instalação. Se você definir Visibilidade do app para Público, adicione endereços de e-mail na área Testadores de rascunho. para todos os usuários de teste e clique em Salvar rascunho.

Importante: escolher PUBLICAR para um app com visibilidade pública enviará imediatamente para análise da equipe do Marketplace. O equipe de revisão deve testar e aprovar o aplicativo antes que ele possa ser adicionado ao Google Marketplace. Salve rascunhos do projeto para torná-lo pode ser instalado pelos usuários de teste sem revisão. Escolha PUBLICAR RASCUNHO mais tarde, quando estiver tudo pronto para a equipe do Marketplace aprová-lo.

Tela de permissão OAuth

A tela de permissão OAuth aparece quando os usuários autorizam o app pela primeira vez. Ele solicita a permitir que seu aplicativo acesse informações pessoais e da conta, como determinado pelos escopos que você ativa.

Acesse a página de criação para a tela de consentimento do OAuth. Forneça o seguinte informações:

• Defina Tipo de usuário como Externo. Clique em Criar.
• Na próxima página, preencha os detalhes necessários do app e os dados de contato. Forneça todos os domínios que hospedam o app em Domínios autorizados. Clique em SALVAR E CONTINUAR.

• Adicione todos os escopos do OAuth exigidos pelo app da Web. Consulte a documentação do OAuth guia de configuração do Terraform (em inglês) para uma discussão aprofundada sobre escopos e sua finalidade.

  Você deve solicitar pelo menos um dos seguintes escopos para que o Google envie o parâmetro de consulta login_hint. Uma explicação mais detalhada sobre isso está disponível no nosso guia de configuração do OAuth:

  • https://www.googleapis.com/auth/userinfo.email (já incluído)
  • https://www.googleapis.com/auth/userinfo.profile (já incluído)

  Os escopos a seguir são específicos dos complementos do Google Sala de Aula:

  • https://www.googleapis.com/auth/classroom.addons.teacher
  • https://www.googleapis.com/auth/classroom.addons.student

  Inclua também outros escopos de API do Google exigidos pelo app usuários.

  Clique em SALVAR E CONTINUAR.

• Liste os endereços de e-mail das contas de teste na página Usuários de teste. Clique em SALVAR E CONTINUAR.

Confirme se as configurações estão corretas e volte ao painel.

Instalar o complemento

Agora você pode instalar seu complemento usando o link na parte superior do Página Detalhes do app do SDK do Marketplace. Clique no aplicativo URL na parte superior da página para ver a lista e escolha Instalar.

Observação: no momento, apenas usuários específicos podem instalar o complemento. Se Seu complemento tem visibilidade pública, apenas os usuários listados como "Rascunho" Testadores. Caso seu complemento tenha visibilidade particular, são os usuários no mesmo domínio que o projeto do Cloud.

Criar um app da Web básico

Configurar um aplicativo da Web de estrutura com duas rotas. Etapas das próximas instruções expandir esse aplicativo. Por isso, por enquanto, basta criar uma página de destino para o complemento /addon-discovery e uma página de índice fictícia / para o "site da empresa".

Implemente estes dois endpoints:

• /: mostra uma mensagem de boas-vindas e um botão para fechar a guia atual. e o iframe do complemento.
• /addon-discovery: mostra uma mensagem de boas-vindas e dois botões: um para fechar. o iframe do complemento e outro para abrir um site em uma nova guia.

Observe que estamos adicionando botões para criar e fechar janelas ou o iframe. Esses demonstrar um método para colocar o usuário com segurança em uma nova guia para de autorização no próximo tutorial.

Criar script utilitário

Crie um diretório static/scripts. Crie um novo arquivo addon-utils.js. Adicione o método duas funções seguintes.

/**
 *   Opens a given destination route in a new window. This function uses
 *   window.open() so as to force window.opener to retain a reference to the
 *   iframe from which it was called.
 *   @param {string} destinationURL The endpoint to open, or "/" if none is
 *   provided.
 */
function openWebsiteInNewTab(destinationURL = '/') {
  window.open(destinationURL, '_blank');
}

/**
 *   Close the iframe by calling postMessage() in the host Classroom page. This
 *   function can be called directly when in a Classroom add-on iframe.
 *
 *   Alternatively, it can be used to close an add-on iframe in another window.
 *   For example, if an add-on iframe in Window 1 opens a link in a new Window 2
 *   using the openWebsiteInNewTab function, you can call
 *   window.opener.closeAddonIframe() from Window 2 to close the iframe in Window
 *   1.
 */
function closeAddonIframe() {
  window.parent.postMessage({
    type: 'Classroom',
    action: 'closeIframe',
  }, '*');
};

Criar rotas

Implemente os endpoints /addon-discovery e /.

Python

Configurar o diretório do aplicativo

Para este exemplo, estruture a lógica do aplicativo como um módulo Python. Esse é o diretório webapp no exemplo fornecido.

Crie um diretório para o módulo de servidor, webapp, por exemplo. Mova o static para o diretório do módulo. Criar um diretório template no diretório do módulo. seus arquivos HTML vão aqui.

Criar o módulo de servidor*

Crie o arquivo __init__.py no diretório do módulo e adicione o seguinte importações e declarações.

from flask import Flask
import config

app = Flask(__name__)
app.config.from_object(config.Config)

# Load other module script files. This import statement refers to the
# 'routes.py' file described below.
from webapp import routes

Em seguida, crie um arquivo para processar as rotas desse app. Isso é webapp/routes.py no exemplo fornecido. Implemente as duas rotas neste .

from webapp import app
import flask

@app.route("/")
def index():
    return flask.render_template("index.html",
                                message="You've reached the index page.")

@app.route("/classroom-addon")
def classroom_addon():
    return flask.render_template(
        "addon-discovery.html",
        message="You've reached the addon discovery page.")

Nossos trajetos transmitem uma variável message para os respectivos Modelos Jinja. Isso é útil para identificar a página que o usuário acessou.

Criar arquivos de configuração e iniciar arquivos

No diretório raiz do seu aplicativo, crie o main.py e o config.py . Configure sua chave secreta no config.py.

import os

class Config(object):
    # Note: A secret key is included in the sample so that it works.
    # If you use this code in your application, replace this with a truly secret
    # key. See https://flask.palletsprojects.com/quickstart/#sessions.
    SECRET_KEY = os.environ.get(
        'SECRET_KEY') or "REPLACE ME - this value is here as a placeholder."

No arquivo main.py, importe o módulo e inicie o servidor Flask.

from webapp import app

if __name__ == "__main__":
    # Run the application over HTTPs with a locally stored certificate and key.
    # Defaults to https://localhost:5000.
    app.run(
        host="localhost",
        ssl_context=("localhost.pem", "localhost-key.pem"),
        debug=True)

Node.js

As rotas são registradas no arquivo app.js com as linhas a seguir.

const websiteRouter = require('./routes/index');
const addonRouter = require('./routes/classroom-addon');

app.use('/', websiteRouter);
app.use('/addon-discovery', addonRouter);

Abra /01-basic-app/routes/index.js e revise o código. Este trajeto é quando o usuário final acessa o site da empresa. A rota renderiza uma resposta usando o modelo do Handlebars index e transmite ao modelo uma Objeto de dados que contém as variáveis title e message.

router.get('/', function (req, res, next) {
  res.render('index', {
    title: 'Education Technology',
    message: 'Welcome to our website!'
  });
});

Abra a segunda rota (/01-basic-app/routes/classroom-addon.js) e revise o código. Esse trajeto é alcançado quando o usuário final acessa o complemento. Aviso que essa rota usa o modelo de Handlebars discovery e, além disso, o layout addon.hbs para renderizar a página de maneira diferente da empresa site.

router.get('/', function (req, res, next) {
  res.render('discovery', {
    layout: 'addon.hbs',
    title: 'Education Technology Classroom add-on',
    message: `Welcome.`
  });
});

Java

O exemplo de código Java usa módulos para empacotar o tutorial sequencial etapas. Como este é o primeiro tutorial, o código está na seção step_01_basic_app. não é esperado que você implemente projeto usando módulos; em vez disso, sugerimos que você crie com base em um único projeto conforme você segue cada etapa do tutorial.

Crie uma classe de controlador, Controller.java, neste exemplo de projeto para definem os endpoints. Nesse arquivo, importe a anotação @GetMapping de a dependência spring-boot-starter-web.

import org.springframework.web.bind.annotation.GetMapping;

Incluir a anotação do controlador do framework do Spring acima da classe definida para indicar o propósito da classe.

@org.springframework.stereotype.Controller
public class Controller {

Em seguida, implemente as duas rotas e uma rota adicional para tratamento de erros.

/** Returns the index page that will be displayed when the add-on opens in a
*   new tab.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the index page template if successful, or the onError method to
*   handle and display the error message.
*/
@GetMapping(value = {"/"})
public String index(Model model) {
  try {
    return "index";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Returns the add-on discovery page that will be displayed when the iframe
*   is first opened in Classroom.
*   @param model the Model interface to pass error information that's
*   displayed on the error page.
*   @return the addon-discovery page.
*/
@GetMapping(value = {"/addon-discovery"})
public String addon_discovery(Model model) {
  try {
    return "addon-discovery";
  } catch (Exception e) {
    return onError(e.getMessage(), model);
  }
}

/** Handles application errors.
*   @param errorMessage message to be displayed on the error page.
*   @param model the Model interface to pass error information to display on
*   the error page.
*   @return the error page.
*/
@GetMapping(value = {"/error"})
public String onError(String errorMessage, Model model) {
  model.addAttribute("error", errorMessage);
  return "error";
}

Testar o complemento

Importante :embora seja possível testar o aplicativo diretamente usando um navegador da Web, você deve testá-lo principalmente nos iframes de complementos do Google Sala de Aula. Carregando seu aplicativo da Web em um iframe pode produzir alguns comportamentos atípicos. Leia nosso iframe e parâmetros de consulta para ver a descrição de cada iframe. Tudo as instruções fornecidas neste tutorial presumem que o complemento pode ser usado no contexto de um iframe.

Inicie o servidor. Em seguida, faça login no Google Sala de Aula como uma dos seus Professores: Acesse a guia Atividades e crie uma Transferência. Selecione seu complemento no seletor Complementos. O iframe é aberto. e o complemento carregará o URI de configuração de anexos especificado na Página Configuração do app do SDK do Marketplace.

Parabéns! Você está pronto para prosseguir para a próxima etapa: como fazer login de usuários com o SSO do Google.