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 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 version bêta 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 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 en preview.

Activer les fonctionnalités d'aperçu 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 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 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 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

Pour utiliser les API en preview, il est important de spécifier le label approprié. Pour les versions Preview publiques de Classroom, le 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 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 la bibliothèque cliente de l'API Google concernée.

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 pour vous et intègrent déjà les fonctionnalités d'aperçu.

Pour les aperçus publics, les bibliothèques clientes Classroom sont disponibles avec les autres bibliothèques clientes du programme Workspace Developer Preview. Pour les aperçus privés, contactez votre contact 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 au lieu 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 habituelles, 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 bêta lorsque vous effectuez des appels d'API à des méthodes avec des fonctionnalités en version bêta.

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 des méthodes et des champs indique également dans quelle(s) version(s) 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 un barème avec l'API d'aperçu CRUD des barèmes, 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 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 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 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 version bêta et spécifier une version bêta. Pour ce faire, définissez un label avec un en-tête X-Goog-Visibilities et la version Preview susmentionnée 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 versions Preview 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 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 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 d'aperçu depuis 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 dans lequel vous vous êtes inscrit au programme Preview développeur.
Les services avancés ne sont pas compatibles avec les méthodes d'aperçu. Vous devrez donc envoyer 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 les API d'aperçu :

Modifier le projet Cloud utilisé par le script

Dans Paramètres du projet, cliquez sur Modifier le projet et saisissez l'ID du projet Cloud dans lequel vous vous êtes inscrit au Programme d'aperçu pour les développeurs (par défaut, les scripts Apps Script utilisent un projet générique). Seuls les projets inscrits peuvent appeler des méthodes d'aperçu.

Configurer les 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 ressemble à ceci :

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 des services avancés, les habilitations OAuth requises sont déduites. Toutefois, pour effectuer des appels HTTP directs aux API Google dans Apps Script, vous devez ajouter manuellement les habilitations appropriées.

Dans Paramètres du projet, activez Afficher le fichier manifeste "appsscript.json" dans l'éditeur. De retour dans Editor, ajoutez oauthScopes au fichier appscript.json pour les portées dont vous avez besoin. Les niveaux d'accès d'une méthode donnée sont listés sur 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 une version de libellé et d'aperçu

De retour dans votre script, assurez-vous d'avoir ajouté le libellé et la version d'aperçu appropriés, comme décrit dans la section HTTP précédente. Voici à quoi ressemblerait l'appel LIST au service Rubrics :

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