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

Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Dostęp do interfejsów API podglądu

Na tej stronie dowiesz się, jak uzyskać dostęp do funkcji w wersji przedpremierowej interfejsu Classroom API i określić wersje przedpremierowe.

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

Wywołujący projekt Google Cloud musi być zarejestrowany w Programie wersji przedpremierowych dla deweloperów Google Workspace i musi być na liście dozwolonych Google.
Funkcje interfejsu API w programach wczesnego dostępu lub wersji przedpremierowej nie są udostępniane w standardowych bibliotekach klienta i domyślnie mogą być niedostępne przez HTTP.
W danym momencie może być dostępnych kilka stanów lub wersji interfejsu API w wersji przedpremierowej.

Włączanie funkcji w wersji przedpremierowej w bibliotekach klienta

Częstym sposobem korzystania z interfejsu Classroom API jest używanie biblioteki klienta. Dostępne są 3 typy bibliotek klienta:

Biblioteki klienta generowane dynamicznie
Statyczne biblioteki klienta udostępniane przez Google
Własna biblioteka klienta

Zalecamy korzystanie z interfejsu API za pomocą bibliotek statycznych generowanych dynamicznie lub udostępnianych przez Google. 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 wersji przedpremierowych i ich roli w usłudze Discovery.

Biblioteki dynamiczne

Biblioteki w językach takich jak Python generują bibliotekę klienta w czasie działania za pomocą dokumentu opisującego 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 dla usługi 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 przypadku pracy z interfejsami API w wersji przedpremierowej 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 w wersji przedpremierowej, możesz określić adres URL Discovery 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 każdym języku znajdziesz w dokumentacji biblioteki klienta interfejsu API Google client library documentation.

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 i mają już wbudowane funkcje w wersji przedpremierowej.

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

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

Aby na przykład użyć 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

Inny przykład: jeśli używasz Node.js i npm, dodaj pobraną bibliotekę klienta Node.js (googleapis-classroom-1.0.4.tgz) jako zależność lokalną w pliku 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 przedpremierowej interfejsu API

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

Różne dostępne wersje i funkcje, które zawierają, są opisane w planie rozwoju interfejsu Classroom API. Dokumentacja referencyjna metod i pól zawiera też informacje o tym, w których wersjach jest dostępna dana metoda lub pole.

Wersję określa się, ustawiając pole PreviewVersion w żądaniach. Aby na przykład utworzyć kryterium oceny za pomocą interfejsu Rubrics CRUD API w wersji przedpremierowej, 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 w wersji przedpremierowej zawierają też pole tylko do odczytu previewVersion użyte w wywołaniu, aby ułatwić Ci sprawdzenie, której wersji używasz. Na przykład odpowiedź na poprzednie wywołanie 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ż korzystać z interfejsu Classroom API 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ą. W tym celu ustaw label z nagłówkiem X-Goog-Visibilities i wspomnianą wersją przedpremierową jako parametr zapytania lub pole treści POST (szczegółowe informacje znajdziesz w odpowiedniej dokumentacji referencyjnej interfejsu API). W przypadku publicznych wersji przedpremierowych etykieta to DEVELOPER_PREVIEW.

Na przykład to żądanie curl wykonuje wywołanie LIST do usługi Rubrics z odpowiednią etykietą widoczności i wersją przedpremierową:

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ę przedpremierową możesz też określić w treści żądania, na przykład 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

Możesz wywoływać interfejsy API w wersji przedpremierowej z Google Apps Script. 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 się w Programie wersji przedpremierowych dla deweloperów.
Usługi zaawansowane nie obsługują metod w wersji przedpremierowej, więc musisz wysyłać żądania bezpośrednio za pomocą protokołu HTTP.
Musisz podać etykietę i wersję przedpremierową zgodnie z opisem w poprzedniej sekcji HTTP.

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

Zmienianie projektu Cloud używanego przez skrypt

W sekcji Ustawienia projektu kliknij Zmień projekt i wpisz identyfikator projektu Cloud, w którym zarejestrowano się w Programie wersji przedpremierowych dla deweloperów (domyślnie skrypty Apps Script używają projektu ogólnego). Tylko zarejestrowane projekty mogą wywoływać metody w wersji przedpremierowej.

Konfigurowanie żądań HTTP

Następnie w Edytorze skonfiguruj żądanie HTTP dowolnej metody, którą chcesz wywołać. Na przykład w krótkim przewodniku wyświetlanie listy kursów za pomocą usługi 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 wykonywana bezpośrednio za pomocą protokołu HTTP wygląda tak:

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 korzystania z usług zaawansowanych wymagane zakresy OAuth są wnioskowane, ale aby wykonywać bezpośrednie wywołania HTTP do interfejsów API Google w Apps Script, musisz ręcznie dodać odpowiednie zakresy.

W sekcji Ustawienia projektu włącz opcję Wyświetlaj plik manifestu „appsscript.json” w edytorze. W Edytorze dodaj oauthScopes do pliku appscript.json dla wszystkich potrzebnych zakresów. Zakresy dla danej metody są wymienione na stronie referencyjnej. Na przykład zapoznaj się ze 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"
  ]
}

Podawanie etykiety i wersji przedpremierowej

W skrypcie upewnij się, że masz dodaną odpowiednią etykietę i wersję przedpremierową zgodnie z opisem w poprzedniej sekcji HTTP. Przykładowe wywołanie LIST do usługi Rubrics wygląda 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);
}