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

Oto 3 kwestie, o których należy pamiętać, korzystając z funkcji w wersji testowej w porównaniu ze stabilną wersją interfejsu API w wersji 1:

Projekt Google Cloud wywołujący usługę musi być zarejestrowany w programie podglądu dla deweloperów Google Workspace i dostępny w 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 może być kilka wersji interfejsu API w wersji podglądowej.

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 wykonywania za pomocą 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 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 próbnych biblioteki klienta Classroom można znaleźć wśród innych bibliotek klienta w ramach programu wersji przedpremierowej Workspace dla programistów. 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 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

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 funkcjami podglądu.

Informacje o różnych dostępnych wersjach i funkcjach, które zawierają, znajdziesz w mapie drogowej interfejsu API Classroom. 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 CRUD Rubrics, w żądaniu CREATE ustawisz parametr 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 dla każdego żądania HTTP jest 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 tak, aby korzystał z projektu Google Cloud zarejestrowanego w programie podglądu dla deweloperów.
Usługi zaawansowane nie obsługują metod podglądu, więc żądania należy wysyłać bezpośrednio za pomocą protokołu 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 używają 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 bezpośrednio w 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 sekcji Ustawienia projektu włącz opcję Wyświetl plik manifestu „appsscript.json” w edytorze. W Edytorze dodaj plik oauthScopes do pliku appscript.json dla odpowiednich zakresów. Zakresy danej metody są wymienione na stronie referencyjnej. 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);
}