Powiadomienia push w interfejsie Classroom API

Aby otrzymywać powiadomienia o zmianach danych w Classroom, możesz użyć metod z kolekcji Registrations.

Z tego artykułu dowiesz się, jak zacząć otrzymywać powiadomienia push.

Omówienie powiadomień push z Classroom

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

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

Poniżej znajdziesz definicje kluczowych pojęć używanych w tej dokumentacji:

  • Adres docelowy to miejsce, do którego wysyłane są powiadomienia.
  • Kanał to rodzaj powiadomień, do których aplikacja innej firmy może się zasubskrybować. Na przykład „zmiany w składzie w kursie 1234”.
  • Rejestracja to instrukcja wysyłania powiadomień z określonego pliku danych do miejsca docelowego.

Gdy utworzysz rejestrację pliku danych, temat Cloud Pub/Sub tej rejestracji będzie otrzymywać powiadomienia z tego pliku danych do czasu jego wygaśnięcia. Rejestracja trwa tydzień, ale możesz ją przedłużyć w dowolnym momencie przed jej wygaśnięciem, przesyłając identyczną prośbę do registrations.create().

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

Rodzaje plików danych

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

  • Każda domena ma kanał zmiany w składzie w domenie, który zawiera powiadomienia o dołączaniu i opuszczaniu zajęć przez uczniów i nauczycieli w tej domenie.
  • Każde zajęcia mają kanał zmiany listy uczniów, na którym pojawiają się powiadomienia o dołączaniu i opuszczaniu zajęć przez uczniów i nauczycieli.
  • Każdy kurs ma kanał zmiany zadań w kursie, na którym wyświetlają się powiadomienia o utworzeniu lub zmodyfikowaniu zadań w danym kursie lub przesłanych przez uczniów obiektów.

Konfigurowanie tematu Cloud Pub/Sub

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

Aby skonfigurować temat Cloud Pub/Sub:

  1. Sprawdź, czy spełniasz wymagania wstępne Cloud Pub/Sub.
  2. Skonfiguruj klienta Cloud Pub/Sub.
  3. Zapoznaj się z cennikiem usługi Cloud Pub/Sub i włącz płatności w projekcie w konsoli dewelopera.

  4. Utwórz temat Cloud Pub/Sub w konsoli dla deweloperów (najłatwiej), za pomocą narzędzia wiersza poleceń (do prostego użycia programistycznego) lub za pomocą interfejsu Cloud Pub/Sub API. Pamiętaj, że Cloud Pub/Sub obsługuje tylko ograniczoną liczbę tematów, więc używanie jednego tematu do odbierania wszystkich powiadomień zapewni, że nie napotkasz problemów ze skalowaniem, jeśli Twoja aplikacja stanie się popularna.

  5. Utwórz subskrypcję w Cloud Pub/Sub, aby określić, jak Cloud Pub/Sub ma dostarczać powiadomienia.

  6. Na koniec, zanim zarejestrujesz się w przypadku powiadomień push, musisz przyznać konto usługi Powiadomienia push (classroom-notifications@system.gserviceaccount.com) uprawnienia do publikowania w Twoim temacie.

UWAGA: jeśli przyznasz konto usługi Push Notifications uprawnienia do publikowania w temacie Cloud Pub/Sub, użytkownicy, którzy mogą wysyłać żądania z Twojego projektu w Konsoli deweloperów, będą mogli sprawdzić, czy istnieje, i zarejestrować się na otrzymywanie powiadomień. Wiele aplikacji przechowuje identyfikatory klienta OAuth po stronie klienta, więc użytkownicy końcowi mogą wysyłać żądania z Twojego projektu w Konsoli programistów. Jeśli dotyczy Cię to i martwisz się, że użytkownicy końcowi wysyłają niechciane powiadomienia do Twojego tematu Cloud Pub/Sub lub znają nazwy tematów Cloud Pub/Sub, których używasz do powiadomień push, rozważ zarejestrowanie powiadomień push z innego projektu w Konsoli dla deweloperów.

Rejestrowanie aplikacji na potrzeby otrzymywania powiadomień

Gdy masz temat, na który konto usługi Classroom API może publikować powiadomienia push, możesz zarejestrować się na powiadomienia, używając metody registrations.create(). Metoda registrations.create() sprawdza, czy można uzyskać dostęp do podanego tematu Cloud Pub/Sub z poziomu konta usługi powiadomień push. Ta metoda zawiedzie, jeśli konto usługi powiadomień push nie może uzyskać dostępu do tematu, np. jeśli temat nie istnieje lub nie masz uprawnień do publikowania w tym temacie.

Autoryzacja

Podobnie jak wszystkie wywołania interfejsu Classroom API, wywołania interfejsu registrations.create() muszą być autoryzowane za pomocą tokena autoryzacji. Ten token uwierzytelniający musi obejmować zakres powiadomień push (https://www.googleapis.com/auth/classroom.push-notifications) oraz wszystkie zakresy wymagane do wyświetlania danych o tym, które powiadomienia są wysyłane.

  • W przypadku kanałów zmian w składzie oznacza to zakres „Składy” lub (najlepiej) jego wersję tylko do odczytu (https://www.googleapis.com/auth/classroom.rosters.readonly lub https://www.googleapis.com/auth/classroom.rosters).
  • W przypadku kanałów zmian zadań oznacza to wersje „uczniów” zakresu zadań lub (najlepiej) ich wersje 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ć uprawnienia OAuth od autoryzowanego użytkownika z wymaganymi zakresami. Jeśli użytkownik odłączy aplikację, powiadomienia przestaną być wysyłane. Pamiętaj, że obecnie delegowanie uprawnień w całej domenie nie jest obsługiwane w tym celu. Jeśli spróbujesz zarejestrować się na otrzymywanie powiadomień, korzystając tylko z upoważnienia delegowanego na poziomie domeny, pojawi się błąd @MissingGrant.

Otrzymywanie powiadomień

Powiadomienia są kodowane w formacie JSON i zawierają:

  • Nazwa kolekcji zawierającej zmieniony zasób. W przypadku powiadomień o zmianach w składzie jest to wartość courses.students lub courses.teachers. W przypadku zmian w zadaniach z zajęć może to być courses.courseWork lub courses.courseWork.studentSubmissions.
  • Identyfikatory zasobu, który uległ zmianie, na mapie. Ta mapa ma dopasowywać argumenty do metody get odpowiedniego zasobu. W przypadku powiadomień o zmianach w składzie grupy zostaną wypełnione pola courseId i userId, które można wysłać bez zmian do funkcji courses.students.get() lub courses.teachers.get(). Podobnie zmiany w kolekcji courses.courseWork będą zawierać pola courseId i id, które można wysłać bez zmian do funkcji courses.courseWork.get(), a zmiany w kolekcji courses.courseWork.studentSubmissions będą zawierać pola courseId, courseWorkId i id, które można wysłać bez zmian do funkcji courses.courseWork.studentSubmissions.get().

Ten fragment kodu pokazuje przykładowe powiadomienie:

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

Powiadomienia mają też atrybuty wiadomości registrationId, które zawierają identyfikator rejestracji, która spowodowała wysłanie powiadomienia. Można go użyć, aby registrations.delete()rezygnować z powiadomień.