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.

Cette page a été traduite par l'API Cloud Translation.

Accéder aux API de la version preview

Cette page explique comment accéder aux fonctionnalités d'aperçu de l'API Classroom et spécifier des versions d'aperçu.

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

Le projet Google Cloud appelant doit être inscrit au programme Preview développeur de Google Workspace et autorisé par Google.
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, plusieurs états (ou versions) d'API peuvent être disponibles en version Preview.

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

Une option courante pour utiliser 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

La méthode recommandée pour utiliser l'API consiste à utiliser des bibliothèques statiques générées dynamiquement ou fournies par Google. Consultez 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 champ d'application de ce guide. Toutefois, nous vous recommandons de 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 même service peut fournir plusieurs documents de découverte.

Les documents de découverte du service de l'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

Lors de l'utilisation des API en preview, il est important de spécifier le label approprié. Pour les versions Preview 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 de prévisualisation, 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 de la bibliothèque cliente de chaque API Google.

Bibliothèques statiques

Les bibliothèques clientes dans des langages tels que Java, Node.js, PHP, C# et Go doivent être compilées à partir de la source. Ces bibliothèques sont fournies et les fonctionnalités de prévisualisation sont déjà intégrées.

Pour les versions Preview publiques, les bibliothèques clientes Classroom se trouvent 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 de vos dépendances habituelles pour utiliser ces bibliothèques locales plutôt que d'importer les bibliothèques clientes standards, qui ne disposent pas des fonctionnalités d'aperçu.

Par exemple, pour utiliser la bibliothèque cliente Go, vous devez utiliser la directive replace dans 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

Par 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 régulières et 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 d'aperçu

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

Les différentes versions disponibles et les fonctionnalités qu'elles incluent sont documentées dans le plan de route de l'API Classroom. La documentation de référence des méthodes et des champs décrit également 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 Preview CRUD des grilles d'évaluation, 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, pour vous aider à identifier 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

Vous pouvez également utiliser 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 d'aperçu pour spécifier une version d'aperçu. Pour ce faire, définissez un label avec un en-tête X-Goog-Visibilities et la version preview mentionnée ci-dessus en tant que paramètre de requête ou champ de corps POST (voir la documentation de référence de l'API appropriée). Pour les versions Preview publiques, le libellé est DEVELOPER_PREVIEW.

Par exemple, la requête curl suivante appelle LIST au service Rubrics avec le libellé de visibilité et la version 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 d'aperçu dans le corps de la requête, par exemple lors de l'exécution d'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

Vous pouvez appeler des API Preview à 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 qu'il utilise le projet Google Cloud que vous avez inscrit au programme Preview développeur.
Les services avancés ne sont pas compatibles avec les méthodes d'aperçu. Vous devez donc effectuer des requêtes directement avec HTTP.
Vous devez fournir un libellé et une version d'aperçu, 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 Preview:

Modifier le projet Cloud utilisé par le script

Dans Project Settings (Paramètres du projet), cliquez sur Change project (Modifier le projet) et saisissez l'ID du projet Cloud que vous avez inscrit au Developer Preview Program (Programme Preview pour les développeurs) (par défaut, les scripts Apps Script utilisent un projet générique). Seuls les projets inscrits peuvent appeler les méthodes d'aperçu.

Configurer des requêtes HTTP

Ensuite, configurez la requête HTTP de la méthode que vous souhaitez rappeler dans l'é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 les services avancés, les champs d'application OAuth requis sont déduits, mais pour effectuer des appels HTTP directs aux API Google dans Apps Script, vous devez ajouter manuellement les champs d'application appropriés.

Dans Paramètres du projet, activez l'option Afficher le fichier manifeste "appsscript.json" dans l'éditeur. Revenez dans l'éditeur et ajoutez oauthScopes au fichier appscript.json pour les niveaux d'accès dont vous avez besoin. Les champs d'application d'une méthode donnée sont répertoriés sur la page de référence. Par exemple, consultez la page de 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

Dans votre script, assurez-vous d'avoir ajouté l'étiquette et la version d'aperçu appropriées, 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);
}