Cette page explique comment accéder aux fonctionnalités preview de l'API Classroom et comment spécifier les versions preview.
Voici les deux éléments à prendre en compte lorsque vous utilisez des fonctionnalités en preview par rapport à la version stable de l'API v1:
- Les fonctionnalités d'API des programmes en accès anticipé ou en version preview ne sont pas exposées dans les 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 en preview.
Activer les fonctionnalités en preview dans les bibliothèques clientes
Une bibliothèque cliente est l'une des solutions courantes d'utilisation de l'API Classroom. 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
Nous vous recommandons d'utiliser l'API à l'aide de bibliothèques statiques générées dynamiquement ou fournies par Google. Consultez la section Créer des bibliothèques clientes si vous devez créer votre propre bibliothèque. La création de votre propre bibliothèque n'entre pas dans le cadre de ce guide, mais vous devez consulter la section Bibliothèques dynamiques pour en savoir plus sur les libellés d'aperçu et leur rôle dans Discovery.
Bibliothèques dynamiques
Les bibliothèques dans des langages tels que Python génèrent la bibliothèque cliente au moment de l'exécution à l'aide d'un document de découverte du service de découverte.
Un document de découverte est une spécification lisible par un ordinateur qui permet de décrire et de consommer les API REST. Il permet de créer des bibliothèques clientes, des plug-ins IDE et d'autres outils qui interagissent avec les API Google. Un service peut fournir plusieurs documents de découverte.
Les documents de découverte pour le service d'API Classroom (classroom.googleapis.com) sont disponibles sur le point de terminaison suivant:
https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY
La distinction importante lors de l'utilisation des API en version preview est de spécifier le label approprié. 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 des méthodes d'aperçu, vous pouvez spécifier l'URL de découverte avec le service, les identifiants et le libellé appropriés:
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)'
Pour en savoir plus sur chaque langage, consultez la documentation des bibliothèques clientes des API Google individuelles.
Bibliothèques statiques
Les bibliothèques clientes dans des langages tels que Java, Node.js, PHP, C# et Go doivent être créées à partir de la source. Ces bibliothèques sont fournies automatiquement, et les fonctionnalités en preview sont déjà intégrées.
Pour les versions Preview publique, les bibliothèques clientes Classroom sont disponibles avec les autres bibliothèques clientes du programme Preview développeur Workspace. Pour les aperçus privés, contactez votre représentant Google si vous avez besoin de générer des bibliothèques statiques.
Vous devrez peut-être modifier la configuration type de vos dépendances pour utiliser ces bibliothèques locales au lieu d'importer les bibliothèques clientes standards, qui ne disposent pas des fonctionnalités en version preview.
Par exemple, pour utiliser la bibliothèque cliente Go, vous devez utiliser la directive replace de votre fichier go.mod pour exiger un module à partir d'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 téléchargement de la bibliothèque cliente Node.js (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, puis instanciez le service classroom à partir 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 preview de l'API
Que vous utilisiez une bibliothèque statique ou dynamique, vous devez spécifier la version d'aperçu lorsque vous appelez l'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 décrites dans la feuille de route de l'API Classroom. La documentation de référence des méthodes et des champs décrit également la ou les versions dans lesquelles la méthode ou le champ est disponible.
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 Rubrics, vous devez définir previewVersion sur 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 preview contiennent également le previewVersion utilisé dans l'appel en tant que champ en lecture seule, ce qui vous aide à comprendre quelle version vous utilisez. Par exemple, la réponse de l'appel CREATE précédent 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 de consommer l'API Classroom directement avec HTTP.
Si vous effectuez des requêtes HTTP sans bibliothèque cliente, vous devez tout de même activer les fonctionnalités de prévisualisation et spécifier une version preview. Pour ce faire, définissez un label avec un en-tête X-Goog-Visibilities et la version d'aperçu mentionnée ci-dessus en tant que paramètre de requête ou champ de corps POST. Pour les aperçus publics, le libellé est DEVELOPER_PREVIEW.
Par exemple, la requête curl suivante envoie un appel LIST au service Rubrics avec le libellé de visibilité et la version d'aperçu appropriés:
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
Vous pouvez également spécifier la version preview dans le corps de la requête, par exemple lorsque vous effectuez une requête 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
L'API pour chaque requête HTTP est décrite dans la documentation REST.