Google Classroom-Add-ons sind jetzt allgemein für Entwickler verfügbar. Weitere Informationen finden Sie in der Dokumentation zu Add-ons.

Diese Seite wurde von der Cloud Translation API übersetzt.

Auf Vorschau-APIs zugreifen

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

Im Vergleich zur stabilen v1-API sind bei der Verwendung von Vorschau-Features drei Aspekte zu berücksichtigen:

Das aufrufende Google Cloud-Projekt muss für das Google Workspace-Entwicklervorschaumprogramm registriert und von Google auf die Zulassungsliste gesetzt werden.
API-Funktionen in Early Access- oder Preview-Programmen sind nicht in den Standard-Clientbibliotheken verfügbar und sind möglicherweise nicht standardmäßig über HTTP zugänglich.
Es kann jederzeit mehrere API-Status oder ‑Versionen in der Vorschau geben.

Vorschaufunktionen in Clientbibliotheken aktivieren

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

Dynamisch generierte Clientbibliotheken
Von Google bereitgestellte statische Clientbibliotheken
Ihre eigene benutzerdefinierte Clientbibliothek

Die Verwendung von dynamisch generierten oder von Google bereitgestellten statischen Bibliotheken ist die empfohlene Methode zur Verwendung der API. Wenn Sie eine eigene Bibliothek erstellen müssen, lesen Sie den Abschnitt Clientbibliotheken erstellen. Das Erstellen einer eigenen Bibliothek wird in diesem Leitfaden nicht behandelt. Sie sollten sich jedoch den Abschnitt zu dynamischen Bibliotheken ansehen, um mehr über Vorschaulabels und ihre Rolle bei Discovery 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. 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 am folgenden Endpunkt:

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

Der wichtige Unterschied bei der Arbeit mit Preview-APIs ist die Angabe des entsprechenden label. Für öffentliche Vorschauen von Classroom lautet das Label DEVELOPER_PREVIEW.

Wenn Sie die Python-Bibliothek generieren und den Classroom-Dienst mit Preview-Methoden 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 Sprachen finden Sie in der Dokumentation zu den Clientbibliotheken der jeweiligen Google-API.

Statische Bibliotheken

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

Für öffentliche Vorabversionen finden Sie die Classroom-Clientbibliotheken zusammen mit den anderen Clientbibliotheken des Workspace Developer Preview Program. Wenn Sie statische Bibliotheken für private Vorabversionen benötigen, wenden Sie sich an Ihren Ansprechpartner bei Google.

Möglicherweise müssen Sie Ihre typische Abhängigkeitskonfiguration ändern, um diese lokalen Bibliotheken zu verwenden, anstatt die Standard-Clientbibliotheken zu importieren, die nicht über die Vorschaufunktionen verfügen.

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

Fordern Sie dann in Ihrer Anwendung zusätzlich zu den regulären Abhängigkeiten das classroom-with-preview-features-Modul an und instanziieren Sie 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 Preview-Version angeben, wenn Sie API-Aufrufe an Methoden mit Preview-Funktionen senden.

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 welcher Version bzw. welchen Versionen die Methode oder das Feld verfügbar ist.

Sie geben eine Version an, indem Sie das Feld PreviewVersion in Anfragen festlegen. Wenn Sie beispielsweise eine Rubrik mit der Rubrics CRUD Preview API erstellen möchten, legen Sie previewVersion in der CREATE-Anfrage auf V1_20231110_PREVIEW fest:

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

Ressourcen, die mit einem Vorschaumethodenaufruf verknüpft sind, enthalten auch die in diesem Aufruf verwendete previewVersion als schreibgeschütztes Feld, damit Sie nachvollziehen können, welche Version Sie verwenden. Die Antwort aus dem 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",
  ...
}

HTTP-Anfragen

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

Wenn Sie HTTP-Anfragen ohne Clientbibliothek stellen, müssen Sie trotzdem Vorschaufunktionen aktivieren und eine Vorschauversion angeben. Dazu wird ein label mit einem X-Goog-Visibilities-Header und der oben genannten Vorschauversion als Abfrageparameter oder 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 Rubrics-Dienst mit dem entsprechenden Sichtbarkeitslabel und der entsprechenden Vorschauversion ausgeführt:

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 Vorschauversion 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

Es ist möglich, Preview-APIs über Google Apps Script aufzurufen. Es gibt jedoch einige Unterschiede zur typischen Verwendung von Apps Script.

Sie müssen Ihr Script so konfigurieren, dass es das Google Cloud-Projekt verwendet, für das Sie sich für das Developer Preview Program registriert haben.
Erweiterte Dienste unterstützen keine Vorschau-Methoden. Sie müssen Anfragen also direkt mit HTTP stellen.
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 Preview-APIs zu beginnen:

Das vom Skript verwendete Cloud-Projekt ändern

Klicken Sie in den Projekteinstellungen auf Projekt ändern und geben Sie die Cloud-Projekt-ID des Projekts ein, für das Sie sich für das Developer Preview-Programm registriert haben. Standardmäßig verwenden Apps Script-Skripts ein generisches Projekt. Nur registrierte Projekte können Vorschau-Methoden aufrufen.

HTTP-Anfragen konfigurieren

Konfigurieren Sie als Nächstes die HTTP-Anfrage der Methode, die Sie in Editor aufrufen möchten. In der Kurzanleitung sieht das Auflisten 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 HTTP 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);
  }
}

Wenn Sie erweiterte Dienste verwenden, werden die erforderlichen OAuth-Bereiche abgeleitet. Wenn Sie jedoch direkte HTTP-Aufrufe an Google APIs in Apps Script 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 in Editor der Datei appscript.json oauthScopes für die benötigten Bereiche hinzu. Die Zugriffsbereiche für eine bestimmte Methode sind auf der Referenzseite aufgeführt. Ein Beispiel finden Sie auf der Seite courses.courseWork.rubrics list method.

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

Achten Sie in Ihrem Skript darauf, dass Sie das entsprechende Label und die entsprechende Vorschauversion wie im vorherigen HTTP-Abschnitt beschrieben hinzugefügt haben. Der Beispielaufruf LIST für den Rubrics-Dienst sieht so aus:

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