Auf Vorschau-APIs zugreifen

Auf dieser Seite wird beschrieben, wie Sie auf die Vorschaufunktionen der Classroom API zugreifen und Vorschauversionen festlegen können.

Die beiden Überlegungen bei der Verwendung von Vorschaufunktionen im Vergleich zur stabilen v1 API sind:

1. API-Funktionen in Early Access- oder Vorschauprogrammen werden in den Standard-Clientbibliotheken nicht zur Verfügung gestellt und sind möglicherweise nicht standardmäßig über HTTP zugänglich.
2. In der Vorabversion können jederzeit mehrere API-Status oder Versionen vorhanden sein.

Vorschaufunktionen in Clientbibliotheken aktivieren

Häufig wird die Classroom API mit einer Clientbibliothek genutzt. Es gibt drei Arten von Clientbibliotheken:

1. Dynamisch generierte Clientbibliotheken
2. Von Google bereitgestellte statische Clientbibliotheken
3. Ihre eigene benutzerdefinierte Clientbibliothek

Wir empfehlen, für die API dynamisch generierte oder von Google bereitgestellte statische Bibliotheken zu verwenden. Weitere Informationen zum Erstellen einer eigenen Bibliothek finden Sie unter Clientbibliotheken erstellen. Das Erstellen einer eigenen Bibliothek wird in diesem Leitfaden nicht behandelt. Sie sollten jedoch den Abschnitt Dynamische Bibliotheken lesen, um mehr über Vorschaulabels und ihre Rolle in der Erkennung zu erfahren.

Dynamische Bibliotheken

Bibliotheken in Sprachen wie Python generieren die Clientbibliothek zur Laufzeit mithilfe eines Discovery-Dokuments aus dem Discovery-Dienst.

Ein Discovery-Dokument ist eine maschinenlesbare Spezifikation zum Beschreiben und Nutzen von REST APIs. Es wird zum Erstellen von Clientbibliotheken, IDE-Plug-ins und anderen Tools verwendet, die mit Google APIs interagieren. Ein Dienst kann mehrere Discovery-Dokumente bereitstellen.

Discovery-Dokumente für den Classroom API-Dienst (classroom.googleapis.com) finden Sie unter folgendem Endpunkt:

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

Der wichtige Unterschied bei der Arbeit mit Vorschau-APIs besteht darin, den entsprechenden label anzugeben. Bei öffentlichen Vorschauen in Classroom lautet dieses Label DEVELOPER_PREVIEW.

Wenn Sie die Python-Bibliothek generieren und den Classroom-Dienst mit Vorschaumethoden instanziieren möchten, können Sie die Discovery-URL mit dem entsprechenden Dienst, den entsprechenden Anmeldedaten und dem entsprechenden Label angeben:

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

Details zu den einzelnen Sprachen finden Sie in der Dokumentation zur Google API-Clientbibliothek.

Statische Bibliotheken

Clientbibliotheken in Sprachen wie Java, Node.js, PHP, C# und Go müssen aus dem Quellcode erstellt werden. Diese Bibliotheken werden für Sie bereitgestellt und die Vorschaufunktionen sind bereits integriert.

Die Classroom-Clientbibliotheken für öffentliche Vorschauen sind zusammen mit den anderen Clientbibliotheken für das Workspace-Entwicklervorschauprogramm verfügbar. Wenden Sie sich für private Vorschauen an Ihren Google-Ansprechpartner, wenn Sie statische Bibliotheken generieren möchten.

Möglicherweise müssen Sie Ihre typische Abhängigkeitenkonfiguration ändern, um diese lokalen Bibliotheken zu verwenden, anstatt die Standard-Clientbibliotheken zu importieren, die keine Vorschaufunktionen haben.

Wenn Sie beispielsweise die Go-Clientbibliothek verwenden möchten, müssen Sie die Anweisung replace in der Datei go.mod verwenden, um ein Modul aus einem lokalen Verzeichnis anzufordern:

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

Wenn Sie Node.js und npm verwenden, fügen Sie den Download der Node.js-Clientbibliothek (googleapis-classroom-1.0.4.tgz) als lokale Abhängigkeit in package.json hinzu:

{
  "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"
  }
}

Fordern Sie dann in Ihrer Anwendung neben den regulären Abhängigkeiten das Modul classroom-with-preview-features an und instanziieren Sie den Dienst classroom aus diesem Modul:

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

...

Vorschau-API-Version angeben

Unabhängig davon, ob Sie eine statische oder dynamische Bibliothek verwenden, müssen Sie die Vorschauversion angeben, wenn Sie API-Aufrufe für Methoden mit Vorschaufunktionen ausführen.

Die verschiedenen verfügbaren Versionen und die darin enthaltenen Funktionen sind in der Classroom API Roadmap dokumentiert. In der Referenzdokumentation für Methoden und Felder wird auch beschrieben, in welchen Versionen die Methode oder das Feld verfügbar ist.

Die Version wird über das Feld PreviewVersion in Anfragen angegeben. Wenn Sie beispielsweise ein Bewertungsschema mit der Rubrics CRUD Preview API erstellen möchten, setzen Sie previewVersion in der CREATE-Anfrage auf V1_20231110_PREVIEW:

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

Hinweis: Vorabversionen sind temporär, während Funktionen in der v1 API auf die allgemeine Verfügbarkeit geprüft werden. Das Verhalten der Vorschauversion kann sich nach dem Einstellungszeitraum ändern. Weitere Informationen finden Sie unter Roadmap für die Classroom API.

Ressourcen, die mit einem Vorschaumethodenaufruf verknüpft sind, enthalten auch das im Aufruf verwendete previewVersion als schreibgeschütztes Feld, damit du besser nachvollziehen kannst, welche Version du verwendest. Die Antwort des vorherigen CREATE-Aufrufs enthält beispielsweise den Wert 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",
  ...
}

Hinweis: Die mit einer Ressource verknüpfte Vorschauversion entspricht der Version, die zum Abrufen der Ressource verwendet wird, und nicht unbedingt dem Aufruf zum Erstellen der Ressource. Wenn Sie einen zukünftigen GET-, LIST- oder PATCH-Aufruf mit einer neuen Version ausführen, wird die neue Version zurückgegeben.

HTTP-Anfragen

Es ist auch möglich, die Classroom API direkt über HTTP zu nutzen.

Wenn Sie HTTP-Anfragen ohne Clientbibliothek senden, müssen Sie trotzdem Vorschaufunktionen aktivieren und eine Vorschauversion angeben. Dazu wird ein label mit einem X-Goog-Visibilities-Header und die zuvor erwähnte Vorschauversion entweder als Abfrageparameter oder als POST-Textfeld festgelegt. Bei öffentlichen Vorschauen lautet das Label DEVELOPER_PREVIEW.

Mit der folgenden curl-Anfrage wird beispielsweise ein LIST-Aufruf mit dem entsprechenden Sichtbarkeitslabel und der entsprechenden Vorschauversion an den Bewertungsschema-Dienst gesendet:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_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

Sie können die Vorschauversion auch im Anfragetext angeben, z. B. wenn Sie eine POST-Anfrage stellen:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

Die API für die einzelnen HTTP-Anfragen wird in der REST-Dokumentation beschrieben.