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 d'aperçu.

Les trois points à prendre en compte lorsque vous utilisez des fonctionnalités en version preview API v1 sont:

Le projet Google Cloud appelant doit être enregistré dans Google Workspace Programme Preview développeur et à la liste d'autorisation de Google.
Les fonctionnalités d'API des programmes Preview ou en accès anticipé ne sont pas exposées dans 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 dans un aperçu.

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

Une option courante pour utiliser l'API Classroom consiste à utiliser une bibliothèque cliente. Il y 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 de façon dynamique ou fournies par Google la méthode recommandée pour utiliser l'API. Si nécessaire, consultez la page Créer des bibliothèques clientes. créer votre propre bibliothèque. La création de votre propre bibliothèque n'entre pas dans le cadre de cette , mais consultez la section sur les bibliothèques dynamiques pour les libellés et leur rôle dans Discovery.

Bibliothèques dynamiques

Dans des langages tels que Python, les bibliothèques génèrent la bibliothèque cliente au moment de l'exécution en utilisant un document de découverte issu du service de découverte ;

Un document de découverte est une spécification lisible par un ordinateur pour décrire et à l'aide d'API REST. Il permet de créer des bibliothèques clientes, des plug-ins IDE et et d'autres outils qui interagissent avec les API Google. Un service peut fournir plusieurs des documents de découverte.

Documents de découverte pour le service de l'API Classroom (classroom.googleapis.com) se trouve au point de terminaison suivant:

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

Lors de l'utilisation des API de prévisualisation, il est important de spécifier les label appropriées. 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 d'aperçu, vous pouvez spécifier l'URL de découverte avec le service approprié, les identifiants et l'étiquette:

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)'

Consultez la documentation de la bibliothèque cliente des API Google pour en savoir plus sur chaque langue.

Bibliothèques statiques

Vous devez créer des bibliothèques clientes dans des langages tels que Java, Node.js, PHP, C# et Go. de la source. Ces bibliothèques sont fournies pour vous et disposent des fonctionnalités en version preview déjà incorporés.

Pour les versions Preview publiques, les bibliothèques clientes Classroom se trouvent au même endroit que les autres Bibliothèques clientes du programme Preview développeur Workspace. Pour les aperçus privés, adressez-vous à votre contact Google si vous avez besoin de bibliothèques statiques générées.

Vous devrez peut-être modifier la configuration type de vos dépendances bibliothèques locales plutôt que d'importer les bibliothèques clientes standards, qui ne les fonctionnalités en preview.

Par exemple, pour utiliser la bibliothèque cliente Go, vous devez utiliser replace dans votre fichier go.mod pour exiger un module dans 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 client Node.js téléchargement de la bibliothèque (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, et instanciez le service classroom 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 le paramètre version preview lorsque vous effectuez des appels d'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 documentées dans la feuille de route de l'API Classroom. La documentation de référence sur les méthodes et les champs décrivent également la ou les versions dans lesquelles la méthode ou le champ sont disponibles.

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 Grilles d'évaluation, vous devez définir previewVersion à 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 la requête CREATE précédente 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 preview spécifient 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 comme soit un paramètre de requête, soit un champ de corps POST (consultez l'API individuelle appropriée documentation de référence). Pour les aperçus publics, le libellé est DEVELOPER_PREVIEW.

Par exemple, la requête curl suivante effectue un appel LIST vers le service Grilles d'évaluation 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 d'aperçu dans le corps de la requête, par exemple lorsque en effectuant 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

Il est possible d'appeler des API de prévisualisation à 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 utiliser le projet Google Cloud avec lequel vous si vous êtes inscrit au programme Preview développeur.
Les services avancés n'étant pas compatibles avec les méthodes d'aperçu, vous devez directement avec HTTP.
Vous devez fournir un libellé et une version d'aperçu, comme décrit dans la section Section HTTP.

Consultez le guide de démarrage rapide correspondant pour vous familiariser avec et configurer un projet de base. Suivez ensuite ces Instructions pour appeler les API Preview:

Modifier le projet Cloud utilisé par le script

Dans Paramètres du projet, cliquez sur Modifier le projet et saisissez le de n'importe quel projet que vous avez inscrit au programme Developer Programme Preview (par défaut, Les scripts Apps Script utilisent un projet générique). Uniquement inscrit les projets peuvent appeler des méthodes d'aperçu.

Configurer des requêtes HTTP

Configurez ensuite la requête HTTP de la méthode que vous souhaitez rappeler dans Éditeur : Par exemple, dans le guide de démarrage rapide, vous pouvez lister les cours avec 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 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 les services avancés, les habilitations OAuth requises sont déduites, mais pour passer des appels HTTP directs aux API Google dans Apps Script, vous devez ajouter manuellement les niveaux d'accès appropriés.

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

Revenez dans votre script et vérifiez que vous avez ajouté le libellé et l'aperçu appropriés. comme décrit dans la section HTTP précédente. L'exemple d'appel LIST pour le service Grilles d'évaluation ressemblerait à ceci:

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