Nauczyciele, którzy korzystają z Classroom i narzędzi innych firm, mają problem z konfigurowaniem zajęć i list uczniów na wielu platformach. Możesz to zrobić ręcznie, korzystając z przesyłania pliku CSV lub wpisując adresy e-mail pojedynczo. Dzięki interfejsowi Classroom API narzędzia innych firm mogą jednak zmniejszyć obciążenie nauczycieli poprzez integrację z najczęstszym przypadkiem użycia tego interfejsu: importem listy uczniów.
Importowanie listy uczniów umożliwia platformom innych firm pobieranie metadanych zajęć, nauczycieli i uczniów w przypadku poszczególnych zajęć przy użyciu uprawnień nauczyciela lub administratora. Nauczyciele mogą pobierać szczegóły kursów, które prowadzą, natomiast administratorzy mają dostęp do szczegółów wszystkich kursów w całej domenie. Ta elastyczność pozwala deweloperom bezproblemowo importować listy Classroom na swoją platformę zarówno na poziomie poszczególnych nauczycieli, jak i w całej domenie za pomocą danych logowania administratora.
Zanim przejdziemy do szczegółów technicznych integracji importu listy, zapoznajmy się z przykładowym procesem:
W aplikacji innej firmy nauczyciel wybiera opcję importowania Kursu z Classroom.
Aplikacja innej firmy wywołuje metodę
courses.listza pomocą interfejsu Classroom API, który zwraca odpowiedź JSON ze wszystkimi kursami nauczyciela.Na podstawie odpowiedzi w formacie JSON aplikacja zewnętrzna wyświetla tytuły kursów nauczyciela, z których może on wybrać jeden. Aplikacja musi śledzić identyfikatory kursów, aby przejść do następnego kroku.
Po wybraniu identyfikatora kursu aplikacja innej firmy wywołuje metody
students.listiteachers.listoraz wyświetla wszystkie nazwy w swojej witrynie, aby nauczyciele mogli je potwierdzić i zaimportować.Korzystając z adresów e-mail zwróconych w plikach odpowiedzi JSON
students.listiteachers.list, aplikacja innej firmy zaprasza użytkowników do dołączenia do nowo zaimportowanego kursu na swojej platformie.
W przypadku każdej z metod wymienionych w procedurze możesz użyć Eksploratora interfejsu API, aby dokładnie sprawdzić, jak działa każda z nich. Zanim skończysz czytać ten przewodnik, zapoznaj się też z tymi materiałami:
Pierwsze kroki
Zanim zaimportujesz listę uczniów z Classroom, musisz określić, jakie informacje o kursie i użytkownikach musisz pobrać za pomocą interfejsu API. Informacje o tym, jakie metadane dotyczące kursu są dostępne, znajdziesz w dokumentacji referencyjnej. Poniżej znajdziesz listę niektórych wymaganych lub typowych pól:
| Pole | Użyj |
|---|---|
| id | Wymagany w przypadku żądań interfejsu API służących do pobierania danych o uczniach lub nauczycielach |
| nazwa | zalecane ze względu na łatwość obsługi dla użytkownika, np. wyświetlanie w witrynie; |
| ownerId | Wymagane podczas importowania na poziomie domeny, aby prawidłowo zidentyfikować głównego nauczyciela kursu |
Informacje o kursie są pobierane w kroku courses.list w przepływie pracy opisanym powyżej. W tym żądaniu możesz określić pewne parametry żądania. Chociaż żaden z tych parametrów nie jest wymagany, zalecamy użycie tych:
| Parametr | Użyj |
|---|---|
| courseState | Jeśli nie określisz inaczej, interfejs API zwróci kursy we wszystkich 6 stanach. Zalecamy określenie ACTIVE, aby pobrać kursy, których nauczyciele obecnie używają. |
| pageSize | Nauczycielom, którzy importują własne kursy, zalecamy podanie małego rozmiaru strony (mniej niż 10), aby skrócić czas odpowiedzi wywołania interfejsu API. |
| pageToken | Wymagane, jeśli używasz żądań po stronie. |
| teacherId | Zaleca się to, ponieważ administratorzy domen często prowadzą kursy. Jeśli nie podasz tej wartości, żądanie zwróci kursy dla nauczycieli w całej domenie. |
| pola | Zaleca się skrócenie czasu odpowiedzi wywołania interfejsu API. |
Korzystając z identyfikatorów zajęć pobranych wcześniej, Twoja aplikacja może teraz pobrać listę uczniów i nauczycieli współprowadzących te zajęcia. Identyfikator kursu to jedyny wymagany parametr zapytania w przypadku teachers.list i students.list, ale warto też rozważyć podanie parametrów pageSize i fields, aby skrócić czas odpowiedzi na wywołania interfejsu API.
Wszystkie dostępne pola dla zasobów ucznia i nauczyciela znajdziesz w odpowiedniej dokumentacji. Dwa najczęściej używane i zwykle wymagane pola w polu profile to profile.name i profile.emailAddress.
| Pole | Użyj |
|---|---|
| profile.name | zalecane ze względu na łatwość obsługi dla użytkownika, np. wyświetlanie w witrynie; |
| profile.emailAddress | Wymagany w przypadku aplikacji, które mają na celu jednoznaczną identyfikację uczniów. |
Aby pobrać i wykorzystać te szczegóły zajęć lub listy z Classroom, aplikacja musi poprosić użytkowników o autoryzację. Aby wdrożyć ten proces, musisz mieć 3 wymagane uprawnienia:
- 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 list uczniów w Google Classroom (nauczyciele i uczniowie)
- https://www.googleapis.com/auth/classroom.profile.emails
- Przyznawanie uprawnień do odczytu właściwości email nauczycielom i uczniom
Synchronizowanie list obecności z powiadomieniami Pub/Sub
W trakcie roku szkolnego listy uczniów mogą się zmieniać, gdy uczniowie rezygnują z zajęć lub dodają nowe. Dodanie powiadomień Pub/Sub pozwoli Ci zsynchronizować aplikację innej firmy z listą uczniów w Classroom. Aby otrzymywać powiadomienia, skonfiguruj temat Google Cloud Pub/Sub, a następnie zarejestruj go za pomocą interfejsu Classroom API. Ta rejestracja to prośba o wysyłanie danych z danego pliku danych do danego tematu. Ten plik danych będzie zawierać wyzwalacze zdarzeń służące do ponownej synchronizacji z listą uczniów nauczyciela w Classroom.
Korzystanie z powiadomień push wymaga jednego dodatkowego zakresu, który nie musi być przesłany do weryfikacji:
- https://www.googleapis.com/auth/classroom.push-notifications
- Zezwala aplikacji na rejestrowanie wszelkich działań związanych z powiadomieniami push
Więcej informacji o integracji z powiadomieniami push z Classroom znajdziesz w przewodniku Zarządzanie powiadomieniami push.