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 deux points à prendre en compte lorsque vous utilisez des fonctionnalités en version preview API v1 sont:

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 préciser 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

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 envoie un appel LIST au 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.