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 des versions preview.

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 être 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

La distinction importante pour travailler avec les API Preview consiste à 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 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 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 Preview

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 envoyez des requêtes HTTP sans bibliothèque cliente, vous devez toujours activer les fonctionnalités Preview et spécifier 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 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 Preview dans le corps de la requête, par exemple lorsque vous envoyez 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

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

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 Éditeur, ajoutez oauthScopes au fichier appscript.json pour les portées 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);
}