Auf Vorschau-APIs zugreifen

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

Im Vergleich zur stabilen Version 1 der API sind bei der Verwendung von Vorabversionen drei Aspekte zu beachten:

1. Das aufrufende Google Cloud-Projekt muss für das Google Workspace-Entwickler-Vorabprogramm registriert und von Google auf der Zulassungsliste stehen.
2. API-Funktionen in Early-Access- oder Vorabversionen sind nicht in den Standardclientbibliotheken verfügbar und sind möglicherweise standardmäßig nicht über HTTP zugänglich.
3. Es kann jederzeit mehrere API-Status oder ‑Versionen in der Vorabversion geben.

Vorabversionsfunktionen in Clientbibliotheken aktivieren

Eine gängige Option für die Verwendung der Classroom API ist eine Clientbibliothek. Es gibt drei Arten von Clientbibliotheken:

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

Wir empfehlen, die API mit dynamisch generierten oder von Google bereitgestellten statischen Bibliotheken zu verwenden. Wenn Sie eine eigene Bibliothek erstellen möchten, lesen Sie den Hilfeartikel Clientbibliotheken erstellen. Das Erstellen einer eigenen Bibliothek fällt nicht in den Rahmen dieses Leitfadens. Im Abschnitt Dynamische Bibliotheken erfährst du jedoch mehr über Vorschaulabels und ihre Rolle in Discovery.

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. Sie wird verwendet, um Clientbibliotheken, IDE-Plug-ins und andere Tools zu erstellen, die mit Google APIs interagieren. Ein Dienst kann mehrere Discovery-Dokumente haben.

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

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

Der wichtige Unterschied bei der Arbeit mit Vorabversionen von APIs besteht darin, die richtige label anzugeben. Bei öffentlichen Vorabversionen von Classroom lautet dieses Label DEVELOPER_PREVIEW.

Wenn Sie die Python-Bibliothek generieren und den Classroom-Dienst mit Vorabmethoden instanziieren möchten, können Sie die Discovery-URL mit dem entsprechenden Dienst, den Anmeldedaten und dem 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)'

Weitere Informationen zu den einzelnen Programmiersprachen finden Sie in der Dokumentation der jeweiligen Google API-Clientbibliothek.

Statische Bibliotheken

Clientbibliotheken in Sprachen wie Java, Node.js, PHP, C# und Go müssen aus der Quelle erstellt werden. Diese Bibliotheken werden Ihnen zur Verfügung gestellt und die Vorschaufunktionen sind bereits integriert.

Für öffentliche Vorabversionen finden Sie die Classroom-Clientbibliotheken zusammen mit den anderen Clientbibliotheken des Workspace-Entwickler-Vorabversion-Programms. Wenn Sie statische Bibliotheken für private Vorschauen generieren lassen möchten, wenden Sie sich an Ihren Google-Ansprechpartner.

Möglicherweise müssen Sie Ihre typische Abhängigkeitskonfiguration ändern, um diese lokalen Bibliotheken zu verwenden, anstatt die Standardclientbibliotheken zu importieren, die keine Vorabversionsfunktionen haben.

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

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

Erfordere dann in deiner Anwendung zusätzlich zu den regulären Abhängigkeiten das classroom-with-preview-features-Modul und instanziere den classroom-Dienst 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,
});

...

Preview-API-Version angeben

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

Die verschiedenen verfügbaren Versionen und die zugehörigen 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.

Geben Sie dazu in Anfragen das Feld PreviewVersion an. Wenn Sie beispielsweise eine Benotungsskala mit der Rubrics CRUD Preview API erstellen möchten, setzen Sie in der CREATE-Anfrage previewVersion 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 nur vorübergehend verfügbar, während Funktionen auf allgemeine Verfügbarkeit in der v1 API überprüft werden. Das Verhalten der Vorabversion kann sich nach Ablauf des Einstellungszeitraums ändern. Weitere Informationen finden Sie in der Roadmap für die Classroom API.

Ressourcen, die mit einem Vorschaumethodaufruf verknüpft sind, enthalten auch die previewVersion, die im Aufruf als schreibgeschütztes Feld verwendet wird. So können Sie nachvollziehen, welche Version Sie verwenden. Die Antwort vom vorherigen CREATE-Aufruf 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 Vorabversion entspricht der Version, mit der die Ressource abgerufen wurde, nicht unbedingt der Version, die beim Erstellen der Ressource angegeben wurde. Wenn Sie in Zukunft einen GET-, LIST- oder PATCH-Aufruf mit einer neuen Version ausführen, wird die neue Version zurückgegeben.

HTTP-Anfragen

Die Classroom API kann auch direkt über HTTP verwendet werden.

Wenn Sie HTTP-Anfragen ohne Clientbibliothek senden, müssen Sie trotzdem die Vorabversionsfunktionen aktivieren und eine Vorabversion angeben. Dazu wird ein label mit einem X-Goog-Visibilities-Header und der oben genannten Vorabversion entweder als Abfrageparameter oder als POST-Textfeld festgelegt (siehe die entsprechende API-Referenzdokumentation). Für öffentliche Vorschauen lautet das Label DEVELOPER_PREVIEW.

Mit der folgenden Curl-Anfrage wird beispielsweise ein LIST-Aufruf an den Rubrikendienst mit dem entsprechenden Sichtbarkeitslabel und der Vorabversion gesendet:

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

Sie können die Vorabversion auch im Anfragetext angeben, z. B. bei einer POST-Anfrage:

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

Die API für jede HTTP-Anfrage wird in der REST-Dokumentation beschrieben.

Google Apps Script

Sie können Vorabversionen von APIs über Google Apps Script aufrufen. Es gibt jedoch einige Unterschiede zur üblichen Verwendung von Apps Script.

1. Sie müssen Ihr Script so konfigurieren, dass das Google Cloud-Projekt verwendet wird, das Sie für das Developer Preview-Programm registriert haben.
2. Erweiterte Dienste unterstützen keine Vorschaumethoden. Sie müssen Anfragen also direkt über HTTP senden.
3. Sie müssen ein Label und eine Vorschauversion angeben, wie im vorherigen HTTP-Abschnitt beschrieben.

In der entsprechenden Kurzanleitung erfahren Sie mehr über Apps Script und wie Sie ein einfaches Projekt einrichten. Folgen Sie dann dieser Anleitung, um mit dem Aufrufen von Vorschau-APIs zu beginnen:

Vom Script verwendetes Cloud-Projekt ändern

Klicken Sie unter Projekteinstellungen auf Projekt ändern und geben Sie die Cloud-Projekt-ID des Projekts ein, das Sie für das Vorabprogramm für Entwickler registriert haben. Standardmäßig wird für Apps Script-Scripts ein generisches Projekt verwendet. Nur registrierte Projekte können Vorschaumethoden aufrufen.

HTTP-Anfragen konfigurieren

Konfigurieren Sie als Nächstes die HTTP-Anfrage der Methode, die Sie im Editor zurückrufen möchten. In der Kurzanleitung sieht das Eintragen von Kursen mit dem Classroom-Dienst beispielsweise so aus:

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

Der entsprechende Vorgang mit direktem HTTP-Aufruf sieht so aus:

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

Bei der Verwendung erweiterter Dienste werden die erforderlichen OAuth-Bereiche abgeleitet. Wenn Sie jedoch in Apps Script direkte HTTP-Aufrufe an Google APIs ausführen möchten, müssen Sie die entsprechenden Bereiche manuell hinzufügen.

Aktivieren Sie in den Projekteinstellungen die Option Manifestdatei „appsscript.json“ im Editor anzeigen. Fügen Sie im Editor der Datei appscript.json für die gewünschten Bereiche oauthScopes hinzu. Die Zugriffsbereiche für eine bestimmte Methode sind auf der Referenzseite aufgeführt. Weitere Informationen finden Sie beispielsweise auf der Seite Methode „courses.courseWork.rubrics list“.

Die aktualisierte appscript.json-Datei könnte so aussehen:

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

Label und Vorschauversion angeben

Prüfen Sie in Ihrem Script, ob Sie das richtige Label und die richtige Vorschauversion hinzugefügt haben, wie im vorherigen HTTP-Abschnitt beschrieben. Ein Beispiel für einen LIST-Aufruf an den Rubrikendienst:

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