Recursos de API

Este guia oferece uma visão geral dos principais componentes da 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 uma atividade, e os serviços recuperam e gerenciam esses recursos. Algumas dessas entidades têm propriedades adicionais específicas da API, além das que existem no Google Sala de Aula. Os principais tipos de entidades são:

Entidade	Representação no Google Sala de Aula
Cursos	Uma classe, como "M. Matemática do 4º período do Smith".
Aliases	Um ID alternativo para um curso.
Convites	Uma maneira de adicionar usuários a uma turma.
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	O trabalho de um estudante em uma determinada atividade, como respostas ou planilhas.
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 seu 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 leitura, atualização e exclusão de instâncias do recurso. Alguns recursos também têm métodos personalizados para outras operações, como modificar a lista de estudantes atribuídos 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 no Google Sala de Aula.
• Os aliases são usados como identificadores alternativos para Courses.
• Os convites são usados para convidar perfis de usuário a se tornarem professores ou estudantes em uma Course. No entanto, 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 compartilham com os estudantes nos cursos. Os tipos de itens do stream possíveis são Coursework, CourseWorkMaterials e Announcements. Os CourseWork e CourseWorkMaterials podem ser organizados visualmente em Tópicos e podem conter AddOnAttachments. Os estudantes enviam StudentSubmissions para o CourseWork.
• Os desenvolvedores podem criar registros para receber notificações quando alguns desses dados mudarem.

O Google Sala de Aula está disponível para domínios que assinam o Google Workspace for Education. Um domínio no contexto da 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 dá controle sobre uma instância de produção da Sala de Aula sem afetar usuários reais.

Cursos e aliases

Courses representa uma classe, como "M. Matemática do 4º período do Smith" e os professores atribuídos, a lista de estudantes e os metadados. Cada curso é identificado por um ID exclusivo atribuído pelo servidor. O recurso Course encapsula especificamente todos os metadados sobre o curso, como nome, descrição, local e horário. As listas de estudantes são gerenciadas pelos recursos Student, Teacher e Invitation e pelos métodos deles.

Aliases são identificadores alternativos de uma turma 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á dois namespaces compatíveis:

• Domínio:o namespace de domínio é útil para criar aliases a que todos os usuários precisam ter acesso, mas que não são específicos de nenhum programa. Por exemplo, as listagens alternativas de um curso, como MAT 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 ficam 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 os cursos do Google Sala de Aula. Os aliases criados nesse namespace estã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.

Turmas e usuários

Students e Teachers são mapeamentos específicos entre um perfil de usuário e um curso, representando a função desse 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 "estudante" ou "professor" representa um conjunto de permissões para um usuário específico em um curso específico. Um curso pode ter mais de um professor ou nenhum estudante. Professores e estudantes podem ser adicionados ou removidos de um curso a qualquer momento.

Estudantes

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

Os estudantes podem ver os detalhes e os professores do curso.

Professores

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

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

Invitations e os métodos associados oferecem uma maneira conveniente de adicionar estudantes e professores aos cursos. Com os convites, os usuários podem escolher se querem participar de um curso, em vez de serem adicionados diretamente por você usando os recursos para professores e estudantes.

UserProfiles representa um mapeamento para o perfil de domínio de um usuário, 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 o atalho "me".

O serviço UserProfiles também pode ser usado para gerenciar e convidar Guardians, que são 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.

Itens de stream

Os itens do stream são os conteúdos postados e compartilhados com os participantes de um curso. Os desenvolvedores e professores podem criar três tipos de itens de stream: Announcement, CourseWork e CourseWorkMaterial.

Os professores criam Announcements na parte de cima da página "Mural" na interface do Classroom. Os professores criam CourseWork e CourseWorkMaterials clicando no botão Criar na guia "Atividades". Os desenvolvedores podem criar todos os tipos de itens de stream de forma programática usando a API Classroom.

As seguintes afirmações sobre itens de stream são verdadeiras:

• Todos os itens do mural podem conter materiais complementares, como arquivos do Google Drive, vídeos do YouTube, Formulários Google, hiperlinks de URL e anexos de complementos do Google Sala de Aula.
• Todos os itens do mural podem ser atribuídos a um subconjunto de estudantes do curso.
• Um CourseWork pode ser classificado ou não. Os professores podem mudar o status de avaliação de uma atividade do CourseWork a qualquer momento.
• Um item do stream pode ter mais de um anexo.
• Um item de stream pode ter anexos de diferentes tipos. Por exemplo, uma atividade CourseWork pode ter arquivos do Google Drive, vídeos do YouTube e anexos de complementos do Google Sala de Aula ao mesmo tempo.
• Um item do stream pode ter anexos complementares de mais de um desenvolvedor.
• Os desenvolvedores podem acessar e modificar os detalhes de qualquer recurso de item do mural que tenha um dos anexos de complemento deles.
• Os desenvolvedores podem entregar, recuperar ou devolver o trabalho de um estudante em uma atividade do CourseWork que inclua um dos anexos de complemento.
• Os desenvolvedores só podem finalizar notas de envios individuais de estudantes em atividades criadas por eles.

Itens de transmissão copiados

Os professores podem copiar um item do mural copiando um curso, reutilizando uma atividade ou publicando um item do mural em vários cursos. Todas as novas cópias terão identificadores distintos, o que pode ser importante se você estiver desenvolvendo um complemento do Google Sala de Aula. Leia nosso guia sobre conteúdo copiado para entender como um complemento pode lidar com esses cenários.

CourseWork e StudentSubmissions

Um item CourseWork representa uma atividade para um grupo de estudantes em um curso. É o único tipo de item do mural que pode aceitar uma atividade enviada por um estudante. Um recurso CourseWork contém detalhes como descrição, data de vencimento, nota máxima e metadados, como hora de criação.

Cada recurso CourseWork descreve um dos seguintes tipos de tarefas:

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

O trabalho de um estudante em um item CourseWork é representado por um StudentSubmission. Ela consiste em uma resposta e metadados adicionais, como um estado e uma nota atribuída.

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

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

Para mais informações sobre como gerenciar atividades e envios de estudantes, consulte Gerenciar atividades.

CourseWorkMaterials e Announcements

Semelhante a CourseWork, CourseWorkMaterials representa o conteúdo atribuído a um grupo de estudantes em um curso. Cada recurso tem detalhes como título e descrição, além de materiais complementares. No entanto, ao contrário das CourseWork, as CourseWorkMaterials não exigem que os estudantes enviem materiais. Assim, 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 as regras da sala de aula.

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

Tópicos

Os Topics são usados para organizar visualmente CourseWork e CourseWorkMaterials em uma turma. Eles podem ser usados para agrupar atividades em "opcional" e "obrigatório", 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, geralmente exibidos em um iframe. Os complementos aparecem como anexos em um item do stream. 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 um conteúdo.

• Os anexos de atividades exigem que o estudante conclua e envie uma atividade individual. Por exemplo, quizzes, desenhos ou jogos. Uma atividade enviada pode ser avaliada.
• Os anexos de conteúdo não exigem um envio do estudante. O estudante não precisa entregar o anexo, e ele não é avaliado. Por exemplo, fotos, artigos e vídeos.

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

Registros

Os aplicativos podem se inscrever para receber notificações quando determinados dados mudarem 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 seu aplicativo.

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