Estrutura da API

Este guia apresenta uma visão geral dos principais componentes que compõem a API Google Classroom. A API Google Classroom consiste em recursos e serviços. Os recursos representam entidades no Google Sala de Aula, como um curso ou atividade, e os serviços recuperam e gerenciam esses recursos. Algumas dessas entidades têm propriedades adicionais específicas para a API, além das que existem no Classroom. Os tipos de entidade principais são:

Entidade	Representação na sala de aula
Cursos	Uma classe, como "M. matemática do quarto período de Smith".
Aliases	Um ID alternativo para um curso.
Convites	Um meio de adicionar usuários a uma classe.
Alunos	Um estudante em uma turma.
Professores	Um professor em uma turma.
Perfis de usuário	Um usuário de forma mais genérica, fora do contexto de estudante ou professor.
CourseWork	Uma atividade em uma turma.
StudentSubmissions	Os estudantes trabalham em uma determinada tarefa, como respostas ou folhas de atividades.
CourseWorkMaterials	Materiais para estudantes em uma turma.
Announcements	Um aviso para os estudantes de uma turma.
AddOnAttachment	Conteúdo ou atividade em uma atividade ou material que normalmente é exibido como um iframe incorporado.
Temas	Um agrupamento visual de atividades e materiais em uma turma.
Registros	Uma instrução para enviar notificações ao app sobre mudanças nos dados, como uma lista de alunos de uma turma.

A maioria dos recursos tem métodos de serviço para operações padrão, como ler, atualizar e excluir instâncias do recurso. Alguns recursos também têm métodos personalizados para outras operações, como modificar a lista de estudantes atribuídas a uma atividade específica.

Para informações detalhadas sobre os recursos e métodos da API, consulte a referência da API Classroom.

Visão geral das relações de recursos

• O curso é o objeto de dados fundamental do Google Sala de Aula.
• Os aliases são usados como identificadores alternativos para Courses.
• Os convites são usados para convidar perfis de usuários a se tornarem professores ou alunos em uma Course, mas os usuários também podem ser adicionados diretamente pelos administradores de domínio do Google Workspace for Education.
• Os professores criam itens do mural e os compartilham com os alunos nos cursos. Os tipos de itens de transmissão possíveis são trabalho escolar, materiais do trabalho escolar e avisos. CourseWork e CourseWorkMaterials podem ser organizados visualmente em Topics e podem conter AddOnAttachments. Os estudantes enviam StudentSubmissions para CourseWork.
• Os desenvolvedores podem criar registros para receber notificações quando alguns desses dados forem alterados.

O Google Sala de Aula está disponível para domínios que assinam o Google Workspace for Education. Um domínio no contexto do Google Sala de Aula geralmente representa um distrito escolar. É possível criar um domínio de teste do Google Workspace for Education para fins de desenvolvimento, o que permite controlar uma instância de produção do Google Sala de Aula sem afetar usuários reais.

Cursos e aliases

Courses representam uma classe, como "M. matemática do 4o período de Smith" e os professores, lista de alunos e metadados atribuídos a ele. Cada curso é identificado por um ID exclusivo atribuído pelo servidor. O recurso Course encapsula especificamente todos os metadados do curso, como nome, descrição, local e hora. As listas de alunos dos cursos são gerenciadas por meio dos recursos Estudante, Professor e Convite e seus métodos.

Aliases são identificadores alternativos de uma classe que podem ser associados a um curso e usados no lugar do ID exclusivo. Cada alias existe em um namespace que restringe quem pode criar e visualizar. Há suporte para dois namespaces:

• Domínio: o namespace do domínio é útil para criar aliases aos quais todos os usuários precisam acessar, mas que não são específicos de nenhum programa. Por exemplo, as listagens alternativas de um curso, como MATH 127 e COMSCI 127, precisam ser criadas no namespace do domínio. Os aliases no namespace do domínio só podem ser criados por administradores de domínio, mas são visíveis para todos os usuários em um domínio.
• Projeto do desenvolvedor:o namespace do projeto do desenvolvedor é útil para gerenciar aliases específicos de um aplicativo. Por exemplo, um aplicativo que usa identificadores alternativos para cursos pode criar aliases para mapear o identificador para cursos do Google Sala de Aula. Os aliases criados neste espaço são vinculados a um Console de APIs do Google específico. Qualquer usuário de um aplicativo pode criar e visualizar aliases no namespace do projeto de desenvolvedor desse aplicativo.

Para mais informações sobre como gerenciar metadados e aliases de cursos, consulte Gerenciar cursos.

Listas de usuários e cursos

Students e Teachers são mapeamentos específicos entre um perfil de usuário e um curso, representando a função do usuário no curso. As designações de estudante e professor não são globais: um usuário pode ser atribuído como professor em um curso e estudante em outro. A designação "aluno" ou "professor" representa um conjunto de permissões para um usuário específico em um curso específico.

Estudantes

Um recurso Student representa um usuário matriculado como estudante em um curso específico.

Os estudantes podem acessar os detalhes do curso e os professores desse curso.

Professores

Um recurso Teacher representa um usuário que ensina um curso específico.

Os professores podem acessar e mudar os detalhes do curso, conferir professores e estudantes e gerenciar outros professores e estudantes.

O Invitations e os métodos associados oferecem uma maneira conveniente de adicionar alunos e professores aos cursos. A criação de convites permite que os usuários escolham se querem participar de um curso, em vez de você adicioná-los diretamente por meio dos recursos para professores e alunos.

UserProfiles representa um mapeamento para o perfil de domínio de um usuário, conforme identificado pelo ID exclusivo ou endereço de e-mail do usuário retornado pela API Directory. O usuário atual também pode consultar o próprio ID usando a abreviação "me".

O serviço UserProfiles também pode ser usado para gerenciar e convidar Guardians, que é um mapeamento entre um estudante e um responsável. Os responsáveis no Google Sala de Aula têm acesso a algumas informações dos estudantes, como as atividades.

Para mais informações sobre como gerenciar turmas, consulte Gerenciar professores e alunos.

Atividades do curso e envios dos estudantes

Um item CourseWork representa uma única tarefa atribuída a um grupo de estudantes em um curso. Ele contém detalhes como a descrição, a data de entrega e os materiais, além de metadados como a hora da criação. Os materiais incluem um título, miniatura e URL, além de um identificador que pode ser usado com as APIs apropriadas (por exemplo, Drive, YouTube).

Os itens CourseWork descrevem um dos seguintes tipos de tarefas:

• Uma tarefa que os estudantes realizam enviando planilhas ou outros anexos.
• Uma pergunta de resposta curta ou de múltipla escolha.

O trabalho dos estudantes para um item CourseWork é representado por um StudentSubmission. Ela consiste em uma resposta e outros metadados, como um estado e a nota atribuída.

O conteúdo de um StudentSubmission depende do tipo do item CourseWork correspondente:

• As planilhas e os anexos enviados para uma atividade, incluindo o título, a miniatura e o URL, além de identificadores que podem ser usados com as APIs apropriadas, como o Drive ou o YouTube.
• A resposta para uma pergunta de resposta curta ou de múltipla escolha.

Para saber mais sobre como gerenciar as atividades e os envios dos alunos, consulte Gerenciar a página "Atividades".

Materiais do curso e avisos

Assim como CourseWork, CourseWorkMaterials representa o conteúdo atribuído a um grupo de estudantes em um curso, com detalhes como título e descrição, além de materiais. No entanto, ao contrário da CourseWork, a CourseWorkMaterials não exige que os estudantes enviem artefatos. Portanto, não há data de entrega e StudentSubmissions não existe para CourseWorkMaterials. Os professores podem usar CourseWorkMaterials para postar leituras sugeridas, um plano de aulas ou regras da sala de aula, por exemplo.

Announcements também representa conteúdo compartilhado com um grupo de estudantes, mas não têm detalhes, como título, e não podem ser organizados por Topics, como CourseWork ou CourseWorkMaterials. Os professores podem usar esses avisos para anunciar lembretes ou avisos para a turma.

Tópicos

Topics são usados para organizar visualmente CourseWork e CourseWorkMaterials em uma classe. Elas podem ser usadas para agrupar atribuições em "opcionais" e "obrigatórias" ou "unidade 1" e "unidade 2", por exemplo.

Complementos do Google Sala de Aula

Um complemento é uma interface e um back-end fornecidos pelo desenvolvedor, normalmente exibidos em um iFrame. Os complementos aparecem como anexos em um item de transmissão. O item de stream pode ser qualquer Announcements, CourseWork ou CourseWorkMaterials. Os anexos de complementos são representados por um AddOnAttachment.

Os anexos de complementos podem ser uma atividade ou conteúdo.

• Os anexos de atividades exigem que o estudante conclua e envie uma atividade individual. Por exemplo, testes, desenhos ou jogos. Um envio de atividade pode receber nota.
• Os anexos de conteúdo não exigem envio do estudante. O estudante não precisa entregar o anexo, e ele não é avaliado. Exemplos incluem fotos, artigos e vídeos.

Consulte os guias de desenvolvimento de complementos para mais informações.

Registros

Os apps podem se inscrever para receber notificações quando determinados dados mudam no Google Sala de Aula. Por exemplo, quando a lista de um curso é atualizada. Registrations representa uma instrução para enviar essas notificações ao aplicativo.

Consulte o guia de notificações push para saber mais.