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 i określić wersje testowe.

Podczas korzystania z funkcji w wersji testowej w porównaniu ze stabilnym interfejsem API w wersji 1 trzeba wziąć pod uwagę 3 rzeczy:

Wywołujący projekt Google Cloud musi być zarejestrowany w programie testowania wersji dla programistów Google Workspace i zezwalać na wyświetlanie go przez Google.
Funkcje interfejsu API w programach z wcześniejszym dostępem lub w ramach wersji w podglądzie nie są dostępne w standardowych bibliotekach klienta i mogą nie być dostępne domyślnie przez HTTP.
W danym momencie podgląd może mieć wiele stanów lub wersji interfejsu API.

Włączanie funkcji podglądu w bibliotekach klienta

Interfejs Classroom API można używać za pomocą biblioteki klienta. Istnieją 3 rodzaje bibliotek klienta:

Biblioteki klienta generowane dynamicznie
Biblioteki klienta statyczne dostarczane przez Google
własną bibliotekę klienta,

Korzystanie z bibliotek generowanych dynamicznie lub udostępnianych przez Google jest zalecanym sposobem korzystania z interfejsu API. Jeśli chcesz utworzyć własną bibliotekę, zapoznaj się z informacjami na temat tworzenia bibliotek klienta. Tworzenie własnej biblioteki wykracza poza zakres tego przewodnika, ale warto zapoznać się z sekcją Biblioteki dynamiczne, aby dowiedzieć się więcej o etykietach podglądu i ich roli w Discovery.

Biblioteki dynamiczne

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

Dokument opisujący to czytelna dla komputera specyfikacja opisująca interfejsy API REST i sposób ich używania. Służy do tworzenia bibliotek klienta, wtyczek IDE i innych narzędzi, które współdziałają z interfejsami API Google. Jedna usługa może udostępniać wiele dokumentów opisujących.

Dokumenty opisujące interfejs Classroom API (classroom.googleapis.com) znajdziesz pod tym punktem końcowym:

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

Ważną różnicą w przypadku pracy z interfejsami API w wersji wstępnej jest określenie odpowiedniego label. W przypadku publicznych wersji przedpremierowych Classroom ta etykieta to DEVELOPER_PREVIEW.

Aby wygenerować bibliotekę Pythona i utworzyć instancję usługi Classroom za pomocą metod podglądu, możesz określić adres URL usługi Discovery z odpowiednimi danymi 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 każdym języku znajdziesz w dokumentacji biblioteki klienta interfejsu API.

Biblioteki statyczne

Biblioteki klientów w językach takich jak Java, Node.js, PHP, C# i Go muszą być kompilowane na podstawie kodu źródłowego. Te biblioteki są dostępne dla Ciebie i mają już wbudowane funkcje podglądu.

W przypadku publicznych wersji przedpremierowych biblioteki klienta Classroom można znaleźć w innych bibliotekach klienta programu podglądu dla programistów Workspace. Jeśli chcesz wyświetlić podgląd prywatny, skontaktuj się z osobą kontaktową z Google, jeśli potrzebujesz wygenerowanych bibliotek statycznych.

Aby używać tych lokalnych bibliotek zamiast standardowych bibliotek klienta, które nie mają funkcji podglądu, może być konieczne zmodyfikowanie konfiguracji typowych zależności.

Aby na przykład korzystać z biblioteki klienta Go, musisz użyć dyrektywy 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

Jeśli na przykład używasz Node.js i npm, dodaj pobranie biblioteki klienta Node.js (googleapis-classroom-1.0.4.tgz) jako lokalną zależność 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 wymagaj modułu 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ślanie wersji interfejsu API w wersji testowej

Niezależnie od tego, czy używasz biblioteki statycznej czy dynamicznej, musisz określić wersję podglądu podczas wywoływania metod interfejsu API z możliwościami podglądu.

Różne dostępne wersje i zawarte w nich funkcje są opisane w Harmonogramie rozwoju interfejsu Classroom API. Dokumentacja referencyjna metod i pol zawiera też informacje o tym, w których wersjach są one dostępne.

Wersję określa się, ustawiając pole PreviewVersion w żądaniach. Aby na przykład utworzyć ocenę cząstkową za pomocą interfejsu API podglądu Rubrics CRUD, w żądaniu CREATE ustaw previewVersion na 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()

Zasoby powiązane z wywołaniem metody podglądu zawierają też pole previewVersion używane w wywołaniu jako pole tylko do odczytu, aby ułatwić Ci ustalenie, której wersji używasz. Na przykład odpowiedź z poprzedniego wywołania metody CREATE 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

Interfejs Classroom API można też używać bezpośrednio za pomocą HTTP.

Jeśli wysyłasz żądania HTTP bez biblioteki klienta, musisz też włączyć funkcje podglądu, aby określić wersję podglądu. Aby to zrobić, ustaw label z nagłówkiem X-Goog-Visibilities i powyższym plikiem wersji podglądu jako parametrem zapytania lub polem treści żądania POST (patrz odpowiednia dokumentacja poszczególnych interfejsów API). W przypadku publicznych wersji przedpremierowych etykieta to DEVELOPER_PREVIEW.

Na przykład to żądanie curl wywołuje LIST do usługi Rubrics 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

Wersję podglądu możesz też określić w treści żądania, np. podczas wysyłania żą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

Z poziomu Google Apps Script można wywoływać interfejsy API wersji próbnej. Występują jednak pewne różnice w porównaniu ze zwykłym korzystaniem z Google Apps Script.

Musisz skonfigurować skrypt w taki sposób, aby używał projektu Google Cloud zarejestrowanego w Programie podglądu dla programistów.
Usługi zaawansowane nie obsługują metod podglądu, więc żądania należy wysyłać bezpośrednio przez HTTP.
Musisz podać etykietę i wersję podglądu, jak opisano w poprzedniej sekcji HTTP.

Zapoznaj się z odpowiednim krótkim przewodnikiem, aby poznać Apps Script i skonfigurować podstawowy projekt. Następnie postępuj zgodnie z tymi instrukcjami, aby rozpocząć wywoływanie interfejsów API w wersji podglądu:

Zmień projekt Cloud używany przez skrypt

W sekcji Ustawienia projektu kliknij Zmień projekt i wpisz identyfikator projektu Cloud, który został zarejestrowany w programie podglądu dla deweloperów (domyślnie skrypty Apps Script korzystają z ogólnego projektu). Metody podglądu mogą wywoływać tylko zarejestrowane projekty.

Konfigurowanie żądań HTTP

Następnie skonfiguruj żądanie HTTP metody, którą chcesz wywołać w Edytorze. Na przykład w Quickstart lista kursów w usłudze Classroom 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ą ustalane automatycznie, ale aby wykonywać bezpośrednie wywołania HTTP interfejsów API Google w Apps Script, musisz ręcznie dodać odpowiednie zakresy.

W Ustawieniach projektu włącz opcję Pokaż plik manifestu „appsscript.json” w edytorze. Wróć do Edytora i dodaj oauthScopes do pliku appscript.json dla odpowiednich zakresów. Zakresy danej metody są wymienione na stronie z odwołaniami. Zobacz na przykład stronę metody courses.courseWork.rubrics list.

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

Prześlij etykietę i wersję podglądu

Wróć do skryptu i upewnij się, że dodano odpowiednią etykietę i wersję podglądu zgodnie z opisem w poprzedniej sekcji HTTP. Przykładowe wywołanie LIST w usłudze Rubrics:

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