Nauczyciele, którzy korzystają zarówno z Classroom, jak i narzędzi innych firm, napotykają wyzwanie polegające na skonfigurowaniu zajęć i list uczniów na wielu platformach. Możesz to zrobić ręcznie, przesyłając plik CSV lub wpisując adresy e-mail pojedynczo. Interfejs Classroom API pozwala jednak zmniejszyć obciążenie nauczyciela dzięki integracji z najczęstszym przypadkiem użycia tego interfejsu: importowaniem list uczniów.
Importowanie list uczniów pozwala platformom firm zewnętrznych pobierać metadane poszczególnych zajęć oraz informacje o nauczycielach i uczniach w poszczególnych zajęciach z uprawnieniami nauczyciela lub administratora. Nauczyciele mogą uzyskać szczegółowe informacje o kursach, na których uczą, a administratorzy – do szczegółów wszystkich zajęć w całej domenie. Dzięki temu deweloperzy mogą bezproblemowo dodawać listy uczniów w Classroom zarówno na poziomie pojedynczego nauczyciela, jak i w całej domenie przy użyciu danych logowania administratora.
Zanim przejdziemy do szczegółów technicznych dotyczących integracji importowania listy uczniów, przyjrzyjmy się najpierw przykładowi przepływu pracy:
W aplikacji innej firmy nauczyciel wybiera opcję zaimportowania kursu Classroom.
Aplikacja innej firmy wywołuje metodę
courses.listprzy użyciu interfejsu Classroom API, który zwraca odpowiedź w formacie JSON ze wszystkimi kursami nauczyciela.Aplikacja innej firmy na podstawie odpowiedzi json wyświetla tytuły kursów nauczyciela, aby umożliwić mu wybranie odpowiedniego tytułu. Aby przejść do następnego kroku, aplikacja będzie musiała zapisywać identyfikatory zajęć.
Za pomocą wybranego identyfikatora zajęć aplikacja innej firmy wywołuje metody
students.listiteachers.listoraz wyświetla wszystkie nazwy w swojej witrynie, aby nauczyciele mogli je potwierdzić do zaimportowania.Aplikacja innej firmy wykorzystuje adresy e-mail zwrócone w plikach JSON z odpowiedziami
students.listiteachers.list, aby zaprosić użytkowników do dołączenia do nowo zaimportowanego kursu na ich platformie.
W przypadku każdej metody wymienionej w przepływie pracy możesz za pomocą narzędzia API Explorer sprawdzić dokładnie, jak działają poszczególne metody. Przed przeczytaniem tego przewodnika warto też zapoznać się z tymi wskazówkami:
Pierwsze kroki
Zanim zaimplementujesz szczegóły importowania listy uczniów w Classroom, musisz określić, które informacje o zajęciach i użytkownikach chcesz pobierać za pomocą interfejsu API. Informacje o dostępnych metadanych kursów znajdziesz w dokumentacji referencyjnej. Poniżej znajdziesz podsumowanie niektórych wymaganych lub typowych pól:
| Pole | Użyj |
|---|---|
| id | Wymagane w przypadku żądań do interfejsu API pobierających uczniów lub nauczycieli |
| nazwa | Zalecane, aby były łatwe w użyciu dla użytkowników, tzn. aby były wyświetlane w witrynie |
| ownerId | Element wymagany w przypadku importowania danych w całej domenie w celu prawidłowej identyfikacji głównego nauczyciela kursu |
Informacje o zajęciach są pobierane w kroku courses.list powyżej. W tym żądaniu możesz podać określone parametry żądania. Choć żaden z nich nie jest wymagany w przypadku tej metody, niektóre z zalecanych parametrów to:
| Parametr | Użyj |
|---|---|
| courseState | Jeśli pozostawisz nieokreślone, interfejs API zwróci kursy ze wszystkich 6 stanów kursów. Zalecamy użycie wartości ACTIVE w celu pobrania zajęć, których obecnie używają nauczyciele. |
| pageSize | W przypadku nauczycieli, którzy importują własne kursy, zalecamy określenie małego (poniżej 10) parametru pageSize, aby skrócić czas odpowiedzi na wywołanie interfejsu API. |
| pageToken | Wymagane, jeśli używasz żądań z podziałem na strony. |
| teacherId | Zalecane, ponieważ administratorzy domen często prowadzą zajęcia. Jeśli nie określisz, żądanie zwróci kursy dla nauczycieli z całej domeny. |
| pola | Zalecane, aby skrócić czas odpowiedzi na wywołanie interfejsu API. |
Korzystając z pobranych wcześniej identyfikatorów zajęć, aplikacja może teraz pobierać listę uczniów i nauczycieli współprowadzących te zajęcia lub kursy. Ten identyfikator kursu jest jedynym wymaganym parametrem zapytania w przypadku teachers.list i students.list, ale możesz też podać parametry pageSize i fields, aby skrócić czas odpowiedzi na wywołania interfejsu API.
Wszystkie dostępne pola dotyczące zasobów uczniów i nauczycieli znajdziesz w odpowiednich dokumentach. Dwa najczęściej używane i zwykle wymagane pola znajdują się w polu profile: profile.name i profile.emailAddress.
| Pole | Użyj |
|---|---|
| profile.name | Zalecane, aby były łatwe w użyciu dla użytkowników, tzn. aby były wyświetlane w witrynie |
| profile.emailAddress | Wymagane w przypadku aplikacji, które mają jednoznacznie identyfikować uczniów |
Aby pobrać z Classroom te informacje o zajęciach lub liście uczniów i ich używać, Twoja aplikacja będzie musiała poprosić użytkowników o autoryzację. Do wdrożenia tego przepływu pracy potrzebne są 3 (3) zakresy:
- https://www.googleapis.com/auth/classroom.courses.readonly
- zapewnia dostęp tylko do odczytu do kursów w Google Classroom.
- https://www.googleapis.com/auth/classroom.rosters.readonly
- Zapewnia dostęp tylko do odczytu do funkcji kursów w Google Classroom (dla nauczycieli i uczniów).
- https://www.googleapis.com/auth/classroom.profile.emails
- Przyznaje nauczycielom i uczniom uprawnienia do odczytu właściwości email.
Synchronizacja list z powiadomieniami Pub/Sub
Wraz z powrotem roku szkolnego listy uczniów mogą się zmieniać, w miarę jak uczniowie spadają lub dodają zajęcia. Dodanie powiadomień Pub/Sub umożliwi synchronizację aplikacji innych firm z programami Classroom. Aby otrzymywać powiadomienia, musisz skonfigurować temat Google Cloud Pub/Sub, a następnie zarejestrować go za pomocą interfejsu Classroom API. Rejestracja to żądanie przez Classroom wysłania danych z przesłanego pliku danych do danego tematu. Ten plik danych będzie wywoływać zdarzenia podczas ponownej synchronizacji z listą uczniów w Classroom.
Stosowanie powiadomień push będzie wymagało 1 dodatkowego zakresu, który nie musi być przesyłany do weryfikacji:
- https://www.googleapis.com/auth/classroom.push-notifications
- Zezwala aplikacji na rejestrowanie aktywności związanej z powiadomieniami push
Więcej informacji o integracji z powiadomieniami push Classroom znajdziesz w naszym przewodniku po zarządzaniu powiadomieniami push.