En esta página, se describe cómo puedes acceder a las funciones de vista previa de la API de Classroom y especificar las versiones preliminares.
Las dos consideraciones que debes tener en cuenta cuando se usan funciones de vista previa en comparación con la API v1 estable son las siguientes:
- Las funciones de API en programas de vista previa o acceso anticipado no están expuestas en las bibliotecas cliente estándar y es posible que no se pueda acceder a ellas de forma predeterminada a través de HTTP.
- En cualquier momento, puede haber varios estados de API o versiones en vista previa.
Habilita funciones de vista previa en bibliotecas cliente
Una opción común para consumir la API de Classroom es con una biblioteca cliente. Existen tres tipos de bibliotecas cliente:
- Bibliotecas cliente generadas de forma dinámica
- Bibliotecas cliente estáticas proporcionadas por Google
- Tu propia biblioteca cliente personalizada
El uso de 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. La creación de tu propia biblioteca está fuera del alcance de esta guía, pero deberías revisar la sección sobre bibliotecas dinámicas para obtener información sobre las etiquetas de vista previa y su función en el descubrimiento.
Bibliotecas dinámicas
Las bibliotecas en lenguajes como Python generan la biblioteca cliente en el entorno de ejecución mediante un documento de descubrimiento del servicio Discovery.
Un documento de descubrimiento es una especificación procesable para describir y consumir las APIs de REST. Se usa para compilar bibliotecas cliente, complementos 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 encuentran 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 de vista previa es especificar el label apropiado. En las vistas previas públicas de Classroom, la etiqueta es DEVELOPER_PREVIEW.
Para generar la biblioteca de Python y crear una instancia del servicio Classroom con métodos de vista previa, puedes especificar la URL de descubrimiento 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 la API de Google individual para obtener detalles sobre cada lenguaje.
Bibliotecas estáticas
Las bibliotecas cliente en lenguajes como Java, Node.js, PHP, C# y Go se deben compilar a partir del código fuente. Estas bibliotecas se proporcionan y ya incorporan las funciones de versión preliminar.
En las versiones preliminares públicas, las bibliotecas cliente de Classroom se pueden encontrar junto con las otras bibliotecas cliente del Programa de versión preliminar para desarrolladores de Workspace. Para obtener vistas previas privadas, comunícate con tu contacto de Google si necesitas generar bibliotecas estáticas.
Es posible que debas modificar la configuración típica de dependencias 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 que requiera 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
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, solicita 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 la API de vista previa
Independientemente de que uses una biblioteca estática o dinámica, debes especificar la versión de vista previa cuando realices llamadas a la API a los métodos con capacidades de vista previa.
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 campos también describe en qué versiones está disponible el método o campo.
Para especificar una versión, debes configurar el campo PreviewVersion en las solicitudes.
Por ejemplo, para crear una rúbrica con la API de la versión preliminar de CRUD de rúbricas, debes establecer previewVersion como V1_20231110_PREVIEW en la solicitud 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()
Los recursos asociados con una llamada de método de vista previa también contienen el previewVersion que se utiliza en la llamada como campo de solo lectura para ayudarte a comprender qué versión utilizas. 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",
...
}
Solicitudes HTTP
También es posible utilizar la API de Classroom directamente con HTTP.
Aunque realices solicitudes HTTP sin una biblioteca cliente, debes habilitar las funciones de vista previa para especificar una versión de vista previa. Para ello, se debe configurar un label con un encabezado X-Goog-Visibilities y la versión de vista previa antes mencionada como un parámetro de consulta o un campo de cuerpo de POST. En las vistas previas públicas, la etiqueta es DEVELOPER_PREVIEW.
Por ejemplo, la siguiente solicitud curl realiza una llamada LIST al servicio 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_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 de vista previa 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_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
--compressed
La API para cada solicitud HTTP se describe en la documentación de REST.