Dodatki do Google Classroom są teraz ogólnie dostępne dla programistów. Więcej informacji znajdziesz w dokumentacji dodatków.

Ta strona została przetłumaczona przez Cloud Translation API.

Dostęp do interfejsów API podglądu

Na tej stronie dowiesz się, jak uzyskać dostęp do funkcji w wersji testowej interfejsu Classroom API oraz określić wersje podglądu.

Trzy, które należy wziąć pod uwagę podczas korzystania z funkcji w wersji testowej w porównaniu z funkcjami w wersji stabilnej Interfejs API w wersji 1 to:

Wywołujący projekt Google Cloud musi być zarejestrowany w Google Workspace Program podglądu dla programistów i dozwolone przez Google.
Funkcje interfejsu API w programach wcześniejszego dostępu lub wersji przedpremierowej nie są widoczne w standardowych bibliotek klienta i mogą być niedostępne domyślnie przez HTTP.
W danym momencie w podgląd.

Włącz funkcje w wersji testowej w bibliotekach klienta

Typowym sposobem korzystania z interfejsu Classroom API jest biblioteka klienta. OK są 3 typy bibliotek klienta:

Dynamicznie generowane biblioteki klienta
Udostępnione przez Google statyczne biblioteki klienta
Twoja własna biblioteka klienta

Użycie dynamicznie generowanych lub dostarczanych przez Google bibliotek statycznych zalecanym sposobem korzystania z interfejsu API. Jeśli chcesz, przeczytaj artykuł o tworzeniu bibliotek klienta. aby utworzyć własną bibliotekę. Nie można tu utworzyć własnej biblioteki. znajdziesz w przewodniku, ale możesz też zapoznać się z sekcją bibliotek dynamicznych, wyświetlić podgląd etykiet i ich roli w Discovery.

Biblioteki dynamiczne

Biblioteki w językach takich jak Python generują bibliotekę klienta w czasie działania za pomocą dokument wykrywania z usługi wykrywania.

Dokument Discovery to czytelna dla komputera specyfikacja służąca do korzystające z interfejsów API typu REST. Służy do tworzenia bibliotek klienta, wtyczek IDE inne narzędzia współpracujące z interfejsami API Google. Jedna usługa może obejmować wiele dokumenty wykrywania.

Dokumenty Discovery dla usługi interfejsu Classroom API (classroom.googleapis.com) znajduje się w punkcie końcowym:

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

Ważną różnicą w przypadku korzystania z interfejsów API w wersji testowej jest określenie odpowiedni label. W przypadku publicznego podglądu Classroom etykieta to DEVELOPER_PREVIEW

Aby wygenerować bibliotekę Pythona i utworzyć instancję usługi Classroom za pomocą możesz określić adres URL Discovery za pomocą odpowiedniej usługi, dane logowania i etykietę:

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

Szczegółowe informacje o poszczególnych interfejsach API znajdziesz w dokumentacji biblioteki klienta dotyczącej poszczególnych interfejsów API Google. język.

Biblioteki statyczne

Należy utworzyć biblioteki klienta w językach takich jak Java, Node.js, PHP, C# i Go ze źródła. Te biblioteki są udostępnione dla Ciebie i udostępniają funkcje w wersji testowej już uwzględnione.

W przypadku publicznych wersji przedpremierowych biblioteki klienta Classroom można znaleźć razem z innymi bibliotekami Biblioteki klienta Programu testowania dla programistów Workspace. W przypadku prywatnego podglądu Jeśli potrzebujesz wygenerowanych bibliotek statycznych, skontaktuj się ze swoją osobą kontaktową w Google.

Aby z nich korzystać, może być konieczne zmodyfikowanie typowej konfiguracji zależności bibliotek lokalnych zamiast importowania standardowych bibliotek klienta, które tego nie robią dostępne w wersji testowej.

Aby na przykład korzystać z biblioteki klienta w języku Go, musisz użyć interfejsu replace w pliku go.mod, aby wymagać modułu z katalogu lokalnego:

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

W kolejnym przykładzie, jeśli używasz Node.js i npm, dodaj klienta Node.js. pobieranie biblioteki (googleapis-classroom-1.0.4.tgz) jako zależność lokalna w 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"
  }
}

Następnie w aplikacji dodaj moduł classroom-with-preview-features oprócz zwykłych zależności i utwórz instancję usługi classroom. z tego modułu:

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

...

Określ wersję podglądu interfejsu API

Niezależnie od tego, czy używasz biblioteki statycznej czy dynamicznej, musisz określić wersji przedpremierowej podczas wykonywania wywołań interfejsu API w metodach z możliwością testowania.

Różne dostępne wersje i obsługiwane w nich funkcje są opisane w dokumentacji w Harmonogramie rozwoju interfejsu Classroom API. w dokumentacji referencyjnej dotyczącej metod zawierają też informacje o wersjach, w których dostępna jest metoda lub pole.

Wersję określa się przez ustawienie pola PreviewVersion w żądaniach. Aby na przykład utworzyć ocenę cząstkową za pomocą interfejsu API podglądu ocen cząstkowych, musisz ustawić Z previewVersion do V1_20231110_PREVIEW w żądaniu 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()

Zasoby powiązane z wywołaniem metody podglądu zawierają też Pole previewVersion zostało użyte w rozmowie jako pole tylko do odczytu, aby pomóc Ci zrozumieć której wersji używasz. Na przykład odpowiedź z poprzedniego polecenia CREATE wywołanie zawiera wartość 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",
  ...
}

Żądania HTTP

Interfejsu API Classroom można też używać bezpośrednio przez HTTP.

Nawet jeśli wysyłasz żądania HTTP bez biblioteki klienta, musisz włączyć funkcje w wersji testowej określają wersję przedpremierową. Aby to zrobić, ustaw label z nagłówkiem X-Goog-Visibilities i wspomnianą wersją podglądu jako parametr zapytania lub pole treści POST (patrz odpowiednie dokumentacja). W przypadku podglądów publicznych etykieta to DEVELOPER_PREVIEW.

Na przykład poniższe żądanie curl wysyła wywołanie funkcji LIST do usługi ocen cząstkowych. z odpowiednią etykietą widoczności i wersją podglądu:

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

Możesz również określić wersję podglądu w treści żądania, na przykład gdy wysyłanie żądania 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

Interfejs API każdego żądania HTTP został opisany w dokumentacji REST.

Google Apps Script

Można wywoływać interfejsy API podglądu za pomocą Google Apps Script. Istnieją jednak o kilka różnicach w stosunku do typowego użycia Apps Script.

Musisz skonfigurować skrypt tak, aby używał wybranego projektu Google Cloud zarejestrowane w Programie testowania aktualizacji dla programistów.
Usługi zaawansowane nie obsługują metod podglądu, więc musisz bezpośrednio przez HTTP.
Musisz podać etykietę i wersję podglądu zgodnie z opisem powyżej Sekcja HTTP.

Aby się zapoznać, zapoznaj się z odpowiednim krótkim wprowadzeniem. Apps Script i uzyskanie podstawowej konfiguracji projektu. Następnie postępuj zgodnie z tymi instrukcjami: instrukcje dotyczące rozpoczynania wywoływania interfejsów API w wersji testowej:

Zmiana projektu Cloud używanego przez skrypt

W Ustawieniach projektu kliknij Zmień projekt i wpisz wartość Identyfikator projektu Cloud powiązany z projektem zarejestrowanym w usłudze Deweloper Program testowania aktualizacji (domyślnie skrypty Apps Script używają ogólnego projektu). Tylko zarejestrowane projekty mogą wywoływać metody podglądu.

Konfigurowanie żądań HTTP

Następnie skonfiguruj żądanie HTTP w przypadku dowolnej metody, za pomocą której chcesz oddzwonić Edytujący. Możesz na przykład w krótkim wprowadzeniu podać listę kursów prowadzonych w Classroom. usługa wygląda tak:

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

Odpowiednia operacja przy użyciu bezpośrednio protokołu HTTP:

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

Podczas korzystania z usług zaawansowanych wymagane zakresy OAuth są wnioskowane, ale bezpośrednich wywołań HTTP do interfejsów API Google w Apps Script, musisz: ręcznie dodać odpowiednie zakresy.

W Ustawieniach projektu włącz opcję Pokaż plik „appsscript.json” plik manifestu w . Wróć do Edytora i dodaj adres oauthScopes do pliku appscript.json dla w zależności od potrzeb. Zakresy danej metody są wymienione w stronie referencyjnej. Zobacz na przykład metodę listycourses.courseWork.rubrics .

Zaktualizowany plik appscript.json może wyglądać tak:

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

Podaj etykietę i wersję podglądu

Wróć do skryptu, sprawdź, czy dodano odpowiednią etykietę i wyświetl podgląd. zgodnie z opisem w poprzedniej sekcji dotyczącej HTTP. Przykładowe wywołanie funkcji LIST do usługa oceny cząstkowej będzie wyglądała tak:

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