Powiadomienia push w interfejsie Classroom API

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ę dla pliku danych, do jej rejestracji temat otrzymuje powiadomienia z tego kanału, dopóki nie wygaśnie. Twoja rejestracja jest ważna przez tydzień, ale możesz ją przedłużyć w dowolnym momencie, dopóki nie wygaśnie, identyczne żądanie jak registrations.create().

Twój temat Cloud Pub/Sub otrzymuje powiadomienia tylko o zasobach, które który użytkownik może wyświetlić za pomocą danych logowania podanych podczas tworzenia rejestracji. Dla: na przykład jeśli użytkownik cofnie uprawnienia Twojej aplikacji lub zostanie usunięty powiadomienia są dostarczane przez dłuższy czas.

Rodzaje plików danych

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

• Każda domena ma kanał zmiany w składzie grupy dla domeny, który zawiera powiadomienia o dołączaniu i opuszczaniu zajęć przez uczniów i nauczycieli w tej domenie.
• Każdy kurs ma listę zmian w kanale kursów, który ujawnia powiadomienia o dołączaniu i opuszczaniu zajęć przez uczniów i nauczycieli w danym Google Cloud.
• 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. W Cloud Pub/Sub możesz: otrzymywać powiadomienia na webhooku lub przez odpytywanie punktu końcowego subskrypcji.

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

1. Sprawdź, czy spełniasz wymagania określone w Cloud Pub/Sub Wymagania wstępne
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 na stronie programisty Konsola (najprostsze) za pomocą wiersza poleceń (do prostego użytku programowego) lub za pomocą Cloud Pub/Sub API. Pamiętaj, że Cloud Pub/Sub dopuszcza tylko ograniczoną liczbę tematów, więc użycie jednego tematu możesz otrzymywać wszystkie powiadomienia, dzięki czemu nie wystąpią problemy ze skalowaniem, staje się popularna.

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

6. Na koniec, zanim się zarejestrujesz w powiadomieniach push, musisz przyznać Konto usługi powiadomień push ([email protected]) uprawnienia na dany temat.

UWAGA: jeśli przyznasz kontu usługi Powiadomienia push uprawnienia do publikowania do tematu Cloud Pub/Sub, czyli użytkowników, którzy mogą wysyłać żądania do Twojego Projekt konsolowy będzie mógł określić, że istnieje, i zarejestrować się powiadomienia o niej. 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 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 programisty.

Rejestrowanie aplikacji na potrzeby otrzymywania powiadomień

Gdy masz temat, który konto usługi powiadomień push interfejsu Classroom API możesz publikować powiadomienia, registrations.create() . Metoda registrations.create() sprawdza, czy podana chmura Temat Pub/Sub jest dostępny dla konta usługi powiadomień push. metoda kończy się niepowodzeniem, jeśli konto usługi powiadomień push nie może dotrzeć do tematu; na przykład jeśli temat nie istnieje lub użytkownik nie został opublikowany dotyczące tego tematu.

Autoryzacja

Podobnie jak wszystkie wywołania interfejsu Classroom API, wywołania registrations.create() muszą być autoryzowano za pomocą tokena autoryzacji. Ten token uwierzytelniania musi zawierać zakres powiadomień push (https://www.googleapis.com/auth/classroom.push-notifications) i inne zakresy są wymagane do wyświetlania danych o wysyłanych powiadomieniach.

• W przypadku plików danych o zmianach listy oznacza to zakres listy, a najlepiej, wariant tylko do odczytu (https://www.googleapis.com/auth/classroom.rosters.readonly lub https://www.googleapis.com/auth/classroom.rosters).
• W przypadku plików danych o zmianach zadań na zajęciach oznacza to, że „uczniowie” wersje kursu zakres roboczy 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ć 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ą zakodowane 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 zmienionego zasobu na mapie. Ta mapa ma dopasowywać argumenty do metody get odpowiedniego zasobu. W przypadku powiadomień o zmianach w składzie grupy pola courseId i userId zostaną 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ą zawierać 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ą zawierać pola courseId, courseWorkId i id, które można wysłać bez zmian do courses.courseWork.studentSubmissions.get().

Ten fragment kodu przedstawia przykładowe powiadomienie:

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

Powiadomienia mają też atrybut wiadomości registrationId, który zawiera identyfikatora rejestracji, który wywołał powiadomienie. Można go użyć z registrations.delete() , aby wyrejestrować się z powiadomień.