Les modules complémentaires Google Classroom sont désormais disponibles pour tous les développeurs. Pour en savoir plus, consultez la documentation sur les modules complémentaires.

Google utilise la technologie IA pour traduire le contenu dans votre langue préférée. Les traductions générées par IA peuvent contenir des erreurs.

Accéder aux API de la version preview

Cette page explique comment accéder aux fonctionnalités en preview de l'API Classroom et spécifier les versions en preview.

Voici les trois points à prendre en compte lorsque vous utilisez des fonctionnalités en preview par rapport à l'API v1 stable :

Le projet Google Cloud appelant doit être inscrit au programme Google Workspace Developer Preview et autorisé par Google.
Les fonctionnalités d'API en accès anticipé ou dans des programmes en preview ne sont pas exposées dans les bibliothèques clientes standards et ne sont peut-être pas accessibles par défaut via HTTP.
À tout moment, plusieurs états ou versions d'API peuvent être en preview.

Activer les fonctionnalités en preview dans les bibliothèques clientes

Une option courante pour consommer l'API Classroom consiste à utiliser une bibliothèque cliente. 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 dynamiquement ou fournies par Google est la méthode recommandée pour utiliser l'API. 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 ne fait pas partie de ce guide, mais vous devez consulter la section sur les bibliothèques dynamiques pour en savoir plus sur les libellés en preview et leur rôle dans la découverte.

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. Ce document permet de créer des bibliothèques clientes, des plug-ins IDE et d'autres outils qui interagissent avec les API Google. Un même service peut fournir plusieurs documents de découverte.

Les documents de découverte pour le service de l'API Classroom (classroom.googleapis.com) sont disponibles au point de terminaison suivant :

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

La distinction importante pour utiliser les API en preview consiste à spécifier le label approprié. Pour les previews publiques de Classroom, ce libellé est DEVELOPER_PREVIEW.

Pour générer la bibliothèque Python et instancier le service Classroom avec des méthodes en preview, vous pouvez spécifier l'URL Discovery 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 de chaque bibliothèque cliente des API Google .

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 et incluent déjà les fonctionnalités en preview.

Pour les previews publiques, les bibliothèques clientes Classroom sont disponibles avec les autres bibliothèques clientes du programme Workspace Developer Preview. Pour les previews privées, contactez votre interlocuteur Google si vous avez besoin de générer des bibliothèques statiques.

Vous devrez peut-être modifier votre configuration de dépendances habituelle pour utiliser ces bibliothèques locales au lieu d'importer les bibliothèques clientes standards, qui ne disposent pas des fonctionnalités en preview.

Par exemple, pour utiliser la bibliothèque cliente Go, vous devez utiliser la replace directive dans votre fichier go.mod afin de demander 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, demandez le module classroom-with-preview-features en plus des dépendances habituelles, 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 d'API en preview

Que vous utilisiez une bibliothèque statique ou dynamique, vous devez spécifier la version en preview lorsque vous effectuez des appels d'API à des méthodes avec des fonctionnalités en preview.

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 pour les méthodes et les champs décrit également la ou les versions dans lesquelles la méthode ou le champ est disponible.

Pour spécifier une version, définissez le champ PreviewVersion dans les requêtes. Par exemple, pour créer une grille d'évaluation avec l'API CRUD en preview Rubrics, vous définissez 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 en preview contiennent également le previewVersion utilisé dans l'appel en tant que champ en lecture seule, ce qui vous permet de comprendre la version que 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 toujours activer les fonctionnalités en preview et spécifier une version en preview. Pour ce faire, définissez un label avec un X-Goog-Visibilities en-tête et la version en preview mentionnée précédemment en tant que paramètre de requête ou champ de corps POST (consultez la documentation de référence de l'API individuelle appropriée ). Pour les previews publiques, le libellé est DEVELOPER_PREVIEW.

Par exemple, la requête curl suivante effectue un appel LIST au service Rubrics avec le libellé de visibilité et la version en preview 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 en 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_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 pour chaque requête HTTP est décrite dans la documentation REST.

Google Apps Script

Il est possible d'appeler des API en preview à partir de Google Apps Script. Toutefois, il existe quelques différences par rapport à l'utilisation habituelle d'Apps Script.

Vous devez configurer votre script pour utiliser le projet Google Cloud dans lequel vous vous êtes inscrit au programme Developer Preview.
Les services avancés ne sont pas compatibles avec les méthodes en preview. Vous devez donc effectuer des requêtes directement avec HTTP.
Vous devez fournir un libellé et une version en preview, comme décrit dans la section HTTP précédente.

Consultez le guide de démarrage rapide correspondant pour vous familiariser avec Apps Script et configurer un projet de base. Suivez ensuite ces instructions pour commencer à appeler des API en preview :

Modifier le projet Cloud utilisé par le script

Dans Project Settings (Paramètres du projet), cliquez sur Change project (Modifier le projet), puis saisissez l'ID du projet Cloud dans lequel vous vous êtes inscrit au programme Developer Preview Program (par défaut, les scripts Apps Script utilisent un projet générique). Seuls les projets inscrits peuvent appeler des méthodes en preview.

Configurer les requêtes HTTP

Ensuite, configurez la requête HTTP de la méthode que vous souhaitez rappeler dans Editor (Éditeur). Par exemple, dans le guide de démarrage rapide, la liste des cours avec le service 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 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 des services avancés, les niveaux d'accès OAuth requis sont déduits. Toutefois, pour effectuer des appels HTTP directs aux API Google dans Apps Script, vous devez ajouter manuellement les niveaux d'accès appropriés.

Dans Project Settings (Paramètres du projet), activez Show "appsscript.json" manifest file in editor (Afficher le fichier manifeste "appsscript.json" dans l'éditeur). Dans Editor (Éditeur), ajoutez oauthScopes au fichier appscript.json pour les niveaux d'accès dont vous avez besoin. Les niveaux d'accès d'une méthode donnée sont répertoriés dans la page de référence. Par exemple, consultez la page de la méthode list 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 en preview

Dans votre script, assurez-vous d'avoir ajouté le libellé et la version en preview appropriés, comme décrit dans la section HTTP précédente. L'exemple d'appel LIST au service Rubrics se présente comme suit :

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);
}