Powiadomienia push w interfejsie Classroom API

Możesz używać metod w kolekcji Registrations, aby otrzymywać powiadomienia o zmianie danych w Classroom.

W tym artykule znajdziesz ogólny opis oraz podstawowe instrukcje, jak zacząć otrzymywać powiadomienia push.

Omówienie powiadomień push z Classroom

Funkcja powiadomień push w interfejsie Classroom API umożliwia aplikacjom korzystającym z interfejsu Classroom API subskrybowanie powiadomień o zmianie danych w Classroom. Powiadomienia są dostarczane do tematu Cloud Pub/Sub, zwykle w ciągu kilku minut od wprowadzenia zmiany.

Aby otrzymywać powiadomienia push, musisz skonfigurować temat Cloud Pub/Sub i podać jego nazwę podczas tworzenia rejestracji na potrzeby odpowiedniego kanału powiadomień.

Poniżej znajdują się definicje kluczowych pojęć wykorzystywanych w tej dokumentacji:

Miejsce docelowe to miejsce, do którego wysyłane są powiadomienia.
Kanał to typ powiadomień, które może subskrybować aplikacja innej firmy. Na przykład: „Zmiany w składzie na kurs 1234”.
Rejestracja to instrukcja przekazywana interfejsowi Classroom API do dostarczania powiadomień z określonego pliku danych do miejsca docelowego.

Gdy utworzysz rejestrację dla pliku danych, jej temat Cloud Pub/Sub będzie otrzymywać powiadomienia z tego pliku danych do momentu wygaśnięcia rejestracji. Rejestracja jest ważna przez tydzień, ale możesz ją przedłużyć w dowolnym momencie, zanim wygaśnie, przesyłając tę samą prośbę do registrations.create().

Temat Cloud Pub/Sub otrzymuje powiadomienia tylko o zasobach, które możesz wyświetlić za pomocą danych logowania podanych podczas tworzenia rejestracji. Jeśli na przykład użytkownik wycofa uprawnienia aplikacji lub zostanie usunięty z roli nauczyciela, powiadomienia będą dostarczane dłużej.

Rodzaje plików danych

Interfejs Classroom API udostępnia obecnie 3 typy plików danych:

Każda domena ma zmiany w liście uczniów, dzięki czemu pojawiają się powiadomienia, gdy uczniowie i nauczyciele dołączają do zajęć w danej domenie i ją opuszczają.
Każdy kurs ma zmianę listy uczniów w zajęciach, dzięki czemu pojawiają się powiadomienia, gdy uczniowie i nauczyciele dołączają do zajęć na tych zajęciach i je opuszczą.
Każdy plik danych zajęć zawiera zmiany zadań na zajęciach, co daje powiadomienia o utworzeniu lub zmodyfikowaniu w ramach tych zajęć jakichkolwiek zadań lub obiektów przesłanych przez uczniów.

Konfigurowanie tematu Cloud Pub/Sub

Powiadomienia są dostarczane do tematów Cloud Pub/Sub. Z Cloud Pub/Sub możesz otrzymywać powiadomienia przez webhooka lub przez odpytywanie punktu końcowego subskrypcji.

Aby skonfigurować temat Cloud Pub/Sub, wykonaj te czynności:

Sprawdź, czy spełniasz wymagania wstępne Cloud Pub/Sub.
Skonfiguruj klienta Cloud Pub/Sub.
Sprawdź cennik Cloud Pub/Sub i włącz płatności za projekt w Konsoli programisty.
Utwórz temat Cloud Pub/Sub w Konsoli programisty (najprostszą), za pomocą narzędzia wiersza poleceń (do prostego zautomatyzowanego użytku) lub za pomocą interfejsu Cloud Pub/Sub API. Pamiętaj, że Cloud Pub/Sub dopuszcza tylko ograniczoną liczbę tematów, więc jeśli będziesz otrzymywać wszystkie powiadomienia dotyczące jednego tematu, unikniesz problemów ze skalowaniem, jeśli Twoja aplikacja stanie się popularna.
Utwórz subskrypcję w Cloud Pub/Sub, aby poinformować Cloud Pub/Sub o sposobie dostarczania powiadomień.
Zanim zarejestrujesz się w usłudze powiadomień push, musisz przyznać kontu usługi powiadomień push (classroom-notifications@system.gserviceaccount.com) uprawnienia do publikowania w Twoim temacie.

UWAGA: jeśli przyznasz kontu usługi powiadomień push uprawnienia do publikowania w temacie Cloud Pub/Sub, użytkownicy, którzy mogą przesyłać żądania z Twojego projektu w Konsoli programisty, będą mogli ustalić, czy ten projekt istnieje, i zarejestrować się w celu otrzymywania powiadomień. Wiele aplikacji przechowuje identyfikatory klienta OAuth po stronie klienta, dzięki czemu użytkownicy mogą wysyłać żądania z Twojego projektu w Konsoli programisty. Jeśli tak jest w Twoim przypadku i obawiasz się, że użytkownicy będą wysyłać niechciane powiadomienia w Twoim temacie Cloud Pub/Sub lub znają nazwy tematów Cloud Pub/Sub, których używasz na potrzeby powiadomień push, zastanów się nad zarejestrowaniem się w celu otrzymywania powiadomień push z innego projektu w Konsoli programisty.

Rejestrowanie aplikacji, aby otrzymywać powiadomienia

Gdy masz już temat, w którym konto usługi powiadomień push interfejsu Classroom API może publikować, możesz zarejestrować się, aby otrzymywać powiadomienia, korzystając z metody registrations.create(). Metoda registrations.create() sprawdza, czy do podanego tematu Cloud Pub/Sub ma dostęp konto usługi powiadomień push. Ta metoda się nie powiedzie, jeśli konto usługi powiadomień push nie może dotrzeć do tematu – na przykład temat nie istnieje lub nie nadano mu uprawnień do publikowania w tym temacie.

Upoważnienie

Tak jak w przypadku wszystkich wywołań interfejsu API Classroom, wywołania registrations.create() muszą być autoryzowane za pomocą tokena autoryzacji. Token uwierzytelniania musi obejmować zakres powiadomień push (https://www.googleapis.com/auth/classroom.push-notifications) i wszelkie zakresy wymagane do wyświetlania danych o wysyłanych powiadomieniach.

W przypadku plików danych o zmianach w liście uczniów chodzi o zakres list lub (najlepiej) wersję tylko do odczytu (https://www.googleapis.com/auth/classroom.rosters.readonly lub https://www.googleapis.com/auth/classroom.rosters).
W przypadku plików danych zmian dotyczących zadań oznacza to wersje zakresu zadania przeznaczonego dla „uczniów” lub (najlepiej) jego wariant tylko do odczytu (https://www.googleapis.com/auth/classroom.coursework.students.readonly lub https://www.googleapis.com/auth/classroom.coursework.students).

Aby powiadomienia były dostarczane, aplikacja musi zachować uwierzytelnienie OAuth od autoryzowanego użytkownika z wymaganymi zakresami. Jeśli użytkownik odłączy aplikację, powiadomienia przestają być wysyłane. Pamiętaj, że obecnie nie można w tym celu przekazywać uprawnień w całej domenie. Jeśli spróbujesz zarejestrować się w celu otrzymywania powiadomień, korzystając tylko z upoważnienia delegowanego w całej domenie, pojawi się błąd @MissingGrant.

Otrzymywanie powiadomień

Powiadomienia są zakodowane w formacie JSON i zawierają:

Nazwa kolekcji zawierającej zmieniony zasób. W przypadku powiadomień o zmianach w liście jest to courses.students lub courses.teachers. W przypadku zmian dotyczących zadania jest to courses.courseWork lub courses.courseWork.studentSubmissions.
Identyfikatory zmienionego zasobu na mapie. Ta mapa ma na celu dopasowanie argumentów do metody get odpowiedniego zasobu. W przypadku powiadomień o zmianach w liście uczniów pola courseId i userId będą wypełnione i można je wysłać bez zmian do courses.students.get() lub courses.teachers.get(). Podobnie zmiany w kolekcjicourses.courseWork będą zawierać courseId i id, które można wysyłać bez zmian do courses.course1}{/.get()}, a zmiany w kursach id.Subcourse(), a zmiany w kursach:courseIdSubcourse1}, które będą wyświetlane w kursach:courseIdSubcourse.get(). będą z nimi powiązane.courseWorkIdcourses.courseWork.studentSubmissions.get()

Ten fragment kodu ilustruje przykładowe powiadomienie:

{
  "collection": "courses.students",
  "eventType": "CREATED",
  "resourceId": {
    "courseId": "12345",
    "userId": "45678"
  }
}

Powiadomienia mają też atrybut wiadomości registrationId zawierający identyfikator rejestracji, która spowodowała powiadomienie, której można użyć razem z registrations.delete() do wyrejestrowania z powiadomień.