Dodatki do Google Classroom są teraz ogólnie dostępne dla programistów. Więcej informacji znajdziesz w dokumentacji dodatków.

Ta strona została przetłumaczona przez Cloud Translation API.

Powiadomienia push w interfejsie Classroom API

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

Ten artykuł zawiera ogólny opis oraz proste instrukcje, jak zacząć otrzymywać powiadomienia push.

Omówienie powiadomień push w 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 pliku danych powiadomień.

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

Miejsce docelowe to miejsce, do którego są wysyłane powiadomienia.
Kanał to rodzaj powiadomień, które aplikacja innej firmy może subskrybować. Na przykład „zmiany na liście uczestników kursu 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 powiązany z tą rejestracją będzie otrzymywać powiadomienia z tego pliku danych do momentu wygaśnięcia rejestracji. Rejestracja trwa tydzień, ale możesz ją przedłużyć w dowolnym momencie przed wygaśnięciem, wysyłając identyczną prośbę do registrations.create().

Temat Cloud Pub/Sub otrzymuje tylko powiadomienia 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 aplikacji lub zostanie usunięty z roli nauczyciela, powiadomienia nie będą już dostarczane.

Rodzaje plików danych

Interfejs Classroom API oferuje 3 rodzaje kanałów:

Każda domena ma kanał zmian w spisie uczniów w domenie, który udostępnia powiadomienia o tym, kiedy uczniowie i nauczyciele dołączają do zajęć w tej domenie i kiedy je opuszczają.
Każdy kurs ma kanał zmian na liście uczniów, który wyświetla powiadomienia o tym, kiedy uczniowie i nauczyciele dołączają do kursów i je opuszczają.
Każde zajęcia mają kanał zmian w zadaniach na zajęciach, który wyświetla powiadomienia o utworzeniu lub zmodyfikowaniu na tych zajęciach dowolnych zadań lub przesłanych przez uczniów projektó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ą wywołania zwrotnego lub przez sondowanie punktu końcowego subskrypcji.

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

Upewnij się, że spełniasz wymagania wstępne dotyczące Cloud Pub/Sub.
Skonfiguruj klienta Cloud Pub/Sub.
Zapoznaj się z cennikiem Cloud Pub/Sub i włącz płatności za projekt w Konsoli dewelopera.
Utwórz temat Cloud Pub/Sub w konsoli dewelopera (najłatwiej), za pomocą narzędzia wiersza poleceń (do prostego użycia programowego) lub za pomocą interfejsu Cloud Pub/Sub API. Pamiętaj, że Cloud Pub/Sub umożliwia tylko ograniczoną liczbę tematów, więc używanie jednego tematu do odbierania wszystkich powiadomień zapewnia, że nie napotkasz problemów ze skalowaniem, jeśli Twoja aplikacja stanie się popularna.
Utwórz subskrypcję w Cloud Pub/Sub, aby określić sposób dostarczania powiadomień przez Cloud Pub/Sub.
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ą wysyłać żądania z Twojego projektu w Konsoli dewelopera, będą mogli stwierdzić, że ten temat istnieje, i zarejestrować się w celu otrzymywania powiadomień. Wiele aplikacji przechowuje identyfikatory klientów OAuth po stronie klienta, więc użytkownicy mogą wysyłać żądania z projektu w Konsoli deweloperów. Jeśli dotyczy Cię ta sytuacja i obawiasz się, że użytkownicy będą wysyłać niechciane powiadomienia do Twojego tematu Cloud Pub/Sub lub poznają nazwy tematów Cloud Pub/Sub, których używasz do powiadomień push, rozważ zarejestrowanie się w celu otrzymywania powiadomień push z innego projektu w Konsoli dewelopera.

Rejestrowanie aplikacji w celu otrzymywania powiadomień

Gdy masz już temat, w którym konto usługi powiadomień push interfejsu Classroom API może publikować informacje, możesz zarejestrować się, aby otrzymywać powiadomienia, korzystając z metody registrations.create(). Metoda registrations.create() sprawdza, czy konto usługi powiadomień push może uzyskać dostęp do podanego tematu Cloud Pub/Sub. Metoda nie działa, jeśli konto usługi powiadomień push nie może uzyskać dostępu do tematu, np. jeśli temat nie istnieje lub nie przyznano mu 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 uwierzytelniania musi zawierać zakres powiadomień push (https://www.googleapis.com/auth/classroom.push-notifications) oraz wszystkie zakresy wymagane do wyświetlania danych, na podstawie których wysyłane są powiadomienia.

W przypadku plików danych ze zmianami w składzie oznacza to zakres Składy lub (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 „uczniowskie” zakresu zadań 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ć przyznane przez autoryzowanego użytkownika uprawnienia OAuth z wymaganymi zakresami. Jeśli użytkownik odłączy aplikację, powiadomienia przestaną być wysyłane. Pamiętaj, że obecnie przekazywanie uprawnień w całej domenie nie jest obsługiwane w tym celu. Jeśli spróbujesz zarejestrować się w celu otrzymywania powiadomień, korzystając tylko z delegowanych uprawnień w całej domenie, 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 harmonogramie jest to courses.students lub courses.teachers. W przypadku zmian w zadaniach jest to courses.courseWork lub courses.courseWork.studentSubmissions.
Identyfikatory zmienionego zasobu w mapie. Ta mapa jest przeznaczona do dopasowywania argumentów do metody get odpowiedniego zasobu. W przypadku powiadomień o zmianach na 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 kolekcji courses.courseWork będą miały pola courseId i id, które można wysłać bez zmian do courses.courseWork.get(), a zmiany w kolekcji courses.courseWork.studentSubmissions będą miały pola courseId, courseWorkId i id, które można wysłać bez zmian do courses.courseWork.studentSubmissions.get().

Poniższy fragment kodu przedstawia przykładowe powiadomienie:

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

Powiadomienia mają też atrybut registrationId message, który zawiera identyfikator rejestracji, która spowodowała wysłanie powiadomienia. Można go użyć z registrations.delete() do wyrejestrowania się z powiadomień.