Zasoby 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ą podmioty w Google Classroom, takie jak kurs lub projekt, a usługi pobierają te zasoby i zarządzają nimi. Niektóre z tych podmiotów mają dodatkowe właściwości specyficzne dla interfejsu API, które nie występują w Classroom. Główne typy elementów to:

Jednostka	Element 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 bardziej ogólnym znaczeniu, poza kontekstem ucznia lub nauczyciela.
CourseWork	Projekt na zajęciach.
StudentSubmissions	Praca ucznia w ramach danego projektu, np. 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 aktywność w zadaniu lub materiale, które są zwykle wyświetlane jako osadzona ramka iframe.
Tematy	Wizualne grupowanie projektów i materiałów na zajęciach.
Rejestracje	Instrukcja wysyłania do aplikacji powiadomień o zmianach w danych, np. na liście uczniów na zajęciach.

Większość zasobów ma metody usługi do standardowych operacji, takich jak odczytywanie, aktualizowanie i usuwanie instancji zasobu. Niektóre zasoby mają też niestandardowe metody do innych operacji, np. modyfikowania listy uczniów, którym przypisano konkretne zadanie.

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

Omówienie powiązań między zasobami

• Kurs to podstawowy obiekt danych w Google Classroom.
• Aliasy są używane jako alternatywne identyfikatory dla Courses.
• Zaproszenia służą do zapraszania profili użytkowników do roli nauczycieli lub uczniów w Course, ale użytkowników mogą też dodawać bezpośrednio administratorzy domeny 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 uporządkować w tematy i mogą one zawierać załączniki AddOnAttachments. Uczniowie przesyłają StudentSubmissions w ramach CourseWork.
• Deweloperzy mogą tworzyć rejestracje, aby otrzymywać powiadomienia o zmianach w tych danych.

Google Classroom jest dostępny w domenach, które subskrybują 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. Dzięki temu będziesz mieć kontrolę nad instancją produkcyjną Classroom bez wpływu na rzeczywistych użytkowników.

Kursy i aliasy

Courses reprezentuje klasę, np. „M. Smith's 4th period math" (Matematyka w 4. godzinie lekcyjnej u Smitha) oraz przypisanych nauczycieli, listę 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. Listy uczniów są zarządzane za pomocą zasobów Student, Teacher i Invitation oraz ich metod.

Aliases to alternatywne identyfikatory klasy, które mogą być powiązane z kursem i używane zamiast unikalnego identyfikatora. Każdy alias istnieje w przestrzeni nazw, która ogranicza możliwość tworzenia i wyświetlania aliasów. Obsługiwane są 2 przestrzenie nazw:

• Domena: przestrzeń nazw domeny jest przydatna do tworzenia aliasów, do których wszyscy użytkownicy potrzebują dostępu, ale które nie są specyficzne dla żadnego programu. Na przykład alternatywne wpisy dotyczące kursu, takie jak MATH 127 i COMSCI 127, powinny być tworzone w przestrzeni nazw domeny. Aliasy w przestrzeni nazw domeny mogą być tworzone tylko przez administratorów domeny, ale są widoczne dla wszystkich użytkowników w domenie.
• Projekt dewelopera: przestrzeń nazw projektu dewelopera jest przydatna do zarządzania aliasami powiązanymi z aplikacją. Na przykład aplikacja, która używa alternatywnych identyfikatorów kursów, może utworzyć aliasy, aby mapować swój identyfikator na kursy w Classroom. Utworzone w tej przestrzeni nazw aliasy są powiązane z określoną konsolą interfejsów API Google. Każdy użytkownik aplikacji może tworzyć i wyświetlać aliasy w przestrzeni nazw projektu deweloperskiego tej aplikacji.

Więcej informacji o zarządzaniu metadanymi kursu i aliasami znajdziesz w artykule Zarządzanie kursami.

Listy uczniów i użytkownicy kursu

Students i Teachers to konkretne powiązania między profilem użytkownika a kursem, które określają rolę użytkownika w tym kursie. Oznaczenia ucznia i nauczyciela nie są globalne: użytkownik może być nauczycielem na jednych zajęciach i uczniem na innych. Określenie „uczeń” lub „nauczyciel” oznacza zestaw uprawnień dla konkretnego użytkownika na konkretnym kursie. Kurs może mieć więcej niż jednego nauczyciela lub nie mieć uczniów. Nauczycieli i uczniów można dodawać do kursu lub usuwać z niego w dowolnym momencie.

Uczniowie

Zasób Student reprezentuje użytkownika, który jest uczniem na konkretnych zajęciach.

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

Nauczyciele

Teacher to zasób reprezentujący użytkownika, który prowadzi konkretny kurs.

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

Invitations i powiązane z nimi metody zapewniają wygodny sposób dodawania uczniów i nauczycieli do kursów. Tworzenie zaproszeń umożliwia użytkownikom wybór, czy chcą dołączyć do kursu, zamiast dodawania ich bezpośrednio za pomocą zasobów dla nauczycieli i uczniów.

UserProfiles reprezentuje mapowanie profilu domeny użytkownika zidentyfikowanego przez unikalny identyfikator lub adres e-mail użytkownika zwrócony przez Directory API. Bieżący użytkownik może też odwoływać się do własnego identyfikatora za pomocą skrótu "me".

Usługa UserProfiles może też służyć do zarządzania Guardians i zapraszania ich. Guardians to powiązanie między uczniem a opiekunem. Opiekunowie w Classroom mają dostęp do niektórych informacji o uczniach, np. do ich zadań.

Więcej informacji o zarządzaniu listami znajdziesz w artykule Zarządzanie nauczycielami i uczniami.

Elementy strumienia

Elementy strumienia to opublikowane treści udostępniane uczestnikom kursu. Deweloperzy i nauczyciele mogą tworzyć 3 typy elementów strumienia: Announcement, CourseWork i CourseWorkMaterial.

Nauczyciele tworzą posty Announcements u góry strony Strumień w interfejsie Classroom. Nauczyciele tworzą CourseWork i CourseWorkMaterials, klikając przycisk Utwórz na karcie Zadania. Deweloperzy mogą programowo tworzyć wszystkie typy elementów strumienia za pomocą interfejsu API Classroom.

Elementy strumienia:

• Wszystkie elementy strumienia mogą zawierać materiały dodatkowe, takie jak pliki z Dysku Google, filmy z YouTube, Formularze Google, hiperlinki URL i załączniki dodatków do Classroom.
• Wszystkie elementy strumienia można przypisać do podzbioru uczniów na zajęciach.
• CourseWork może być ocenione lub nie. Nauczyciele mogą w każdej chwili zmienić stan oceniania CourseWork zadania.
• Element strumienia może mieć więcej niż 1 załącznik.
• Element strumienia może zawierać załączniki różnych typów. Na przykład jedenCourseWork projekt może mieć jednocześnie załączniki w postaci plików z Dysku Google, filmów z YouTube i dodatków do Classroom.
• Element strumienia może zawierać załączniki dodatkowe od więcej niż jednego dewelopera.
• Deweloperzy mogą pobierać i modyfikować szczegóły dowolnego zasobu elementu strumienia, który ma jeden z ich załączników dodatku.
• Deweloperzy mogą oddać, odzyskać lub zwrócić zadanie ucznia w przypadku CourseWorkprojektu, który zawiera jeden z załączników dodatku.
• Deweloperzy mogą finalizować oceny tylko w przypadku przesłanych przez uczniów projektów w projektach, które utworzyli.

Skopiowane elementy transmisji

Nauczyciele mogą kopiować elementy strumienia, kopiując zajęcia, ponownie wykorzystując projekt lub publikując element strumienia na wielu zajęciach. Nowe kopie będą miały odrębne identyfikatory, co może być ważne, jeśli tworzysz dodatek do Google Classroom. Zapoznaj się z naszym przewodnikiem po skopiowanych treściach, aby dowiedzieć się, jak dodatek może sobie radzić w takich sytuacjach.

CourseWork i StudentSubmissions

Element CourseWork reprezentuje projekt dla grupy uczniów na kursie. Jest to jedyny typ elementu na stronie Strumień, który może przyjmować zadania przesłane przez uczniów. CourseWork Zasób zawiera szczegóły takie jak opis, termin odesłania, maksymalna ocena i metadane, np. czas utworzenia.

Każdy zasób CourseWork opisuje 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. Składa się z odpowiedzi i dodatkowych metadanych, takich jak stan i przypisana ocena.

Zawartość elementu StudentSubmission zależy od typu odpowiedniego elementu CourseWork i może obejmować:

• arkusze i załączniki przesłane w ramach zadania, w tym ich tytuł, miniaturę i adres URL, a także identyfikatory, których można używać z odpowiednimi interfejsami API, takimi jak Dysk lub YouTube;
• Odpowiedź na pytanie z krótką odpowiedzią lub pytanie jednokrotnego wyboru.

Więcej informacji o zarządzaniu zadaniami i przesłanymi przez uczniów pracami znajdziesz w artykule Zarządzanie zadaniami.

Materiały do zajęć i ogłoszenia

Podobnie jak w przypadku CourseWork, CourseWorkMaterials reprezentuje treści przypisane do grupy uczniów na kursie. Każde źródło zawiera szczegóły, takie jak tytuł i opis, a także materiały dodatkowe. W przeciwieństwie jednak do CourseWorkCourseWorkMaterials nie wymagają od uczniów przesyłania żadnych artefaktów. Dlatego nie ma terminu, a w przypadku CourseWorkMaterials nie ma StudentSubmissions. Nauczyciele mogą używać CourseWorkMaterials do publikowania sugerowanych lektur, programu nauczania lub zasad obowiązujących na zajęciach.

Announcements również reprezentują treści udostępnione grupie uczniów, ale nie mają szczegółów, takich jak tytuł, i nie można ich porządkować według Topics, tak jak CourseWork czy CourseWorkMaterials. Nauczyciele mogą ich używać do ogłaszania przypomnień lub powiadomień dla klasy.

Tematy

Topics służą do wizualnego porządkowania CourseWork i CourseWorkMaterials w ramach zajęć. Możesz ich używać np. do grupowania zadań na „opcjonalne” i „wymagane” lub „moduł 1” i „moduł 2”.

Dodatki do Classroom

Dodatek to interfejs i backend obsługiwane przez dewelopera, które są zwykle wyświetlane w ramce iframe. Dodatki są wyświetlane jako załączniki w elemencie strumienia. Element transmisji może być dowolnym 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ą od ucznia ukończenia i przesłania indywidualnego projektu. Mogą to być np. quizy, losowania lub gry. Przesłane zadanie może zostać ocenione.
• Załączniki do treści nie wymagają przesłania przez ucznia. Uczeń nie musi oddawać załącznika i nie jest on oceniany. Przykłady to zdjęcia, artykuły i filmy.

Więcej informacji znajdziesz w przewodnikach dotyczących tworzenia dodatków.

Rejestracje

Aplikacje mogą subskrybować powiadomienia o zmianach określonych danych w Google Classroom. Na przykład gdy zaktualizowana zostanie lista uczestników kursu. Registrations to instrukcja wysyłania tych powiadomień do Twojej aplikacji.

Więcej informacji znajdziesz w przewodniku po powiadomieniach push.