Dostęp do interfejsów API podglądu

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

Dwie kwestie, które należy wziąć pod uwagę podczas korzystania z funkcji wersji testowej w porównaniu ze stabilnym interfejsem API 1, to:

Funkcje interfejsu API w programach wcześniejszego dostępu lub wersji przedpremierowej nie są udostępniane w standardowych bibliotekach klienta i mogą być domyślnie niedostępne przez HTTP.
W danym momencie wersja testowa może zawierać kilka stanów lub wersji interfejsu API.

Włącz funkcje podglądu w bibliotekach klienta

Typowym sposobem korzystania z interfejsu Classroom API jest skorzystanie z biblioteki klienta. Istnieją 3 typy bibliotek klienta:

Dynamicznie generowane biblioteki klienckie
Statyczne biblioteki klienta udostępnione przez Google
Twoja własna biblioteka klienta

Zalecanym sposobem korzystania z interfejsu API jest korzystanie z bibliotek statycznych generowanych dynamicznie lub dostarczanych przez Google. Jeśli chcesz utworzyć własną bibliotekę, przeczytaj artykuł o tworzeniu bibliotek klienta. Tworzenie własnej biblioteki nie wykracza poza zakres tego przewodnika, ale przejrzyj sekcję biblioteki dynamiczne, aby dowiedzieć się więcej o etykietach podglądu i ich roli w wykrywaniu.

Biblioteki dynamiczne

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

Dokument Discovery to czytelna dla komputera specyfikacja opisująca i wykorzystując interfejsy API REST. Jest używany 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 dotyczących wykrywania.

Dokumenty Discovery 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 korzystania z interfejsów API w wersji testowej jest określenie odpowiedniego elementu label. W przypadku publicznego podglądu Classroom ta etykieta to DEVELOPER_PREVIEW.

Aby wygenerować bibliotekę Pythona i utworzyć instancję usługi Classroom przy użyciu metod podglądu, możesz określić 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 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 źródła. Te biblioteki są udostępniane Tobie i mają już włączone funkcje w wersji testowej.

W przypadku publicznej wersji przedpremierowej biblioteki klienta Classroom można znaleźć razem z innymi bibliotekami klienta Workspace Developer Preview Program. Jeśli potrzebujesz wygenerowanych bibliotek statycznych, skontaktuj się ze swoim przedstawicielem Google w sprawie prywatnej wersji przedpremierowej.

Może być konieczne zmodyfikowanie typowej konfiguracji zależności, aby użyć tych bibliotek lokalnych, zamiast importowania standardowych bibliotek klienta, które nie mają funkcji w wersji testowej.

Aby np. skorzystać z biblioteki klienta w języku 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 używasz Node.js i npm, dodaj do pobrania bibliotekę klienta Node.js (googleapis-classroom-1.0.4.tgz) jako zależność lokalną 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 swojej aplikacji wymagaj modułu classroom-with-preview-features jako uzupełnienie 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 testowej interfejsu API

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

Różne dostępne wersje i funkcje, które się w nich obejmują, znajdziesz w harmonogramie korzystania z interfejsu Classroom API. Dokumentacja metod i pól zawiera też informacje o tym, w których wersjach jest dostępna metoda lub pole.

Aby określić wersję, ustaw w żądaniach pole PreviewVersion. Aby na przykład utworzyć ocenę cząstkową za pomocą interfejsu Rubrics CRUD API, ustaw w żądaniu CREATE 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żywane w wywołaniu jako pole tylko do odczytu, dzięki czemu możesz sprawdzić, 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

Z interfejsu Classroom API można też korzystać bezpośrednio przez HTTP.

Nawet jeśli wysyłasz żądania HTTP bez biblioteki klienta, i tak musisz włączyć funkcje podglądu, aby 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 POST. W przypadku podglądów publicznych etykieta to DEVELOPER_PREVIEW.

Na przykład to żądanie curl powoduje wywołanie listy 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_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, na przykład podczas tworzenia żądania POST:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

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