Cette page explique comment accéder aux fonctionnalités en preview de l'API Classroom et spécifier les versions d'aperçu.
Les trois points à prendre en compte lorsque vous utilisez des fonctionnalités en version preview API v1 sont:
- Le projet Google Cloud appelant doit être enregistré dans Google Workspace Programme Preview développeur et à la liste d'autorisation de Google.
- Les fonctionnalités d'API des programmes Preview ou en accès anticipé ne sont pas exposées dans bibliothèques clientes standards et peuvent ne pas être accessibles par défaut via HTTP.
- À tout moment, il peut y avoir plusieurs états, ou versions, d'API dans un aperçu.
Activer les fonctionnalités en preview dans les bibliothèques clientes
Une option courante pour utiliser l'API Classroom consiste à utiliser une bibliothèque cliente. Il y il existe trois types de bibliothèques clientes:
- Bibliothèques clientes générées dynamiquement
- Bibliothèques clientes statiques fournies par Google
- Votre propre bibliothèque cliente personnalisée
L'utilisation de bibliothèques statiques générées de façon dynamique ou fournies par Google la méthode recommandée pour utiliser l'API. Si nécessaire, consultez la page Créer des bibliothèques clientes. créer votre propre bibliothèque. La création de votre propre bibliothèque n'entre pas dans le cadre de cette , mais consultez la section sur les bibliothèques dynamiques pour les libellés et leur rôle dans Discovery.
Bibliothèques dynamiques
Dans des langages tels que Python, les bibliothèques génèrent la bibliothèque cliente au moment de l'exécution en utilisant un document de découverte issu du service de découverte ;
Un document de découverte est une spécification lisible par un ordinateur pour décrire et à l'aide d'API REST. Il permet de créer des bibliothèques clientes, des plug-ins IDE et et d'autres outils qui interagissent avec les API Google. Un service peut fournir plusieurs des documents de découverte.
Documents de découverte pour le service de l'API Classroom (classroom.googleapis.com
)
se trouve au point de terminaison suivant:
https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY
Lors de l'utilisation des API de prévisualisation, il est important de spécifier
les label
appropriées. Pour les aperçus publics Classroom, ce libellé est
DEVELOPER_PREVIEW
Pour générer la bibliothèque Python et instancier le service Classroom avec d'aperçu, vous pouvez spécifier l'URL de découverte avec le service approprié, les identifiants et l'étiquette:
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)'
Consultez la documentation de la bibliothèque cliente des API Google pour en savoir plus sur chaque langue.
Bibliothèques statiques
Vous devez créer des bibliothèques clientes dans des langages tels que Java, Node.js, PHP, C# et Go. de la source. Ces bibliothèques sont fournies pour vous et disposent des fonctionnalités en version preview déjà incorporés.
Pour les versions Preview publiques, les bibliothèques clientes Classroom se trouvent au même endroit que les autres Bibliothèques clientes du programme Preview développeur Workspace. Pour les aperçus privés, adressez-vous à votre contact Google si vous avez besoin de bibliothèques statiques générées.
Vous devrez peut-être modifier la configuration type de vos dépendances bibliothèques locales plutôt que d'importer les bibliothèques clientes standards, qui ne les fonctionnalités en preview.
Par exemple, pour utiliser la bibliothèque cliente Go, vous devez utiliser replace
dans votre fichier go.mod
pour exiger un module dans un répertoire 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
Autre exemple : si vous utilisez Node.js et npm, ajoutez le client Node.js
téléchargement de la bibliothèque (googleapis-classroom-1.0.4.tgz
) en tant que dépendance locale dans
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"
}
}
Ensuite, dans votre application, exigez le module classroom-with-preview-features
.
en plus des dépendances standards, et instanciez le service classroom
de ce module:
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,
});
...
Spécifier une version d'API d'aperçu
Que vous utilisiez une bibliothèque statique ou dynamique, vous devez spécifier le paramètre version preview lorsque vous effectuez des appels d'API vers des méthodes dotées de fonctionnalités d'aperçu.
Les différentes versions disponibles et les fonctionnalités qu'elles incluent sont documentées dans la feuille de route de l'API Classroom. La documentation de référence sur les méthodes et les champs décrivent également la ou les versions dans lesquelles la méthode ou le champ sont disponibles.
La spécification d'une version s'effectue en définissant le champ PreviewVersion dans les requêtes.
Par exemple, pour créer une grille d'évaluation avec l'API d'aperçu CRUD de Grilles d'évaluation, vous devez définir
previewVersion
à V1_20231110_PREVIEW
dans la requête 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()
Les ressources associées à un appel de méthode d'aperçu contiennent également le
previewVersion
utilisé dans l'appel en tant que champ en lecture seule pour vous aider à comprendre
la version que vous utilisez. Par exemple, la réponse de la requête CREATE précédente
contient la valeur 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",
...
}
Requêtes HTTP
Il est également possible d'utiliser l'API Classroom directement avec HTTP.
Si vous effectuez des requêtes HTTP sans bibliothèque cliente, vous devez quand même activer
les fonctionnalités en preview spécifient une version preview. Pour ce faire, définissez un label
avec un en-tête X-Goog-Visibilities
et la version preview mentionnée ci-dessus comme
soit un paramètre de requête, soit un champ de corps POST (consultez l'API individuelle appropriée
documentation de référence). Pour les aperçus publics, le libellé est DEVELOPER_PREVIEW
.
Par exemple, la requête curl suivante effectue un appel LIST vers le service Grilles d'évaluation avec le libellé de visibilité et la version d'aperçu appropriés:
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
Vous pouvez également spécifier la version d'aperçu dans le corps de la requête, par exemple lorsque en effectuant une requête 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
L'API utilisée pour chaque requête HTTP est décrite dans la documentation REST.
Google Apps Script
Il est possible d'appeler des API de prévisualisation à partir de Google Apps Script. Cependant, il existe quelques différences par rapport à l'utilisation habituelle d'Apps Script.
- Vous devez configurer votre script pour utiliser le projet Google Cloud avec lequel vous si vous êtes inscrit au programme Preview développeur.
- Les services avancés n'étant pas compatibles avec les méthodes d'aperçu, vous devez directement avec HTTP.
- Vous devez fournir un libellé et une version d'aperçu, comme décrit dans la section Section HTTP.
Consultez le guide de démarrage rapide correspondant pour vous familiariser avec et configurer un projet de base. Suivez ensuite ces Instructions pour appeler les API Preview:
Modifier le projet Cloud utilisé par le script
Dans Paramètres du projet, cliquez sur Modifier le projet et saisissez le de n'importe quel projet que vous avez inscrit au programme Developer Programme Preview (par défaut, Les scripts Apps Script utilisent un projet générique). Uniquement inscrit les projets peuvent appeler des méthodes d'aperçu.
Configurer des requêtes HTTP
Configurez ensuite la requête HTTP de la méthode que vous souhaitez rappeler dans Éditeur : Par exemple, dans le guide de démarrage rapide, vous pouvez lister les cours avec Classroom se présente comme suit:
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);
}
}
L'opération équivalente en utilisant directement HTTP est la suivante:
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);
}
}
Lorsque vous utilisez les services avancés, les habilitations OAuth requises sont déduites, mais pour passer des appels HTTP directs aux API Google dans Apps Script, vous devez ajouter manuellement les niveaux d'accès appropriés.
Dans Paramètres du projet, activez l'option Afficher "appsscript.json" dans un fichier manifeste
éditeur. De retour dans l'éditeur, ajoutez oauthScopes
au fichier appscript.json
pour
selon les niveaux d'accès dont vous avez besoin. Les champs d'application d'une méthode donnée sont répertoriés dans la section
la page de référence. Par exemple, reportez-vous à la méthode de liste "courses.courseWork.rubrics"
.
Le fichier appscript.json
mis à jour peut se présenter comme suit:
{
"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"
]
}
Fournir un libellé et une version d'aperçu
Revenez dans votre script et vérifiez que vous avez ajouté le libellé et l'aperçu appropriés. comme décrit dans la section HTTP précédente. L'exemple d'appel LIST pour le service Grilles d'évaluation ressemblerait à ceci:
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);
}