Recursos de 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 uma 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:

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 de transmissão e os compartilham com os estudantes nos cursos. Os possíveis tipos de itens de transmissão são trabalho escolar, materiais do trabalho escolar e avisos. O CourseWork e o CourseWorkMaterials podem ser organizados visualmente em Tópicos 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.

A 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 representa uma classe, como "M. Aula de matemática do 4º período do Smith", além dos professores, lista de estudantes e metadados atribuídos. 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 pelos 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á 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 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. Um curso pode ter mais de um professor ou nenhum aluno. 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 conferir os detalhes do curso e os professores dele.

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. Com a criação de convites, os usuários podem escolher se querem ou não participar de um curso, em vez de serem adicionados diretamente pelos recursos de 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 se referir ao 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.

Itens de transmissão

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

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

As seguintes informações são verdadeiras para os itens de transmissão:

• Todos os itens de transmissão 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 stream podem ser atribuídos a um subconjunto de estudantes no curso.
• Um CourseWork pode ser avaliado ou não. Os professores podem mudar o status de avaliação de uma atividade CourseWork a qualquer momento.
• Um item de transmissão pode ter mais de um anexo.
• Um item de transmissão pode ter anexos de tipos diferentes. Por exemplo, uma atividade CourseWork pode ter arquivos do Google Drive, vídeos do YouTube e anexos do complemento do Google Sala de Aula ao mesmo tempo.
• Um item de transmissão pode ter anexos de complementos de mais de um desenvolvedor.
• Os desenvolvedores podem acessar e modificar os detalhes de qualquer recurso de item do Stream que tenha um dos anexos de complemento.
• Os desenvolvedores podem entregar, recuperar ou devolver o envio de um estudante para uma atividade CourseWork que inclui um dos anexos do complemento.
• Os desenvolvedores só podem finalizar as notas de envios de estudantes individuais em atividades criadas por eles.

Itens de streaming copiados

Os professores podem copiar um item de transmissão copiando um curso, reutilizando uma atividade ou publicando um item de transmissão em vários cursos. Todas as novas cópias terão identificadores diferentes, o que pode ser uma consideração 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.

Atividades acadêmicas e envios dos estudantes

Um item CourseWork representa uma atividade para um grupo de estudantes em um curso. É o único tipo de item de transmissão que pode aceitar uma entrega do estudante. Um recurso CourseWork contém detalhes como a descrição, a data de vencimento, a nota máxima e metadados, como a hora da 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 dos estudantes para um item CourseWork é representado por um StudentSubmission. Ele 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 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 mais informações sobre como gerenciar trabalhos e envios de estudantes, consulte Gerenciar trabalhos.

CourseWorkMaterials and Announcements

Assim como 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 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.

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 avisos para anunciar lembretes ou avisos para a turma.

Tópicos

Os 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 transmissão 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. O envio de uma atividade pode ser avaliado.
• 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.