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 conocen el diseño orientado a recursos ni las APIs de Google Workspace.

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

Diseño orientado a recursos

Como se mencionó en Recursos de la API, la API de Classroom sigue patrones de diseño orientado a 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() para el 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 recursos secundarios (a veces llamados recursos secundarios), también se requieren identificadores para el recurso principal. Por ejemplo, cuando se crea un CourseWork dentro de un Course, se necesita el id de Course para establecer a qué Course pertenece el CourseWork.

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

Aplicar parche

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

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

Nota: Es posible que veas métodos update() junto con métodos patch(). Si bien ambos modifican un recurso, difieren en su comportamiento. Update() reemplaza por completo un recurso por uno nuevo, mientras que patch() solo actualiza los 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 las cosas, la API de Google Classroom usa casi exclusivamente patch(), y se recomienda que uses ese método en general.

Los métodos Patch() devuelven 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 según id o alias. La llamada a get() devuelve el recurso completo directamente.

El método list() recupera varios recursos del mismo tipo en una sola solicitud, sin necesidad de los identificadores de recursos individuales. A menudo, la operación list() obtiene todos los recursos secundarios de algún recurso principal, 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.

En general, los métodos list() tienen una cantidad máxima de recursos que se pueden devolver en una sola llamada, y se pueden configurar límites inferiores 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 devuelve 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 el 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, no se pueden modificar los usuarios asignados de un recurso CourseWork. En estos casos, hay métodos personalizados disponibles, como el método modifyAssignees. El comportamiento de estos métodos es personalizado, por lo que debes consultar la documentación de cada uno de ellos.