En esta página, se describe cómo puedes acceder a las funciones de vista previa de la API de Classroom y especificar versiones preliminares.
Las tres consideraciones que debes tener en cuenta al usar las funciones de vista previa en comparación con la versión estable v1 API:
- El proyecto de Google Cloud que realiza la llamada debe estar inscrito en Google Workspace. Programa de versión preliminar para desarrolladores y las listas de entidades permitidas de Google.
- Las funciones de API en los programas de vista previa o de acceso anticipado no se exponen en la a las bibliotecas cliente estándar y podría no ser accesible de forma predeterminada a través de HTTP.
- En un momento dado, puede haber varios estados o versiones de API en vista previa.
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. Hay hay 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 y se recomienda usar la API. Consulta Cómo compilar bibliotecas cliente si lo necesitas. crear tu propia biblioteca. La creación de tu propia biblioteca está fuera del alcance de este pero deberías consultar la sección Bibliotecas dinámicas para obtener más información Etiquetas de vista previa y su rol en el descubrimiento.
Bibliotecas dinámicas
Las bibliotecas en lenguajes como Python generan la biblioteca cliente en el entorno de ejecución con un Documento de descubrimiento del servicio de descubrimiento.
Un Documento de descubrimiento es una especificación procesable para describir y las APIs de REST que consumen. Se usa para compilar bibliotecas cliente, complementos IDE y y otras herramientas que interactúan con las APIs de Google. Un servicio puede proporcionar varios de descubrimiento.
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 de vista previa es especificar la
la label apropiada. Para las vistas previas públicas de Classroom, la etiqueta está
DEVELOPER_PREVIEW
Para generar la biblioteca de Python y crear una instancia del servicio Classroom con de vista previa, puedes especificar la URL de descubrimiento con el servicio adecuado credenciales y etiqueta:
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 una. idioma.
Bibliotecas estáticas
Se deben compilar bibliotecas cliente en lenguajes como Java, Node.js, PHP, C# y Go. desde la fuente. Estas bibliotecas se proporcionan para ti y tienen las funciones de versión preliminar ya incorporado.
Para las vistas previas públicas, las bibliotecas cliente de Classroom se pueden encontrar con el otro 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 tu configuración de dependencias típica para usar estas las bibliotecas locales en lugar de importar las bibliotecas cliente estándar, que no contar con las funciones de vista previa.
Por ejemplo, para usar la biblioteca cliente de Go, debes usar replace
directiva en tu archivo go.mod para solicitar 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 el cliente de Node.js
descarga de la biblioteca (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 regulares y crear una instancia del servicio classroom.
de 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,
});
...
Especifica una versión de vista previa de la API
Independientemente de si usas una biblioteca estática o dinámica, debes especificar el Preview cuando se realizan llamadas a la API a métodos con capacidades de vista previa.
Se documentan las diferentes versiones disponibles y las funciones que incluyen en la Hoja de ruta de la API de Classroom. La documentación de referencia sobre métodos y campos también describen en qué versiones está disponible el método o el campo.
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 a 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 la
previewVersion se usa en la llamada como campo de solo lectura para ayudarte a comprender
qué versión estás usando. Por ejemplo, la respuesta del comando CREATE anterior
llamada 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 consumir la API de Classroom directamente con HTTP.
Si realizas solicitudes HTTP sin una biblioteca cliente, aun así debes habilitar
de vista previa especifican una versión preliminar. Para ello, se debe configurar una 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 (consulta la API individual
documentación de referencia). Para las vistas previas 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 de vista previa en el cuerpo de la solicitud, por ejemplo, cuando realizar 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.
- Debes configurar tu secuencia de comandos para que use cualquier proyecto de Google Cloud estar inscrita en el Programa de Versión preliminar para desarrolladores
- Los servicios avanzados no admiten métodos de vista previa, por lo que deberás realizar directamente con HTTP.
- Debes proporcionar una etiqueta y una versión de vista previa, como se describe en el documento anterior. Sección HTTP.
Consulta la guía de inicio rápido correspondiente para familiarizarte con Apps Script y obtener la configuración básica de un proyecto. Luego, sigue estos Instrucciones para comenzar a llamar a las APIs de Preview:
Cambiar el proyecto de Cloud que utiliza la secuencia de comandos
En Project Settings, haz clic en Change project y, luego, ingresa el ID del proyecto de la nube de cualquier proyecto que hayas inscrito en el programa de Developer de versión preliminar (de forma predeterminada, Las secuencias de comandos de Apps Script usan un proyecto genérico). Solo inscritos los proyectos pueden llamar a métodos de vista previa.
Configura solicitudes HTTP
A continuación, configura la solicitud HTTP del método al que quieras llamar Editor. Por ejemplo, en la guía de inicio rápido, puedes enumerar los cursos con el servicio 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 los servicios avanzados, se infieren los permisos de OAuth necesarios, pero hacer llamadas HTTP directas a las APIs de Google en Apps Script, se debe agregar manualmente los alcances adecuados.
En Project Settings, habilita Show "appsscript.json" archivo de manifiesto en
Google Cloud. Vuelve al Editor y agrega oauthScopes al archivo appscript.json de
los permisos que necesites. Los alcances de un método determinado se enumeran en la
página de referencia. Por ejemplo, consulta el 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
Vuelve a la secuencia de comandos y asegúrate de haber agregado la etiqueta y la vista previa correctas. versión, como se describe en la sección HTTP anterior. La llamada LIST de ejemplo a el servicio de rúbricas se vería así:
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);
}