Cómo funcionan las solicitudes

En esta página, se describe una descripción general de alto nivel de cómo funcionan las solicitudes en la API de Google Classroom. El objetivo es ayudar a los lectores que aún no están familiarizados con el diseño orientado a los recursos ni con las APIs de Google Workspace.

Para ver muestras de código específicas, consulta las guías de la API correspondientes, por ejemplo, Crea y administra cursos o Crea y administra el trabajo del curso.

Diseño orientado a recursos

Como se menciona en Estructura de la API, la API de Classroom sigue patrones de diseño orientado a los recursos. La mayoría de los recursos tienen métodos para operaciones estándar, como crear, leer, actualizar y borrar instancias del recurso.

Por ejemplo, es posible create(), patch(), get(), list() y delete() un Course de Classroom con la API.

Crear

Para crear un recurso nuevo, como un Course, llama al método create() del recurso correspondiente.

Las llamadas a Create() siempre requieren los detalles iniciales y críticos del recurso correspondiente como entrada. Por ejemplo, para crear un Course, llama al método create() en el recurso Course y especifica name y description en la solicitud, junto con información opcional, como room.

En el caso de los subrecursos (a veces llamados recursos secundarios), también se requieren identificadores para el recurso superior. Por ejemplo, cuando se crea un CourseWork dentro de un Course, se necesita el id de Course para establecer a qué Course pertenece CourseWork.

Los métodos Create() muestran una instancia del recurso recién creado en la respuesta de la llamada a la API. Por lo general, el recurso que se muestra tiene campos adicionales generados por el servidor, como el recurso id o creationTime.

Aplicar parche

Para modificar los recursos existentes, llama al método patch() (que a veces se llama update()) en el recurso correspondiente. El método patch() es casi idéntico a create(), con dos diferencias clave. Cuando llames al método patch(), debes especificar lo siguiente:

1. Es el id del recurso que se modificará.
2. Es una lista de campos, llamada updateMask, que determina qué campos del recurso se deben actualizar. Esto es opcional en los casos en que hay un conjunto predeterminado de campos o se infieren los campos.

Nota: Es posible que observes métodos update() junto con métodos patch(). Si bien ambos modifican un recurso, difieren en el comportamiento. Update() reemplaza por completo un recurso por uno nuevo, mientras que patch() solo actualiza campos seleccionados. Por ejemplo, courses.update() reemplaza un Course existente completo, mientras que courses.patch() usa el fieldMask mencionado anteriormente para modificar solo campos específicos en el Course. Para simplificar, la API de Google Classroom usa patch() casi de forma exclusiva, y se recomienda que uses ese método en general.

Los métodos Patch() muestran la instancia completa del recurso actualizado en la respuesta de la llamada a la API, con todos los cambios completados.

Obtener y enumerar

Existen dos métodos para recuperar recursos: get() y list().

El método get() recupera un recurso específico por algún identificador. Por ejemplo, recuperar un Course basado en id o alias. La llamada a get() muestra el recurso completo directamente.

El método list() recupera varios recursos del mismo tipo en una sola consulta, sin necesidad de los identificadores de recursos individuales. A menudo, la operación list() obtiene todos los subrecursos de algún recurso superior, por ejemplo, recupera todos los CourseWork dentro de un Course. Esto es útil para minimizar las solicitudes, en comparación con realizar varias llamadas a get(), y es particularmente valioso cuando no conoces el id de los recursos que deseas.

Por lo general, los métodos list() tienen una cantidad máxima de recursos que se pueden mostrar en una sola llamada, y se pueden configurar límites más bajos si se incluye un valor pageSize con la llamada. En los casos en que haya más recursos que el límite, el método list() admite la paginación. Cada "página" de resultados que se muestra proporciona un pageToken, que se puede incluir en una llamada list() posterior para recuperar el siguiente lote de recursos.

Borrar

El método delete() acepta un identificador de recursos, como id, y borra el recurso correspondiente. Si delete() se realiza correctamente, se muestra una respuesta vacía.

Otras operaciones

No todas las operaciones posibles con la API de Classroom se pueden lograr con las operaciones estándar mencionadas anteriormente, por ejemplo, modificar los destinatarios de un recurso CourseWork. En estos casos, están disponibles métodos personalizados, como el método modifyAssignees. El comportamiento de estos métodos es personalizado y debes consultar la documentación de cada uno de ellos.