Powiadomienia push w interfejsie Classroom API

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

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 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 „zmiana składu na kursie 1234”.
  • Rejestracja to instrukcja dla interfejsu Classroom API, aby dostarczać powiadomienia 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 identyczne żądanie do registrations.create().

Twój 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 cofnie uprawnienia do 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ą web hooka 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 programistó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ń zapobiega problemom ze skalowaniem, jeśli aplikacja staje się popularna.

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

  6. Przed zarejestrowaniem się w usłudze Powiadomienia push musisz przyznać kontu usługi powiadomień 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 taki temat 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 projektu w Konsoli programistów. Jeśli dotyczy to Twojej sytuacji i obawiasz się, że użytkownicy będą wysyłać niechciane powiadomienia dotyczące Twojego tematu Cloud Pub/Sub lub nie znasz nazw tematów Cloud Pub/Sub, których używasz w powiadomieniach push, rozważ zarejestrowanie się, by otrzymywać powiadomienia push z innego projektu w Konsoli programisty.

Rejestrowanie aplikacji na potrzeby 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 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 plików danych o zmianach na liście uczniów oznacza to zakres listy lub (a najlepiej) jego wariant 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 zachowywać uwierzytelnienie OAuth od autoryzowanego użytkownika z wymaganymi zakresami. Jeśli użytkownik odłączy aplikację, powiadomienia zostaną rozłączone. Uwaga: obecnie w tym celu nie można przekazywać uprawnień w całej domenie. 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 projektach z zajęć może to być courses.courseWork lub courses.courseWork.studentSubmissions.
  • Identyfikatory zasobu, który uległ zmianie, na mapie. Ta mapa ma na celu dopasowanie argumentów do metody get odpowiedniego zasobu. PocourseIdcourseIdcourseIduserIdcourses.students.get()courses.teachers.get()ididcourses.courseWork.get()courseWorkIdcourses.courseWork.studentSubmissions.get()

Ten fragment kodu pokazuje przykładowe powiadomienie:

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

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