Recursos de la API

En esta guía, se proporciona una descripción general de los componentes principales que conforman la API de Google Classroom. La API de Google Classroom consta de recursos y servicios. Los recursos representan entidades en Google Classroom, como un curso o una tarea, y los servicios recuperan y administran estos recursos. Algunas de estas entidades tienen propiedades adicionales específicas de la API, además de lo que existe en Classroom. Los tipos de entidades principales son los siguientes:

Entidad	Representación en Classroom
Cursos	Una clase, como “M. Matemáticas del 4º período de Smith".
Siglas	Es un ID alternativo para un curso.
Invitaciones	Es un medio para agregar usuarios a una clase.
Alumnos	Un estudiante en una clase.
Profesores	Un profesor en una clase
Perfiles de usuario	Un usuario de forma más genérica, fuera del contexto de estudiante o profesor.
CourseWork	Una tarea en una clase.
StudentSubmissions	Es el trabajo de un estudiante para una tarea determinada, como respuestas o hojas de cálculo.
CourseWorkMaterials	Son materiales para los estudiantes de una clase.
Anuncios	Un anuncio para los estudiantes de una clase.
AddOnAttachment	Contenido o una actividad en una tarea o un material que, por lo general, se muestra como un iframe incorporado.
Temas	Es una agrupación visual de tareas y materiales en una clase.
Registros	Una instrucción para enviar notificaciones a tu app sobre cambios en los datos, como una lista de clases.

La mayoría de los recursos tienen métodos de servicio para operaciones estándar, como leer, actualizar y borrar instancias del recurso. Algunos recursos también tienen métodos personalizados para otras operaciones, como modificar la lista de estudiantes a los que se les asignó una tarea en particular.

Para obtener información detallada sobre los recursos y métodos de la API, consulta la referencia de la API de Classroom.

Descripción general de las relaciones de recursos

• Curso es el objeto de datos fundamental de Google Classroom.
• Los alias se usan como identificadores alternativos para Courses.
• Las invitaciones se usan para invitar a perfiles de usuario a convertirse en profesores o estudiantes en un Course, pero los administradores de dominios de Google Workspace for Education también pueden agregar usuarios directamente.
• Los profesores crean elementos de transmisión y los comparten con los estudiantes en sus cursos. Los tipos de elementos de transmisión posibles son Trabajos, Materiales del curso y Anuncios. CourseWork y CourseWorkMaterials se pueden organizar visualmente en Topics y pueden contener AddOnAttachments. Los estudiantes envían StudentSubmissions para su CourseWork.
• Los desarrolladores pueden crear registros para recibir notificaciones cuando cambien algunos de estos datos.

Google Classroom está disponible para los dominios que se suscriben a Google Workspace for Education. Por lo general, un dominio en el contexto de Classroom representa un distrito escolar. Puedes crear un dominio de prueba de Google Workspace for Education para fines de desarrollo, lo que te brinda el control de una instancia de producción de Classroom sin afectar a los usuarios reales.

Cursos y alias

Courses representa una clase, como "M. Matemáticas del 4° período de Smith", y sus profesores asignados, lista de estudiantes y metadatos. Cada curso se identifica con un ID único que asigna el servidor. El recurso Course encapsula específicamente todos los metadatos sobre el curso, como el nombre, la descripción, la ubicación y la hora. Las listas de cursos se administran a través de los recursos Estudiante, Profesor y Invitación, y sus métodos.

Aliases son identificadores alternativos para una clase que pueden asociarse con un curso y usarse en lugar del ID único. Cada alias existe en un espacio de nombres que limita quién puede crearlo y verlo. Se admiten dos espacios de nombres:

• Dominio: El espacio de nombres de dominio es útil para crear alias a los que todos los usuarios deben tener acceso, pero que no son específicos de ningún programa. Por ejemplo, las fichas alternativas de un curso, como MATH 127 y COMSCI 127, se deben crear en el espacio de nombres del dominio. Solo los administradores de dominios pueden crear alias en el espacio de nombres del dominio, pero todos los usuarios de un dominio pueden verlos.
• Proyecto de desarrollador: El espacio de nombres del proyecto de desarrollador es útil para administrar alias específicos de una aplicación. Por ejemplo, una aplicación que usa identificadores alternativos para los cursos puede crear alias para asignar su identificador a los cursos de Classroom. Los alias creados en este espacio de nombres están vinculados a una Consola de API de Google específica. Cualquier usuario de una aplicación puede crear y ver alias en el espacio de nombres del proyecto de desarrollador de esa aplicación.

Para obtener más información sobre cómo administrar los metadatos y los alias de los cursos, consulta Administra cursos.

Usuarios y listas de cursos

Students y Teachers son asignaciones específicas entre un perfil de usuario y un curso, que representan el rol de ese usuario en el curso. Las designaciones de estudiante y profesor no son globales: un usuario puede asignarse como profesor para un curso y como estudiante en otro. La designación “estudiante” o “profesor” representa un conjunto de permisos para un usuario en particular en un curso determinado. Un curso puede tener más de un profesor o ningún estudiante. Los profesores y los alumnos se pueden agregar o quitar de un curso en cualquier momento.

Estudiantes

Un recurso Student representa a un usuario que se inscribió como estudiante en un curso específico.

Los estudiantes pueden ver los detalles del curso y a los profesores que lo integran.

Profesores

Un recurso Teacher representa a un usuario que imparte un curso específico.

Los profesores pueden ver y cambiar los detalles del curso, ver a los profesores y alumnos, y administrar a otros profesores y alumnos.

Invitations y sus métodos asociados proporcionan una forma conveniente de agregar estudiantes y profesores a los cursos. Crear invitaciones permite que los usuarios elijan unirse o no a un curso, en lugar de que los agregues directamente a través de los recursos para profesores y estudiantes.

UserProfiles representa una asignación al perfil de dominio de un usuario, como lo identifica el ID único o la dirección de correo electrónico del usuario que muestra la API de Directory. El usuario actual también puede hacer referencia a su propio ID con la abreviatura "me".

El servicio UserProfiles también se puede usar para administrar y invitar a Guardians, que es una asignación entre un estudiante y un tutor. Los tutores en Classroom tienen acceso a cierta información de los estudiantes, como sus tareas.

Para obtener más información sobre la administración de listas, consulta Administra profesores y alumnos.

Elementos de la transmisión

Los elementos de transmisión son los elementos de contenido publicados que se comparten con los miembros de un curso. Los desarrolladores y los profesores pueden crear tres tipos de elementos de transmisión: Announcement, CourseWork y CourseWorkMaterial.

Los profesores crean Announcements en la parte superior de la página Novedades en la IU de Classroom. Para crear CourseWork y CourseWorkMaterials, los profesores deben hacer clic en el botón Crear en la pestaña Trabajo en clase. Los desarrolladores pueden crear todos los tipos de elementos de transmisión de forma programática a través de la API de Classroom.

Los siguientes son verdaderos para los elementos de transmisión:

• Todos los elementos de la transmisión pueden contener materiales complementarios, como archivos de Google Drive, videos de YouTube, Formularios de Google, hipervínculos de URL y archivos adjuntos de complementos de Classroom.
• Todos los elementos de las novedades se pueden asignar a un subconjunto de los estudiantes del curso.
• Una CourseWork puede tener o no una calificación. Los profesores pueden cambiar el estado de calificación de una tarea de CourseWork en cualquier momento.
• Un elemento de transmisión puede tener más de un archivo adjunto.
• Un elemento de transmisión puede tener archivos adjuntos de diferentes tipos. Por ejemplo, una tarea de CourseWork puede tener archivos de Google Drive, videos de YouTube y archivos adjuntos de complementos de Classroom de forma simultánea.
• Un elemento de transmisión puede tener archivos adjuntos de complementos de más de un desarrollador.
• Los desarrolladores pueden obtener y modificar los detalles de cualquier recurso de elemento de novedades que tenga uno de sus archivos adjuntos de complementos.
• Los desarrolladores pueden entregar, reclamar o devolver la entrega de un estudiante para una tarea de CourseWork que incluya uno de sus archivos adjuntos de complementos.
• Los desarrolladores solo pueden finalizar las calificaciones de las tareas individuales que hayan creado.

Elementos de transmisión copiados

Los profesores pueden copiar un elemento de transmisión copiando un curso, reutilizando una tarea o publicando un elemento de transmisión en varios cursos. Las copias nuevas tendrán identificadores distintos, lo que puede ser una consideración importante si estás desarrollando un complemento de Classroom. Lee nuestra guía sobre contenido copiado para comprender cómo un complemento puede controlar estas situaciones.

CourseWork y StudentSubmissions

Un elemento CourseWork representa una tarea para un grupo de estudiantes en un curso. Es el único tipo de elemento de la sección Novedades que puede aceptar el envío de un estudiante. Un recurso CourseWork contiene detalles como la descripción, la fecha límite, la calificación máxima y metadatos como la fecha de creación.

Cada recurso CourseWork describe uno de los siguientes tipos de tareas:

• Es una tarea que los estudiantes completan cuando envían hojas de cálculo o otros archivos adjuntos.
• Una pregunta de respuesta corta o de opción múltiple.

El trabajo del estudiante para un elemento CourseWork se representa con un StudentSubmission. Consiste en una respuesta y metadatos adicionales, como un estado y una calificación asignada.

El contenido de un StudentSubmission depende del tipo del elemento CourseWork correspondiente y puede incluir lo siguiente:

• Las hojas de cálculo y los archivos adjuntos enviados para una tarea, incluidos su título, miniatura y URL, así como los identificadores que se pueden usar con las APIs adecuadas, como Drive o YouTube.
• Es la respuesta a una pregunta de respuesta breve o de opción múltiple.

Para obtener más información sobre cómo administrar el trabajo de los estudiantes y las tareas, consulta Cómo administrar el trabajo de los estudiantes.

Anuncios y materiales del curso

Al igual que CourseWork, CourseWorkMaterials representa el contenido asignado a un grupo de estudiantes en un curso. Cada recurso tiene detalles como un título y una descripción, además de materiales complementarios. Sin embargo, a diferencia de CourseWork, CourseWorkMaterials no requiere que los estudiantes envíen ningún artefacto. Por lo tanto, no hay fecha límite, y StudentSubmissions no existe para CourseWorkMaterials. Los profesores pueden usar CourseWorkMaterials para publicar lecturas sugeridas, un plan de estudios o las reglas del aula.

Announcements también representa contenido compartido con un grupo de estudiantes, pero no tiene detalles como un título y no se puede organizar por Topics como CourseWork o CourseWorkMaterials. Los profesores pueden usarlos para anunciar recordatorios o avisos a la clase.

Temas

Topics se usa para organizar visualmente CourseWork y CourseWorkMaterials dentro de una clase. Se pueden usar para agrupar tareas en “opcional” y “obligatoria”, o “unidad 1” y “unidad 2”, por ejemplo.

Complementos de Classroom

Un complemento es una IU y un backend que se entrega a los desarrolladores y, por lo general, se muestra en un iframe. Los complementos aparecen como archivos adjuntos en un elemento de transmisión. El elemento de transmisión puede ser cualquier Announcements, CourseWork o CourseWorkMaterials. Los archivos adjuntos de complementos se representan con un AddOnAttachment.

Los archivos adjuntos de complementos pueden ser una actividad o contenido.

• Los archivos adjuntos de actividades requieren que un estudiante complete y entregue una entrega individual. Algunos ejemplos son cuestionarios, dibujos o juegos. De manera opcional, se puede calificar el envío de una actividad.
• Los archivos adjuntos de contenido no requieren que los estudiantes realicen una entrega. El estudiante no necesita entregar el archivo adjunto, y no se le asigna una calificación. Algunos ejemplos son las fotos, los artículos y los videos.

Consulta las guías de desarrollo de complementos para obtener más información.

Registros

Las aplicaciones pueden suscribirse para recibir notificaciones cuando cambien ciertos datos en Google Classroom. Por ejemplo, cuando se actualiza la lista de un curso. Registrations representa una instrucción para enviar estas notificaciones a tu aplicación.

Consulta la guía de notificaciones push para obtener más información.