Configuração de projetos do Google Cloud

Esta página inclui as informações necessárias para criar e configurar projetos do Google Cloud para complementos do Google Sala de Aula. Os projetos do Google Cloud são usados para implementar o Logon único do Google pelo OAuth 2.0 (SSO do Google), para autorizar solicitações feitas pelo seu complemento e para gerenciar a listagem de um complemento na loja do Google Workspace Marketplace.

Para informações mais gerais sobre como publicar um complemento no Marketplace, consulte Publicar um app.

Criação de projetos do Google Cloud

Importante: o aplicativo de complemento de produção precisa ter a visibilidade pública definida no SDK do Google Workspace Marketplace. Um projeto privado pode ser útil para desenvolver e testar seu complemento, mas apenas um público é necessário.

Há dois tipos de projetos a serem criados: um privado usado para desenvolvimento e um público acessível pelos usuários finais. Os rótulos "público" e "particular" se referem à visibilidade do seu app no Google Workspace Marketplace. Um app particular do Marketplace só pode ser instalado por usuários no domínio em que foi criado, enquanto um app público do Marketplace está disponível para qualquer domínio do Google Workspace. Elas precisam ser duas solicitações separadas, porque um projeto não pode ser público e privado ao mesmo tempo. As solicitações públicas precisam ser analisadas e aprovadas antes de ficarem disponíveis no marketplace.

Importante: não é possível converter um projeto privado em público.

Para informações gerais sobre a criação de projetos do Google Cloud, acesse Criar um projeto do Google Cloud.

Criar um projeto público do Google Cloud

Esse projeto representa o aplicativo complementar que pode ser acessado por administradores, professores e estudantes. Um projeto público precisa ser analisado e aprovado pela equipe do Google Workspace Marketplace antes de ser lançado ou instalado.

1. Crie um novo projeto do Google Cloud no seu domínio de produção.

   Criar um projeto do Google Cloud

   Importante: verifique se o projeto pertence ao seu domínio de produção e se você fez login no console do Google Cloud como usuário desse domínio.
   Aviso: use a versão Draft do projeto para testes. No momento, o recurso de rascunho só está disponível no Programa de prévia para desenvolvedores do Google Workspace. Depois de criar o projeto do Cloud, preencha o formulário de inscrição para ativar os recursos do Programa de Prévia para Desenvolvedores do Google Workspace. Para mais informações, consulte Atualizar a página de detalhes do app com rascunhos.

2. Ative a API Classroom no seu projeto do Cloud.

   Ativar a API Classroom

3. Ative o SDK do Google Workspace Marketplace no seu projeto do Cloud.

   Ativar o SDK do Google Workspace Marketplace

4. Defina a Configuração do app Visibilidade do app do SDK do Marketplace como Público e marque a caixa Não listado.

   Ponto importante: não é possível compartilhar ou converter um projeto particular usado durante o desenvolvimento e o teste interno.
   Ponto importante: não é possível encontrar apps não listados no Google Workspace Marketplace pesquisando ou navegando. Na configuração do SDK do Marketplace, você pode encontrar um URL direto que pode ser usado para instalar o complemento. Somente o Google e o desenvolvedor podem encontrar a página da loja. O app precisa permanecer não listado até que você se sinta confortável para lançar para o público em geral. É possível alternar se um complemento está listado na página "Configuração do app" do SDK do Marketplace.

5. Preencha os campos obrigatórios na página Detalhes do app do SDK do Marketplace e clique em PUBLICAR.

6. Seu app será analisado pela equipe do Google Workspace Marketplace. Eles vão se comunicar com você usando o endereço de e-mail do desenvolvedor especificado no SDK do Marketplace. Depois que o app for aprovado, limpe a caixa Não listado para que professores e administradores possam encontrá-lo no Marketplace.

Criar um projeto privado do Google Cloud

Esse projeto privado representa o aplicativo complementar usado para desenvolvimento. Ela não é acessível a usuários fora do domínio em que foi criada, mas não precisa ser aprovada antes da instalação. Portanto, o Google recomenda usar esse projeto para desenvolver e testar seu complemento em um ambiente controlado.

Você precisa ter acesso a um domínio do Google Workspace for Education com a licença Teaching & Learning ou Plus para criar um projeto privado. Se você ainda não tiver acesso a esse domínio, siga estas etapas para configurar um domínio de demonstração do Google Workspace for Education, fazer upgrade para uma licença Plus e permitir que ele acesse a API de complementos do Google Sala de Aula:

1. Siga as etapas para receber um domínio de teste para desenvolvedores.

2. Com a sessão iniciada como administrador no domínio de demonstração, crie um novo projeto do Google Cloud.

   Criar um projeto do Google Cloud

   Aviso: verifique se o projeto pertence ao domínio de demonstração e se você fez login no console do Google Cloud usando uma conta de administrador do domínio de demonstração.

   Se você não conseguir acessar o console do Google Cloud ou criar projetos do Cloud, verifique o seguinte no console do administrador:

   • Acesse a página Configurações da conta > Configurações de acesso com base na idade e selecione a opção Todos os usuários neste grupo ou unidade organizacional têm 18 anos ou mais.
   • Em Apps > Serviços adicionais do Google:
   • O Google Cloud Platform está ATIVADO para todos.
   • As configurações de criação de projetos são Permitir que os usuários criem projetos.
   • As configurações de acesso ao Cloud Shell são Permitir acesso ao Cloud Shell.

3. Preencha e envie o formulário de solicitação de upgrade de domínio de demonstração. O envio deste formulário solicita que o Google faça upgrade do seu domínio de demonstração para o Google Workspace for Education Plus com dez licenças e permite que seu projeto do Cloud acesse a API de complementos do Classroom.

   Você vai receber um e-mail quando os processos de upgrade e lista de permissões forem concluídos. Atribua licenças Plus às contas de professores de teste no Admin Console. Em Diretório > Usuários, crie ou selecione as contas de professores de teste. Nas Licenças de cada professor, confirme se o Google Workspace for Education Plus está Atribuído.

4. Ative a API Classroom no seu projeto do Cloud.

   Ativar a API Classroom

5. Ative o SDK do Google Workspace Marketplace no seu projeto do Cloud.

   Ativar o SDK do Google Workspace Marketplace

6. Defina a configuração do app Visibilidade do app do SDK do Marketplace como privada.

7. Preencha os campos obrigatórios na página Detalhes do app do SDK do Marketplace e clique em PUBLISH. Depois que a página de informações do app for publicada, os usuários no domínio poderão encontrar e instalar o app no Google Workspace Marketplace ou abrindo o URL do app mostrado na página de informações do produto.

OAuth 2.0

O acesso à API Classroom requer consentimento para acesso aos dados do usuário. Eles são recebidos ao solicitar acesso do Google aos escopos OAuth para o usuário autenticado e receber um token que pode ser usado para fazer chamadas de API para o Google Sala de Aula. Os escopos precisam ser configurados na página de detalhes da loja do Google Workspace Marketplace para que o administrador do domínio possa dar consentimento em nome dos usuários do domínio se eles instalarem o complemento.

Importante: se o complemento solicitar escopos adicionais, inclua-os na tela de consentimento do OAuth, na guia "Configuração do app do SDK do Marketplace" e no código do aplicativo do complemento. Escopos incompatíveis nesses locais podem causar problemas para os usuários durante a instalação de complementos.

Como os escopos do Google Sala de Aula são sensíveis, é necessário solicitar a verificação do OAuth antes de lançar o complemento. Caso contrário, os usuários vão receber uma mensagem de aviso de que o aplicativo não foi verificado, e apenas um pequeno número de usuários poderá acessar seu produto. Consulte a visão geral da sequência de análise para mais informações sobre a verificação.

Aviso: se você estiver usando um projeto do Google Cloud para desenvolver um complemento, não solicite os novos escopos no código para produtos existentes até que a verificação seja concluída. Use um fluxo de autorização separado, um ambiente de teste ou defina uma flag de recurso para solicitar apenas esses escopos para as rotas relacionadas aos seus complementos antes de concluir a verificação.

Consulte a página Escopos do OAuth para APIs do Google para ver uma lista detalhada de todos os escopos disponíveis e seus usos. Consulte a página Configurar o OAuth na documentação do Workspace para informações gerais sobre a configuração do OAuth.

Permissões do usuário

Seu app da Web precisa solicitar pelo menos um dos seguintes escopos:

• https://www.googleapis.com/auth/userinfo.email, que permite que um aplicativo acesse o endereço de e-mail do usuário.
• https://www.googleapis.com/auth/userinfo.profile, que permite que um app acesse informações pessoais, como retrato, nome e sobrenome e outras informações pessoais que o usuário disponibilizou publicamente.

Depois que um usuário autoriza um desses escopos no seu complemento, eles são identificados pelo parâmetro de consulta login_hint. Esse parâmetro é transmitido para qualquer um dos URLs do seu app da Web quando um iframe é aberto. Se um usuário não tiver autorizado um desses escopos, o login_hint não será enviado.

Aviso: o app precisa solicitar pelo menos um dos escopos userinfo.email ou userinfo.profile para receber login_hint em visitas subsequentes do mesmo usuário.

login_hint é um parâmetro padrão do OpenID Connect que pode ser transmitido ao Google ao usar o Login do Google ou solicitar um token OAuth. O objetivo é tornar a experiência de autorização mais fácil para o usuário final.

Escopos dos complementos do Google Sala de Aula

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

• https://www.googleapis.com/auth/classroom.addons.teacher, que permite o acesso a todos os métodos da API.
• https://www.googleapis.com/auth/classroom.addons.student, que permite o acesso para iniciar operações de validação e leitura de anexos.

Mesmo com um token de acesso OAuth válido que indica as credenciais do usuário, as chamadas de API são bloqueadas por outros requisitos:

• Todos os métodos exigem que o usuário seja professor ou estudante no curso especificado pelo courseId na solicitação.
• A criação, a atualização, a exclusão e a devolução de notas de anexos exigem que o usuário seja um professor.
• As chamadas para uma postagem específica do Google Sala de aula são bloqueadas pelas seguintes verificações.
  • Quando um complemento já tem pelo menos um anexo em uma postagem, ele pode fazer solicitações para:
    • Validação de inicialização do iframe
    • Operações de leitura, atualização e exclusão de anexos
    • Atualizações de notas na postagem
  • Quando o iframe de descoberta de anexos é aberto pela primeira vez, o complemento pode não ter um anexo na postagem. Um parâmetro de consulta addOnToken é fornecido e pode ser usado para fazer solicitações para o seguinte:
    • Criar um anexo na postagem (addOnToken é obrigatório)
    • Validação de inicialização (addOnToken é validado se fornecido e é necessário quando o complemento não tem um anexo na publicação).

Verificação do OAuth

Observação: não é possível criar um vídeo de demonstração para enviar como parte do processo de verificação do OAuth. Em vez disso, publique o complemento sem verificar o OAuth. Isso alerta a equipe de análise do Google Workspace Marketplace para fazer um vídeo de demonstração em seu nome. Em seguida, a equipe de análise vai fornecer o vídeo para que você possa incluí-lo no envio de verificação do OAuth.

Um complemento do Google Sala de Aula usa as APIs do Google para acessar os dados dos usuários do Google.

• Verifique a identidade da sua marca.
• Verifique os escopos sensíveis do OAuth.

Consulte as Perguntas frequentes sobre a verificação da API OAuth para mais informações sobre o processo de verificação.

Ficha no Google Workspace Marketplace

Aviso: depois de salvar a opção de visibilidade durante o processo de publicação, não será possível mudar a seleção.

Para informações gerais sobre a configuração do SDK do Google Workspace Marketplace, acesse Ativar e configurar o SDK do Google Workspace Marketplace e Criar uma página de detalhes da loja do Google Workspace Marketplace.

Considerações sobre listagem

A Listagem da loja do SDK do Marketplace do seu projeto público do Google Cloud especifica o nome e as descrições do seu aplicativo para usuários finais. Você pode fornecer esses detalhes em vários idiomas em Detalhes do app.

Siga estas diretrizes nas suas listagens:

• Em Detalhes do app:

  • Evite pontuação no nome do aplicativo. Por exemplo, use My Add-on by My Company em vez de "My Company: My Add-on" ou "My Add-on, by My Company".

  • A Short Description e a Detailed Description não podem conter o mesmo texto.

  + Confira se você selecionou um valor para o campo Preços. Esse campo inclui opções de Sem custo financeiro, Pago com teste sem custo financeiro, Pago com recursos sem custo financeiro e Pago. Não é necessário especificar o valor do custo na listagem do Marketplace.

  • Verifique se você selecionou um valor para o campo Categoria. Recursos acadêmicos ou Ferramentas para professores e administradores podem ser boas opções de complemento do Google Sala de Aula.

  • Consulte os itens listados na descrição de detalhes do app do Marketplace para mais informações.

Importante: confira os detalhes do app para cada idioma em que você oferece o complemento.

• Em Recursos gráficos:

  • Todos os recursos gráficos fornecidos não são embaçados e atendem aos tamanhos especificados nos padrões do Google Workspace Marketplace

  • Todas as capturas de tela fornecidas são representações precisas da sua experiência com o complemento.

• Em Links de suporte:

  • Verifique se você forneceu um link para os Termos de Serviço do seu aplicativo.

• Confira se você está obedecendo às diretrizes de branding da API do Google, que abrangem nomes e descrições permitidos.

• Se você se referir a algum produto do Google na sua listagem, use o nome dele no formato fornecido na Lista de marcas registradas. Inclua o símbolo de marca registrada (™) se especificado. Use Google Docs™, não "Google Docs".

Integrar com os serviços de licenciamento e faturamento do Google

Se você quiser permitir que seus aplicativos do Google Workspace Marketplace sejam integrados aos serviços de licenciamento e faturamento do Google, acesse a API Marketplace.

Configurações de instalação

Os complementos podem permitir a instalação individual, além da instalação do administrador. Esta página destaca algumas diferenças entre os dois tipos de instalação. Não é intenção promover nenhum dos dois tipos de instalação. É possível permitir a instalação individual na página de configuração do app do SDK do Google Workspace Marketplace.

Instalação do administrador

As instalações do administrador permitem que um administrador adicione um complemento a todas as contas em um domínio ou a grupos de acesso ou unidades organizacionais específicos. Somente um administrador do domínio pode realizar uma instalação de administrador. O administrador pode consentir com todos os escopos de acesso em nome de todos os usuários no domínio. Os usuários não são solicitados a consentir com nenhum escopo de acesso se o administrador escolher fazer isso.

Confira a seguir algumas considerações sobre a instalação do administrador.

• Controles mais rígidos. Os administradores podem restringir os usuários que podem acessar um complemento.
• Compatibilidade com licenciamento. Se o aplicativo exigir uma licença, canalizar as instalações por um administrador pode ajudar a garantir que as licenças sejam distribuídas e usadas de maneira adequada com a instituição correspondente.
• Menor carga para os usuários finais. Uma instalação de administrador reduz a carga de configuração para professores e estudantes. Isso pode resultar em uma experiência de usuário mais suave, com menos cliques e menos oportunidades de confusão.

Consulte Instalar apps do Marketplace no seu domínio para mais informações sobre como realizar instalações de administrador e Como funciona a estrutura organizacional para saber mais sobre unidades organizacionais e grupos de acesso.

Instalação individual

As instalações individuais adicionam um complemento à conta do usuário. O usuário precisa consentir com os escopos de acesso do complemento durante a instalação.

Confira a seguir algumas considerações sobre a instalação individual.

• Facilitar a adoção. Mais usuários podem encontrar e instalar seu complemento no Google Workspace Marketplace. Permitir a instalação individual pode incentivar mais professores a adotarem ou defenderem seu produto.
• Testes de administrador. Um administrador pode instalar individualmente um complemento para testar ou avaliar antes de aprovar ou instalar para um grupo mais amplo.

Além de instalar complementos em nome dos usuários, os administradores também podem manter uma lista de permissões para permitir que os usuários instalem complementos que permitem a instalação individual. Se um complemento não estiver na lista de permissões, os usuários ainda vão poder conferir a listagem dele no Google Workspace Marketplace, mas não vão conseguir fazer a instalação. Em vez disso, eles vão receber uma mensagem explicando que a instalação do complemento não foi permitida por um administrador do domínio. Consulte Gerenciar apps do Google Workspace Marketplace na lista de permissões para saber mais sobre esse comportamento.

Consulte a documentação de configurações de instalação do Google Workspace Marketplace para mais informações.

Integração de apps

Você precisa fornecer um URL de iframe de inicialização no campo URI de configuração do anexo. Esse URL é usado como o valor src do iframe para o iframe de descoberta de anexos. O iframe de descoberta de anexos é usado pelos professores para encontrar conteúdo ou atividades para anexar à atividade.

Você também precisa especificar todos os prefixos de URI em que os anexos são permitidos no seu complemento. Esse recurso aumenta a segurança ao impedir anexos de fontes não autorizadas.

Consulte a página do guia de iframes para mais detalhes sobre esses campos.

Contas de teste

Crie contas de teste no seu domínio de demonstração para verificar o comportamento correto do complemento privado. Duas contas de estudante são necessárias para testar a alternância entre alunos no iframe da análise do trabalho do estudante.

Contas de teste sugeridas:

• Professora Tammy, tammy.teacher@<seu domínio de demonstração>
• Sam Student, sam.student@<seu domínio de demonstração>
• Sally Student, sally.student@<seu domínio de demonstração>

Siga este procedimento para criar uma conta de teste:

1. Faça login no Admin Console.
2. Acesse Usuários.
3. Clique em Adicionar novo usuário (consulte a Figura 1).
4. Insira as informações do usuário e atribua as funções adequadas.

Figura 1. Local do link Adicionar novo usuário no Admin Console.

Siga este procedimento para criar um novo grupo de teste:

1. Faça login no Admin Console.
2. Acesse Grupos.
3. Clique em Criar grupo (consulte a Figura 2).
4. Insira os membros e proprietários do grupo.

Figura 2. Local do link Create group no Admin Console.