Accede a las APIs de vista previa

En esta página, se describe cómo acceder a las funciones de vista previa de la API de Classroom y especificar versiones de vista previa.

Las tres consideraciones que se deben tener en cuenta cuando se usan funciones en versión preliminar en comparación con la API de v1 estable son las siguientes:

1. El proyecto de Google Cloud que realiza la llamada debe estar inscrito en el Programa de Versión preliminar para desarrolladores de Google Workspace y estar en la lista de entidades permitidas de Google.
2. Las funciones de la API en programas de acceso anticipado o versión preliminar no se exponen en las bibliotecas cliente estándar y es posible que no se pueda acceder a ellas de forma predeterminada a través de HTTP.
3. En cualquier momento, puede haber varios estados o versiones de la API en versión preliminar.

Habilita las funciones de vista previa en las bibliotecas cliente

Una opción común para consumir la API de Classroom es con una biblioteca cliente. Existen tres tipos de bibliotecas cliente:

1. Bibliotecas cliente generadas de forma dinámica
2. Bibliotecas cliente estáticas proporcionadas por Google
3. Tu propia biblioteca cliente personalizada

Usar bibliotecas estáticas generadas de forma dinámica o proporcionadas por Google es la forma recomendada de usar la API. Consulta cómo compilar bibliotecas cliente si necesitas compilar tu propia biblioteca. Crear tu propia biblioteca está fuera del alcance de esta guía, pero debes revisar la sección sobre bibliotecas dinámicas para obtener información sobre las etiquetas de vista previa y su función en Discovery.

Bibliotecas dinámicas

Las bibliotecas en lenguajes como Python generan la biblioteca cliente en el tiempo de ejecución con un documento de descubrimiento del servicio de descubrimiento.

Un documento de descubrimiento es una especificación legible por máquina para describir y consumir APIs de REST. Se usa para compilar bibliotecas cliente, complementos de IDE y otras herramientas que interactúan con las APIs de Google. Un servicio puede proporcionar varios documentos de descubrimiento.

Los documentos de descubrimiento para el servicio de la API de Classroom (classroom.googleapis.com) se pueden encontrar en el siguiente extremo:

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

La distinción importante para trabajar con APIs en versión preliminar es especificar el label adecuado. En el caso de las versiones preliminares públicas de Classroom, la etiqueta es DEVELOPER_PREVIEW.

Para generar la biblioteca de Python y crear una instancia del servicio de Classroom con métodos de vista previa, puedes especificar la URL de Discovery con el servicio, las credenciales y la etiqueta adecuados:

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

Consulta la documentación de la biblioteca cliente de cada API de Google para obtener detalles sobre cada lenguaje.

Bibliotecas estáticas

Las bibliotecas cliente en lenguajes como Java, Node.js, PHP, C# y Go deben compilarse desde el código fuente. Estas bibliotecas se proporcionan para ti y ya incorporan las funciones de vista previa.

En el caso de las versiones preliminares públicas, las bibliotecas cliente de Classroom se pueden encontrar con las otras bibliotecas cliente del Programa de Versión preliminar para desarrolladores de Workspace. En el caso de las vistas previas privadas, comunícate con tu contacto de Google si necesitas que se generen bibliotecas estáticas.

Es posible que debas modificar la configuración de dependencias habitual para usar estas bibliotecas locales en lugar de importar las bibliotecas cliente estándar, que no tienen las funciones de vista previa.

Por ejemplo, para usar la biblioteca cliente de Go, debes usar la directiva replace en tu archivo go.mod para requerir un módulo de un directorio local:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

Como otro ejemplo, si usas Node.js y npm, agrega la descarga de la biblioteca cliente de Node.js (googleapis-classroom-1.0.4.tgz) como una dependencia local en package.json:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

Luego, en tu aplicación, requiere el módulo classroom-with-preview-features además de las dependencias normales y crea una instancia del servicio classroom desde ese módulo:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithPreviewFeatures = require('classroom-with-preview-features');

...

const classroom = classroomWithPreviewFeatures.classroom({
  version: 'v1',
  auth: auth,
});

...

Cómo especificar una versión de API de vista previa

Independientemente de si usas una biblioteca estática o dinámica, debes especificar la versión preliminar cuando realices llamadas a la API para invocar métodos con capacidades de versión preliminar.

Las diferentes versiones disponibles y las funciones que incluyen se documentan en la Hoja de ruta de la API de Classroom. La documentación de referencia de los métodos y los campos también describe en qué versiones están disponibles.

Para especificar una versión, se debe configurar el campo PreviewVersion en las solicitudes. Por ejemplo, para crear una rúbrica con la API de vista previa de CRUD de rúbricas, debes establecer previewVersion en V1_20231110_PREVIEW en la solicitud de CREATE:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

Nota: Las versiones preliminares están diseñadas para ser temporales mientras se validan las funciones para la disponibilidad general en la API de v1. El comportamiento de la versión preliminar está sujeto a cambios después del período de baja. Consulta la Hoja de ruta de la API de Classroom para obtener más información.

Los recursos asociados con una llamada al método de vista previa también contienen el previewVersion que se usó en la llamada como un campo de solo lectura, para ayudarte a comprender qué versión estás usando. Por ejemplo, la respuesta de la llamada CREATE anterior contiene el valor V1_20231110_PREVIEW:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

Nota: La versión preliminar asociada a un recurso corresponde a la versión que se usa para recuperar el recurso, no necesariamente a la llamada para crear el recurso. Si realizaste una llamada GET, LIST o PATCH futura con una versión nueva especificada, se devolvería la versión nueva.

Solicitudes HTTP

También es posible consumir la API de Classroom directamente con HTTP.

Si realizas solicitudes HTTP sin una biblioteca cliente, debes habilitar las funciones en versión preliminar y especificar una versión preliminar. Para ello, se establece un label con un encabezado X-Goog-Visibilities y la versión preliminar mencionada anteriormente como un parámetro de consulta o un campo del cuerpo de POST (consulta la documentación de referencia de la API individual correspondiente). Para las versiones preliminares públicas, la etiqueta es DEVELOPER_PREVIEW.

Por ejemplo, la siguiente solicitud curl realiza una llamada LIST al servicio de rúbricas con la etiqueta de visibilidad y la versión de vista previa adecuadas:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

También puedes especificar la versión preliminar en el cuerpo de la solicitud, por ejemplo, cuando realizas una solicitud POST:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

La API para cada solicitud HTTP se describe en la documentación de REST.

Google Apps Script

Es posible llamar a las APIs de vista previa desde Google Apps Script. Sin embargo, existen algunas diferencias con respecto al uso típico de Apps Script.

1. Debes configurar tu secuencia de comandos para que use el proyecto de Google Cloud en el que te inscribiste en el Programa de versión preliminar para desarrolladores.
2. Los Servicios avanzados no admiten métodos de vista previa, por lo que deberás realizar solicitudes directamente con HTTP.
3. Debes proporcionar una etiqueta y una versión preliminar, como se describe en la sección HTTP anterior.

Consulta la guía de inicio rápido correspondiente para familiarizarte con Apps Script y configurar un proyecto básico. Luego, sigue estas instrucciones para comenzar a llamar a las APIs en versión preliminar:

Cómo cambiar el proyecto de Cloud que usa la secuencia de comandos

En Configuración del proyecto, haz clic en Cambiar proyecto y, luego, ingresa el ID del proyecto de Cloud en el que te inscribiste en el Programa de versión preliminar para desarrolladores (de forma predeterminada, las secuencias de comandos de Apps Script usan un proyecto genérico). Solo los proyectos inscritos pueden llamar a los métodos de vista previa.

Configura solicitudes HTTP

A continuación, configura la solicitud HTTP del método al que deseas llamar en Editor. Por ejemplo, en la guía de inicio rápido, la lista de cursos con el servicio de Classroom se ve de la siguiente manera:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

La operación equivalente con HTTP directamente es la siguiente:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

Cuando se usan servicios avanzados, se infieren los permisos de OAuth necesarios, pero para hacer llamadas HTTP directas a las APIs de Google en Apps Script, debes agregar manualmente los permisos adecuados.

En Project Settings, habilita Show "appsscript.json" manifest file in editor. De vuelta en Editor, agrega oauthScopes al archivo appscript.json para los permisos que necesites. Los permisos para un método determinado se indican en la página de referencia. Por ejemplo, consulta la página del método de lista courses.courseWork.rubrics.

El archivo appscript.json actualizado podría verse de la siguiente manera:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

Proporciona una etiqueta y una versión de vista previa

De vuelta en tu secuencia de comandos, asegúrate de haber agregado la etiqueta y la versión preliminar adecuadas, como se describe en la sección HTTP anterior. La llamada de LIST de ejemplo al servicio de Rúbricas se vería de la siguiente manera:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}