Struktura interfejsu API

Ten przewodnik zawiera omówienie głównych komponentów interfejsu Google Classroom API. Interfejs Google Classroom API składa się z zasobów i usług. Zasoby reprezentują elementy w Google Classroom, takie jak kurs lub projekt, a usługi umożliwiają pobieranie tych zasobów i zarządzanie nimi. Niektóre z tych encji oprócz właściwości występujących w Classroom mają dodatkowe właściwości specyficzne dla interfejsu API. Główne typy elementów to:

Jednostka	Reprezentacja w Classroom
Kursy	Klasa, np. „M. Smith's 4th period math".
Aliasy	Alternatywny identyfikator zajęć.
Zaproszenia	Sposób dodawania użytkowników do zajęć.
Uczniowie	Uczeń na zajęciach.
Nauczyciele	Nauczyciel na zajęciach.
Profile użytkowników	Użytkownik w ogólnym znaczeniu, poza kontekstem ucznia lub nauczyciela.
CourseWork	projekt z zajęć.
StudentSubmissions	prace uczniów dotyczące danego projektu, takie jak odpowiedzi lub arkusze;
CourseWorkMaterials	Materiały dla uczniów biorących udział w zajęciach.
Ogłoszenia	Ogłoszenie dla uczniów na zajęciach.
AddOnAttachment	Treści lub zadania w ramach projektu lub materiału, które są zwykle wyświetlane jako osadzony iframe.
Tematy	Wizualne grupowanie projektów i materiałów na zajęciach.
Rejestracje	Instrukcja wysyłania do aplikacji powiadomień w przypadku zmian danych, np. listy uczniów.

Większość zasobów ma metody usług do wykonywania standardowych operacji, takich jak odczytywanie, aktualizowanie i usuwanie wystąpień zasobu. Niektóre zasoby mają też niestandardowe metody do innych działań, takich jak modyfikowanie listy uczniów, którym przypisano konkretny projekt.

Szczegółowe informacje o zasobach i metodach interfejsu API znajdziesz w dokumentacji interfejsu API Classroom.

Omówienie relacji między zasobami

• Zajęcia to podstawowy obiekt danych w Google Classroom.
• Aliasy są używane jako alternatywne identyfikatory Courses.
• Zaproszenia służą do zapraszania profili użytkowników do pełnienia roli nauczycieli lub uczniów w Course. Użytkownicy mogą też być dodawani bezpośrednio przez administratorów domen Google Workspace for Education.
• Nauczyciele tworzą elementy strumienia i udostępniają je uczniom na swoich kursach. Możliwe typy elementów strumienia to Coursework, CourseWorkMaterials i Announcements. Elementy CourseWork i CourseWorkMaterials można wizualnie porządkować według tematów. Mogą one zawierać załączniki z dodatku. Uczniowie przesyłają StudentSubmissions do projektu CourseWork.
• Deweloperzy mogą tworzyć rejestracje, aby otrzymywać powiadomienia o zmianach niektórych danych.

Google Classroom jest dostępna w domenach, które korzystają z Google Workspace for Education. Domena w kontekście Classroom zwykle reprezentuje okręg szkolny. Możesz utworzyć domenę testową Google Workspace for Education na potrzeby rozwoju, co zapewni Ci kontrolę nad produkcyjną instancją Classroom bez wpływu na rzeczywistych użytkowników.

Kursy i aliasy

Courses reprezentuje klasę, np. „M”. „4 godzina matematyki Smitha” oraz przypisani nauczyciele, lista uczniów i metadane. Każdy kurs jest identyfikowany przez unikalny identyfikator przypisany przez serwer. Zasób Course zawiera wszystkie metadane dotyczące kursu, takie jak nazwa, opis, lokalizacja i czas. Listami uczniów zarządza się za pomocą zasobów Uczeń, Nauczyciel i Zaproszenie oraz ich metod.

Aliases to alternatywne identyfikatory zajęć, które mogą być powiązane z kursem i używane zamiast unikalnego identyfikatora. Każdy alias znajduje się w przestrzeni nazw, która ogranicza, kto może go utworzyć i wyświetlić. Obsługiwane są 2 przestrzenie nazw:

• Domena: przestrzeń nazw domeny przydaje się do tworzenia aliasów, do których wszyscy użytkownicy potrzebują dostępu, ale nie są związane z żadnym programem. Na przykład alternatywne listy kursów, takie jak MATH 127 i COMSCI 127, powinny być tworzone w przestrzeni nazw domeny. Aliasy w przestrzeni nazw domeny mogą tworzyć tylko administratorzy domeny, ale są widoczne dla wszystkich użytkowników domeny.
• Projekt dewelopera: przestrzeń nazw projektu dewelopera jest przydatna do zarządzania aliasami związanymi z konkretną aplikacją. Na przykład aplikacja, która używa alternatywnych identyfikatorów kursów, może tworzyć aliasy, aby mapować identyfikator na kursy w Classroom. Aliasy utworzone w tym zakresie nazw są powiązane z konkretną Konsolą interfejsów API Google. Każdy użytkownik aplikacji może tworzyć i wyświetlać aliasy w przestrzeni nazw projektu dewelopera tej aplikacji.

Więcej informacji o zarządzaniu metadanymi i aliasami zajęć znajdziesz w artykule Zarządzanie zajęciami.

Listy uczniów i uczniowie

Students i Teachers to określone powiązania między profilem użytkownika a zajęciami, które reprezentują rolę użytkownika w kursie. Użytkownik może być nauczycielem na jednych zajęciach i uczniem na innych. Oznaczenie „uczeń” lub „nauczyciel” oznacza zestaw uprawnień danego użytkownika w danym kursie.

Uczniowie

Zasób Student reprezentuje użytkownika, który jest uczniem w określonym kursie.

Uczniowie mogą wyświetlać informacje o zajęciach i nauczycielach.

Nauczyciele

Zasób Teacher reprezentuje użytkownika, który prowadzi konkretny kurs.

Nauczyciele mogą wyświetlać i zmieniać szczegóły zajęć, wyświetlać nauczycieli i uczniów oraz zarządzać dodatkowymi nauczycielami i uczniami.

Invitations i powiązane z nimi metody stanowią wygodny sposób dodawania uczniów i nauczycieli do zajęć. Tworzenie zaproszeń pozwala użytkownikom decydować, czy chcą dołączyć do kursu, zamiast dodawania ich bezpośrednio za pomocą zasobów dla nauczycieli i uczniów.

UserProfiles to mapowanie do profilu domeny użytkownika zidentyfikowanego na podstawie unikalnego identyfikatora lub adresu e-mail użytkownika zwróconego przez Directory API. Bieżący użytkownik może też sprawdzić swój identyfikator, używając skrótu "me".

Przy użyciu usługi UserProfiles można też zapraszać użytkowników Guardians, czyli mapowania między uczniem a opiekunem. Opiekunowie w Classroom mają dostęp do niektórych informacji o uczniach, na przykład do ich projektów.

Więcej informacji o zarządzaniu listami znajdziesz w artykule Zarządzanie listami nauczycieli i uczniów.

Zadania z zajęć i prace uczniów

Element CourseWork reprezentuje jedno zadanie przypisane do grupy uczniów biorących udział w zajęciach. Zawiera ona szczegóły takie jak opis, termin i materiały, a także metadane, takie jak czas utworzenia. Materiały obejmują tytuł, miniaturę i adres URL, a także identyfikator, którego można używać z odpowiednimi interfejsami API (np. Dysk, YouTube).

Elementy CourseWork opisują jeden z tych typów zadań:

• Projekt, który uczniowie wykonują, przesyłając arkusze lub inne załączniki.
• Pytanie z krótką odpowiedzią lub pytanie jednokrotnego wyboru.

Zadania uczniów dotyczące elementu CourseWork są oznaczone symbolem StudentSubmission. Zawiera on odpowiedź i dodatkowe metadane, takie jak stan i przypisana ocena.

Treść elementu StudentSubmission zależy od typu odpowiadającego mu elementu CourseWork:

• Arkusze robocze i załączniki przesłane do projektu, w tym tytuł, miniatura i adres URL, a także identyfikatory, których można użyć z odpowiednimi interfejsami API, takimi jak Dysk czy YouTube.
• Odpowiedź na pytanie z krótką odpowiedzią lub pytanie jednokrotnego wyboru.

Więcej informacji o zarządzaniu pracami domowymi i zadaniami uczniów znajdziesz w artykule Zarządzanie zadaniami.

Materiały i ogłoszenia dotyczące pracy domowej

Podobnie jak CourseWork, CourseWorkMaterials to treści przypisane grupie uczniów w kursie, wraz z tytułem i opisem oraz materiałami. Jednak w odróżnieniu od CourseWork projekt CourseWorkMaterials nie wymaga od uczniów przesyłania żadnych artefaktów. W związku z tym nie ma terminu, a pole StudentSubmissions nie istnieje dla CourseWorkMaterials. Nauczyciele mogą używać CourseWorkMaterials do publikowania sugerowanych lektur, programu nauczania lub zasad obowiązujących na zajęciach.

Element Announcements reprezentuje też treści udostępnione grupie uczniów, ale nie ma szczegółów takich jak tytuł i nie można go uporządkować według właściwości Topics, np. CourseWork czy CourseWorkMaterials. Nauczyciele mogą korzystać z tych funkcji, by powiadamiać uczniów o zajęciach.

Tematy

Topics służą do wizualnego porządkowania elementów CourseWork i CourseWorkMaterials w ramach klasy. Można ich używać do grupowania zadań na „opcjonalne” i „wymagane” lub na przykład „moduł 1” i „moduł 2”.

Dodatki do Classroom

Dodatek to interfejs użytkownika i back-end obsługiwany przez dewelopera, który jest zwykle wyświetlany w ramce iframe. Dodatki są wyświetlane jako załączniki w elemencie w strumieniu. Elementem strumienia może być dowolna Announcements, CourseWork lub CourseWorkMaterials. Załączniki dodatków są oznaczone symbolem AddOnAttachment.

Załączniki dodatków mogą być aktywnościami lub treściami.

• Załączniki do aktywności wymagają, aby uczeń wykonał i złożył indywidualne zgłoszenie. Przykłady: quizy, rysunki lub gry. Przesłane aktywności można opcjonalnie ocenić.
• Załączniki z treściami nie wymagają przesłania przez ucznia. Uczeń nie musi oddawać załącznika, a jego ocena nie jest uwzględniana. Przykłady to zdjęcia, artykuły i filmy.

Więcej informacji znajdziesz w przewodnikach dla programistów tworzących dodatki.

Rejestracje

Aplikacje mogą subskrybować powiadomienia o zmianach niektórych danych w Google Classroom. Na przykład gdy lista uczniów jest aktualizowana. Registrations to instrukcja wysyłania tych powiadomień do aplikacji.

Więcej informacji znajdziesz w przewodniku na temat powiadomień push.