Nauczyciele, którzy korzystają zarówno z Classroom, jak i narzędzi innych firm, mają problem z konfigurowaniem zajęć i list uczniów na wielu platformach. Możesz to zrobić ręcznie, przesyłając pliki CSV lub wpisując adresy e-mail pojedynczo. Dzięki interfejsowi Classroom API narzędzia innych firm mogą jednak zmniejszyć obciążenie nauczycieli, integrując się z najczęstszym zastosowaniem interfejsu API: importowaniem listy uczniów.
Importowanie list uczniów umożliwia platformom innych firm pobieranie metadanych zajęć, nauczycieli i uczniów w przypadku poszczególnych zajęć z uprawnieniami nauczyciela lub administratora. Nauczyciele mogą pobierać szczegółowe informacje o kursach, które prowadzą, a administratorzy mają dostęp do szczegółów wszystkich kursów w całej domenie. Dzięki temu deweloperzy mogą bezproblemowo wprowadzać listy uczniów z Classroom na swoją platformę na poziomie poszczególnych nauczycieli lub w całej domenie, używając danych logowania administratora.
Zanim przejdziemy do szczegółów technicznych integracji importu list, przyjrzyjmy się przykładowemu przepływowi pracy:
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, aby mógł on wybrać jeden z nich. Aby przejść do następnego kroku, aplikacja musi śledzić identyfikatory kursów.
Po wybraniu identyfikatora kursu aplikacja innej firmy wywołuje metody
students.listiteachers.listi wyświetla wszystkie nazwy w swojej witrynie, aby nauczyciele mogli potwierdzić import.Korzystając z adresów e-mail zwróconych w plikach JSON odpowiedzi
students.listiteachers.list, aplikacja innej firmy zaprasza użytkowników do dołączenia do nowo zaimportowanego kursu na swojej platformie.
W przypadku każdej metody wymienionej w procedurze możesz użyć Eksploratora interfejsu API, aby sprawdzić, jak dokładnie działa każda z nich. Zanim skończysz czytać ten przewodnik, zapoznaj się też z tymi materiałami:
Pierwsze kroki
Zanim wdrożysz szczegóły importowania listy uczniów w Classroom, musisz określić, jakie informacje o kursie i użytkownikach chcesz pobrać za pomocą interfejsu API. Informacje o dostępnych metadanych kursu znajdziesz w dokumentacji. Poniżej znajdziesz podsumowanie niektórych wymaganych lub często używanych pól:
| Pole | Użyj |
|---|---|
| id | Wymagane w przypadku żądań API pobierających informacje o uczniach lub nauczycielach |
| nazwa | Zalecane ze względu na łatwość użycia przez użytkownika, np.wyświetlanie w witrynie. |
| ownerId | Wymagane podczas importowania na poziomie całej domeny, aby prawidłowo zidentyfikować głównego nauczyciela kursu. |
Informacje o kursie są pobierane na etapie courses.list w przepływie pracy powyżej. W tym żądaniu możesz określić niektóre parametry. Żaden z nich nie jest wymagany w przypadku tej metody, ale zalecamy użycie tych parametrów:
| Parametr | Użyj |
|---|---|
| courseState | Jeśli nie zostanie określony, interfejs API zwróci kursy we wszystkich 6 stanach kursu. Zalecamy określenie ACTIVE, aby pobrać kursy, z których nauczyciele obecnie korzystają. |
| pageSize | Nauczycielom, którzy importują własne kursy, zalecamy określenie małej wartości parametru pageSize (poniżej 10), aby skrócić czas odpowiedzi wywołania interfejsu API. |
| pageToken | Wymagane, jeśli używasz żądań podzielonych na strony. |
| teacherId | Zalecane, ponieważ administratorzy domeny często prowadzą kursy. Jeśli nie zostanie określony, żądanie zwróci kursy dla nauczycieli w całej domenie. |
| pola | Zalecane, aby skrócić czas odpowiedzi wywołania interfejsu API. |
Korzystając z identyfikatorów kursów pobranych wcześniej, aplikacja może teraz pobrać listę uczniów i nauczycieli współprowadzących dla danego kursu lub kursów. Ten identyfikator kursu jest jedynym wymaganym parametrem zapytania w przypadku teachers.list i students.list, ale możesz też rozważyć określenie parametrów pageSize i fields, aby skrócić czas odpowiedzi wywołań interfejsu API.
Wszystkie dostępne pola zasobów dla uczniów i nauczycieli znajdziesz w odpowiedniej dokumentacji. 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 ze względu na łatwość użycia przez użytkownika, np.wyświetlanie w witrynie. |
| profile.emailAddress | Wymagane w przypadku aplikacji, które chcą jednoznacznie identyfikować uczniów |
Aby pobrać i wykorzystać dowolne z tych szczegółów kursu lub listy uczniów z Classroom, aplikacja musi poprosić użytkowników o autoryzację. Aby wdrożyć ten proces, musisz mieć 3 wymagane 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 list uczniów w Google Classroom (nauczyciele i uczniowie).
- https://www.googleapis.com/auth/classroom.profile.emails
- Zapewnia dostęp do odczytu właściwości email nauczycieli i uczniów.
Synchronizowanie list z powiadomieniami Pub/Sub
W trakcie roku szkolnego listy uczniów mogą się zmieniać, ponieważ uczniowie mogą rezygnować z zajęć lub dołączać do nich. Dodanie powiadomień Pub/Sub umożliwi synchronizację aplikacji innej firmy z listami uczestników zajęć w Classroom. Aby otrzymywać powiadomienia, skonfiguruj temat Google Cloud Pub/Sub, a następnie zarejestruj go w interfejsie Classroom API. Rejestracja jest prośbą o wysyłanie przez Classroom danych z podanego pliku do podanego tematu. Ten plik danych będzie zawierać wyzwalacze zdarzeń do ponownej synchronizacji z listą uczniów nauczyciela w Classroom.
Korzystanie z powiadomień push wymaga dodatkowego zakresu, którego nie trzeba przesyłać do weryfikacji:
- https://www.googleapis.com/auth/classroom.push-notifications
- Zezwala aplikacji na rejestrowanie dowolnej aktywności związanej z powiadomieniami push
Więcej informacji o integracji z powiadomieniami push w Classroom znajdziesz w naszym przewodniku po zarządzaniu powiadomieniami push.