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 znajdziesz informacje o tym, jak uzyskać dostęp do funkcji w wersji testowej interfejsu Classroom API i określić wersje testowe.

W porównaniu ze stabilnym interfejsem API w wersji 1 podczas korzystania z funkcji w wersji testowej należy wziąć pod uwagę 3 kwestie:

Wywołujący projekt Google Cloud musi być zarejestrowany w programie przedpremierowym dla deweloperów Google Workspace i musi być na liście dozwolonych Google.
Funkcje interfejsu API w programach wcześniejszego dostępu lub w wersji podglądowej nie są udostępniane w standardowych bibliotekach klienta i domyślnie mogą być niedostępne przez HTTP.
W danej chwili w wersji zapoznawczej może być kilka stanów lub wersji interfejsu API.

Włączanie funkcji w wersji testowej w bibliotekach klienta

Popularnym sposobem korzystania z interfejsu Classroom API jest używanie biblioteki klienta. Istnieją 3 rodzaje bibliotek klienta:

Dynamicznie generowane biblioteki klienta
Statyczne biblioteki klienta dostarczane przez Google
własną bibliotekę klienta

Korzystanie z dynamicznie generowanych lub statycznych bibliotek udostępnianych przez Google to zalecany sposób korzystania z interfejsu API. Jeśli chcesz utworzyć własną bibliotekę, przeczytaj artykuł Tworzenie 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 przy użyciu dokumentu Discovery z usługi Discovery.

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 usługę interfejsu Classroom API (classroom.googleapis.com) znajdziesz w tym punkcie końcowym:

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

Ważną różnicą w pracy z interfejsami API w wersji podglądowej jest określenie odpowiedniego label. W przypadku publicznych wersji przedpremierowych Classroom etykieta toDEVELOPER_PREVIEW.

Aby wygenerować bibliotekę Pythona i utworzyć instancję usługi Classroom z metodami w wersji zapoznawczej, możesz określić adres URL wykrywania z odpowiednią usługą, 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 poszczególnych językach znajdziesz w dokumentacji biblioteki klienta interfejsu API Google.

Biblioteki statyczne

Biblioteki klienta w językach takich jak Java, Node.js, PHP, C# i Go muszą być tworzone na podstawie kodu źródłowego. Te biblioteki są udostępniane użytkownikom i zawierają już funkcje w wersji przedpremierowej.

W przypadku wersji przedpremierowych biblioteki klienta Classroom można znaleźć razem z innymi bibliotekami klienta programu wersji przedpremierowej Workspace dla programistów. W przypadku wersji prywatnych skontaktuj się z osobą kontaktową w Google, jeśli potrzebujesz wygenerowanych bibliotek statycznych.

Aby używać tych lokalnych bibliotek zamiast importować standardowe biblioteki klienta, które nie mają funkcji w wersji podglądowej, może być konieczne zmodyfikowanie typowej konfiguracji zależności.

Aby na przykład użyć biblioteki klienta w języku Go, musisz użyć dyrektywy replacew 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 pobraną bibliotekę 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 oprócz zwykłych zależności wymagaj modułu classroom-with-preview-features 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 podglądu

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

Dostępne wersje i funkcje, które zawierają, są opisane w harmonogramie interfejsu Classroom API. Dokumentacja referencyjna metod i pól zawiera też informacje o tym, w których wersjach są one dostępne.

Wersję określa się, ustawiając w żądaniach pole PreviewVersion. Aby na przykład utworzyć ocenę cząstkową za pomocą interfejsu Rubrics CRUD Preview API, w żądaniu CREATE ustawisz wartość 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żyte w wywołaniu jako pole tylko do odczytu, co pomaga zrozumieć, której wersji używasz. Na przykład odpowiedź z poprzedniego wywołania 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

Możesz też używać interfejsu API Classroom bezpośrednio za pomocą protokołu HTTP.

Jeśli wysyłasz żądania HTTP bez biblioteki klienta, musisz włączyć funkcje w wersji przedpremierowej i określić 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 żądania POST (patrz odpowiednia dokumentacja interfejsu API). W przypadku publicznych wersji przedpremierowych etykieta to DEVELOPER_PREVIEW.

Na przykład to żądanie curl wywołuje metodę LIST w usłudze 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

W treści żądania możesz też określić wersję podglądu, 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 dla każdego żądania HTTP jest opisany w dokumentacji REST.

Google Apps Script

Z poziomu Google Apps Script można wywoływać interfejsy API w wersji przedpremierowej. Występuje jednak kilka różnic w porównaniu z typowym użyciem Apps Script.

Musisz skonfigurować skrypt tak, aby używał projektu Google Cloud, w którym zarejestrowano Cię w programie testów wersji przedpremierowych dla deweloperów.
Usługi zaawansowane nie obsługują metod podglądu, więc musisz wysyłać żądania bezpośrednio za pomocą protokołu HTTP.
Musisz podać etykietę i wersję podglądu zgodnie z opisem 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 podglądu:

Zmienianie projektu w Google Cloud używanego przez skrypt

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

Konfigurowanie żądań HTTP

Następnie skonfiguruj żądanie HTTP dowolnej metody, którą chcesz wywołać zwrotnie w Edytorze. Na przykład w krótkim wprowadzeniu lista kursów z usługą 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);
  }
}

Odpowiednikiem tej operacji przy użyciu bezpośredniego HTTP jest:

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

W przypadku usług zaawansowanych wymagane zakresy OAuth są wywnioskowane, ale aby wykonywać bezpośrednie wywołania HTTP do interfejsów API Google w Apps Script, musisz ręcznie dodać odpowiednie zakresy.

W ustawieniach projektu włącz opcję Wyświetlaj plik manifestu „appsscript.json” w edytorze. Wróć do Edytora i dodaj oauthScopes do pliku appscript.json w przypadku zakresów, których potrzebujesz. Zakresy dla danej metody są wymienione na stronie referencyjnej. Na przykład zobacz 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"
  ]
}

Podaj 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 dotyczącej HTTP. Przykładowe wywołanie LIST do usługi Rubrics wyglądałoby 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);
}