Auf Vorschau-APIs zugreifen

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

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

1. Das aufrufende Google Cloud-Projekt muss im Google Workspace-Konto registriert sein Vorschauprogramm für Entwickler und die Zulassungsliste werden von Google aufgeführt.
2. API-Funktionen in Early Access- oder Vorschauprogrammen werden nicht im Standard-Clientbibliotheken und sind möglicherweise nicht standardmäßig über HTTP zugänglich.
3. Es können jederzeit mehrere API-Status oder Versionen in in der Vorschau ansehen.

Vorschaufunktionen in Clientbibliotheken aktivieren

Die Classroom API kann häufig über eine Clientbibliothek genutzt werden. Es gibt es drei Arten von Clientbibliotheken:

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

Die Verwendung dynamisch generierter oder von Google bereitgestellter statischer Bibliotheken zur Verwendung der API empfohlen. Weitere Informationen finden Sie unter Clientbibliotheken erstellen. um Ihre eigene Bibliothek zu erstellen. Das Erstellen einer eigenen Bibliothek ist nicht möglich. Leitfaden, aber Sie sollten den Abschnitt Dynamische Bibliotheken lesen, um mehr über und deren Rolle in der Erkennung.

Dynamische Bibliotheken

Bibliotheken in Sprachen wie Python generieren die Clientbibliothek zur Laufzeit mithilfe von Ein Discovery-Dokument aus dem Discovery-Dienst.

Ein Discovery-Dokument ist eine maschinenlesbare Spezifikation zum Beschreiben und die REST APIs nutzen. Damit können Clientbibliotheken, IDE-Plug-ins und andere Tools, die mit Google APIs interagieren. Ein Dienst kann mehrere Discovery-Dokumente.

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

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

Der wesentliche Unterschied bei der Arbeit mit Preview-APIs besteht darin, entsprechende label. Bei öffentlichen Classroom-Vorschauen ist dieses Label DEVELOPER_PREVIEW

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

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 Clientbibliotheken finden Sie in der Dokumentation zur Clientbibliothek für die Google API. Sprache.

Statische Bibliotheken

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

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

Möglicherweise müssen Sie die Konfiguration Ihrer typischen Abhängigkeiten ändern, um diese lokale Bibliotheken zu importieren, anstatt die Standard-Client-Bibliotheken zu importieren, die Vorschaufunktionen haben.

Wenn Sie beispielsweise die Go-Clientbibliothek verwenden möchten, müssen Sie die Methode replace verwenden. in der Datei go.mod, 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 Node.js-Client hinzu. Bibliotheksdownload (googleapis-classroom-1.0.4.tgz) als lokale Abhängigkeit in 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"
  }
}

Fordern Sie dann in Ihrer Anwendung das Modul classroom-with-preview-features an. zusätzlich zu den regulären Abhängigkeiten 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 wenn API-Aufrufe an Methoden mit Vorschaufunktionen gesendet werden.

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

Die Version wird über das Feld PreviewVersion in den Anfragen angegeben. Um beispielsweise ein Bewertungsschema mit der Bewertungsschemas-CRUD-Vorschau-API zu erstellen, legen Sie Folgendes fest: previewVersion zu V1_20231110_PREVIEW in der CREATE-Anfrage:

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: Vorschauversionen sind als temporäre Version vorgesehen, während Funktionen validiert werden. . Das Verhalten der Vorschauversion unterliegt nach Ablauf des Einstellungszeitraums ändern. Weitere Informationen finden Sie in der Classroom API-Roadmap.

Ressourcen, die mit einem Aufruf einer Vorschaumethode verknüpft sind, enthalten auch den Parameter previewVersion wird im Aufruf als schreibgeschütztes Feld verwendet, damit Sie die Informationen besser verstehen welche Version Sie verwenden. Die Antwort der vorherigen CREATE-Anweisung "call" enthält 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 einer Ressource zugeordnete Vorschauversion entspricht der Version zum Abrufen der Ressource verwendet wird, nicht unbedingt der Aufruf zum Erstellen der resource; bei zukünftigen GET-, LIST- oder PATCH-Aufrufen mit einer neuen Version angegeben ist, wird die neue Version zurückgegeben.

HTTP-Anfragen

Die Classroom API kann auch direkt mit HTTP verwendet werden.

Auch bei HTTP-Anfragen ohne Clientbibliothek müssen Sie Vorschaufunktionen geben eine Vorschauversion an. Legen Sie dazu eine label fest. mit einem X-Goog-Visibilities-Header und der oben genannten Vorschauversion als entweder einen Abfrageparameter oder ein POST-Body-Feld (siehe entsprechende API für Referenzdokumentation). Bei öffentlichen Vorschauen lautet das Label „DEVELOPER_PREVIEW“.

Die folgende curl-Anfrage sendet beispielsweise einen LIST-Aufruf an den Bewertungsschemas-Dienst. mit dem entsprechenden Sichtbarkeitslabel und der entsprechenden Vorschauversion:

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. wenn eine POST-Anfrage stellen:

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

Vorschau-APIs können über Google Apps Script aufgerufen werden. Es gibt jedoch Unterschiede zur üblichen Verwendung von Apps Script.

1. Sie müssen Ihr Skript so konfigurieren, dass ein beliebiges Google Cloud-Projekt verwendet wird Sie haben sich für das Vorschauprogramm für Entwickler registriert.
2. Erweiterte Dienste unterstützen keine Vorschaumethoden. Sie müssen daher -Anfragen direkt mit HTTP senden.
3. Sie müssen wie oben beschrieben ein Label und eine Vorschauversion angeben HTTP-Abschnitt:

Sehen Sie sich die entsprechende Kurzanleitung an, um sich mit den Apps Script und richten Sie ein grundlegendes Projekt ein. Folgen Sie dann dieser Anleitung zum Aufrufen von Preview-APIs:

Das vom Skript verwendete Cloud-Projekt ändern

Klicken Sie unter Projekteinstellungen auf Projekt ändern und geben Sie ID des Cloud-Projekts, das Sie beim Entwickler Vorschauprogramm (standardmäßig Apps Script-Skripts verwenden ein generisches Projekt. Nur angemeldete Nutzer Projekte können Vorschaumethoden aufrufen.

HTTP-Anfragen konfigurieren

Konfigurieren Sie als Nächstes die HTTP-Anfrage der Methode, die Sie zurückrufen möchten. Bearbeiter: Beispielsweise werden in der Kurzanleitung Kurse mit der Classroom-Version sieht 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 direkter HTTP-Verwendung 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, direkte HTTP-Aufrufe an Google APIs in Apps Script ausführen, müssen Sie die entsprechenden Bereiche manuell hinzufügen.

Aktivieren Sie in den Projekteinstellungen die Option appsscript.json anzeigen Manifestdatei in Editor. Fügen Sie im Editor oauthScopes zur appscript.json-Datei für welche Bereiche Sie benötigen. Die Bereiche für eine bestimmte Methode sind in der Referenzseite. Siehe zum Beispiel die Listenmethode courses.courseWork.rubrics .

Die aktualisierte Datei appscript.json 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

Fügen Sie im Skript das richtige Label hinzu und zeigen Sie eine Vorschau an. -Version wie im vorherigen HTTP-Abschnitt beschrieben. Das Beispiel für einen LIST-Aufruf an sieht der Bewertungsschemas-Dienst 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);
}