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 las que existen 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".
Alias	Es un ID alternativo para un curso.
Invitaciones	Es un medio para agregar usuarios a una clase.
Alumnos	Es un estudiante de 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	Es una tarea en una clase.
StudentSubmissions	Es el trabajo de un estudiante para una tarea determinada, como respuestas u hojas de trabajo.
CourseWorkMaterials	Son los materiales para los estudiantes de una clase.
Anuncios	Es un anuncio para los estudiantes de una clase.
AddOnAttachment	Contenido o actividad en una tarea o material que suele mostrarse como un iframe incorporado.
Temas	Es una agrupación visual de tareas y materiales en una clase.
Registros	Es una instrucción para enviar notificaciones a tu app sobre los cambios en los datos, como la lista de una clase.

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

• El curso es el objeto de datos fundamental en 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 dominio de Google Workspace for Education también pueden agregar usuarios directamente.
• Los profesores crean elementos del tablón y los comparten con los estudiantes de sus cursos. Los tipos de elementos de transmisión posibles son Coursework, CourseWorkMaterials y Announcements. CourseWork y CourseWorkMaterials se pueden organizar visualmente en Temas 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. En el contexto de Classroom, un dominio suele representar 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, la lista de estudiantes y los metadatos. Cada curso se identifica con un ID único asignado por 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 Student, Teacher y Invitation y sus métodos.

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

• Dominio: El espacio de nombres del dominio es útil para crear alias a los que todos los usuarios necesitan acceder, 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 del dominio pueden crear alias en el espacio de nombres del dominio, pero todos los usuarios de un dominio pueden verlos.
• Proyecto para desarrolladores: El espacio de nombres del proyecto para desarrolladores 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 APIs de Google específica. Cualquier usuario de una aplicación puede crear y ver alias en el espacio de nombres del proyecto para desarrolladores de esa aplicación.

Para obtener más información sobre la administración de alias y metadatos de cursos, consulta Administra cursos.

Listas de cursos y usuarios

Students y Teachers son asignaciones específicas entre un perfil de usuario y un curso, que representan el rol del usuario en el curso. Las designaciones de estudiante y profesor no son globales: a un usuario se le puede asignar el rol de profesor en un curso y el de estudiante en otro. Las designaciones "estudiante" o "profesor" representan un conjunto de permisos para un usuario específico en un curso en particular. Un curso puede tener más de un profesor o ningún estudiante. Los profesores y los estudiantes se pueden agregar o quitar de un curso en cualquier momento.

Estudiantes

Un recurso Student representa a un usuario que está inscrito 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 enseña un curso específico.

Los profesores pueden ver y cambiar los detalles del curso, ver a los profesores y estudiantes, y administrar a los profesores y estudiantes adicionales.

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 si quieren unirse 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, identificado por el ID único o la dirección de correo electrónico del usuario que devuelve 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 e invitar a Guardians, que son 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 estudiantes.

Elementos de la transmisión

Los elementos del flujo son las publicaciones de contenido 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. Los profesores crean CourseWork y CourseWorkMaterials haciendo clic en el botón Crear en la pestaña Trabajo en clase. Los desarrolladores pueden crear todos los tipos de elementos de la transmisión de forma programática a través de la API de Classroom.

Los siguientes enunciados son verdaderos sobre los elementos de transmisión:

• Todos los elementos del flujo 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 calificación. Los profesores pueden cambiar el estado de calificación de una tarea de CourseWork en cualquier momento.
• Un elemento del flujo puede tener más de un adjunto.
• Un elemento de transmisión puede tener archivos adjuntos de diferentes tipos. Por ejemplo, una tarea CourseWork podría tener archivos de Google Drive, videos de YouTube y archivos adjuntos de complementos de Classroom de forma simultánea.
• Un elemento de la 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 complemento.
• 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 complemento.
• Los desarrolladores solo pueden finalizar las calificaciones de los envíos individuales de los estudiantes en las tareas que crearon.

Elementos de la transmisión copiados

Los profesores pueden copiar un elemento del flujo copiando un curso, reutilizando una tarea o publicando un elemento del flujo en varios cursos. Las copias nuevas tendrán identificadores distintos, lo que puede ser una consideración importante si desarrollas un complemento de Classroom. Lee nuestra guía sobre el 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 secuencia que puede aceptar envíos de estudiantes. 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:

• Tarea que los estudiantes completan enviando hojas de trabajo o otros archivos adjuntos.
• Una pregunta de respuesta corta o de opción múltiple

El trabajo de los estudiantes para un elemento CourseWork se representa con un StudentSubmission. Consta de 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 trabajo 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 del curso y los envíos de los estudiantes, consulta Administra el trabajo del curso.

Materiales y anuncios 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 ni StudentSubmissions para CourseWorkMaterials. Los profesores pueden usar CourseWorkMaterials para publicar lecturas sugeridas, un programa de estudios o las reglas del aula.

Los Announcements también representan el contenido compartido con un grupo de estudiantes, pero no tienen detalles como un título y no se pueden organizar por Topics como CourseWork o CourseWorkMaterials. Los profesores pueden usar estos canales para anunciar recordatorios o avisos a la clase.

Temas

Topics se usan para organizar visualmente CourseWork y CourseWorkMaterials dentro de una clase. Por ejemplo, se pueden usar para agrupar tareas en "opcionales" y "obligatorias", o "unidad 1" y "unidad 2".

Complementos de Classroom

Un complemento es una IU y un backend que proporciona el desarrollador y que, por lo general, se muestra en un iframe. Los complementos aparecen como archivos adjuntos en un elemento de la 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 el estudiante complete y envíe una entrega individual. Algunos ejemplos incluyen cuestionarios, dibujos o juegos. Opcionalmente, se puede calificar la entrega de una actividad.
• Los archivos adjuntos de contenido no requieren que los estudiantes envíen una entrega. El estudiante no necesita entregar el archivo adjunto y no se califica. Algunos ejemplos son las fotos, los artículos y los videos.

Si deseas obtener más información, consulta las guías para desarrolladores de complementos.

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.