Classroom API의 푸시 알림

Registrations 컬렉션의 메서드를 사용하여 클래스룸에서 데이터가 변경될 때 알림을 받을 수 있습니다.

이 도움말에서는 푸시 알림 수신을 시작하는 방법에 관한 간단한 안내와 함께 개념적 개요를 제공합니다.

클래스룸 푸시 알림 개요

Classroom API 푸시 알림 기능을 사용하면 Classroom API를 사용하는 애플리케이션이 클래스룸의 데이터가 변경될 때 알림을 구독할 수 있습니다. 알림은 일반적으로 변경 후 몇 분 이내에 Cloud Pub/Sub 주제에 전송됩니다.

푸시 알림을 받으려면 Cloud Pub/Sub 주제를 설정하고 적절한 알림 피드의 등록을 만들 때 해당 주제의 이름을 제공해야 합니다.

다음은 이 문서에서 사용되는 주요 개념의 정의입니다.

  • 대상은 알림이 전송되는 위치입니다.
  • 피드는 서드 파티 애플리케이션에서 구독할 수 있는 알림 유형입니다. 예를 들어 '1234 과정의 명단 변경'과 같이 입력합니다.
  • 등록은 특정 피드에서 대상으로 알림을 전송하도록 클래스룸 API에 지시하는 것입니다.

피드 등록을 만들면 등록의 Cloud Pub/Sub 주제에 만료될 때까지 해당 피드의 알림이 수신됩니다. 등록은 일주일 동안 지속되지만 만료되기 전에 언제든지 registrations.create()에 동일한 요청을 보내 연장할 수 있습니다.

Cloud Pub/Sub 주제는 등록을 만들 때 제공한 사용자 인증 정보로 볼 수 있는 리소스에 대한 알림만 수신합니다. 예를 들어 사용자가 애플리케이션에서 권한을 취소하거나 교사로서 삭제된 경우 알림이 더 오래 전송됩니다.

피드의 유형

Classroom API는 현재 세 가지 유형의 피드를 제공합니다.

  • 각 도메인에는 도메인 명단 변경 피드가 있으며, 이 피드는 학생과 교사가 해당 도메인의 강의에 참여하거나 탈퇴할 때 알림을 표시합니다.
  • 각 과정에는 과정 피드의 출석부 변경사항이 있어서 학생과 교사가 해당 과정에 참여하거나 나갈 때 알림이 표시됩니다.
  • 각 과정에는 과정 활동 변경사항 피드가 있으며, 이 피드는 해당 과정에서 과정 활동 또는 학생 제출물 객체가 생성되거나 수정될 때 알림을 표시합니다.

Cloud Pub/Sub 주제 설정

알림은 Cloud Pub/Sub 주제에 전송됩니다. Cloud Pub/Sub에서는 웹훅을 통해 또는 구독 엔드포인트를 폴링하여 알림을 수신할 수 있습니다.

Cloud Pub/Sub 주제를 설정하려면 다음을 실행해야 합니다.

  1. Cloud Pub/Sub 기본 요건을 충족하는지 확인합니다.
  2. Cloud Pub/Sub 클라이언트 설정
  3. Cloud Pub/Sub 요금을 검토하고 Developer Console 프로젝트에 결제를 사용 설정합니다.

  4. 개발자 콘솔(가장 쉬움), 명령줄 도구(간단한 프로그래매틱 사용) 또는 Cloud Pub/Sub API를 사용하여 Cloud Pub/Sub 주제를 만듭니다. Cloud Pub/Sub는 제한된 수의 주제만 허용하므로 하나의 주제를 사용하여 모든 알림을 수신하면 애플리케이션이 인기를 얻더라도 확장 문제가 발생하지 않습니다.

  5. Cloud Pub/Sub에서 구독을 만들어 Cloud Pub/Sub에 알림을 전송하는 방법을 알려줍니다.

  6. 마지막으로 푸시 알림을 등록하기 전에 주제에 게시할 수 있는 푸시 알림 서비스 계정(classroom-notifications@system.gserviceaccount.com) 권한을 부여해야 합니다.

참고: 푸시 알림 서비스 계정에 Cloud Pub/Sub 주제에 게시할 권한을 부여하면 Developer Console 프로젝트에서 요청할 수 있는 사용자가 주제가 있는지 확인하고 주제에 알림을 등록할 수 있습니다. 많은 애플리케이션은 클라이언트 측에 OAuth 클라이언트 ID를 저장하므로 최종 사용자가 Developer Console 프로젝트에서 요청할 수 있습니다. 이 경우 최종 사용자가 Cloud Pub/Sub 주제에 원치 않는 알림을 보내거나 푸시 알림에 사용하는 Cloud Pub/Sub 주제의 이름을 알 수 있다는 점이 우려된다면 다른 Developer Console 프로젝트에서 푸시 알림을 등록하는 것이 좋습니다.

알림을 위해 애플리케이션 등록

Classroom API 푸시 알림 서비스 계정이 게시할 수 있는 주제가 있으면 registrations.create() 메서드를 사용하여 알림을 등록할 수 있습니다. registrations.create() 메서드는 제공된 Cloud Pub/Sub 주제에 푸시 알림 서비스 계정으로 연결할 수 있는지 확인합니다. 푸시 알림 서비스 계정이 주제에 도달할 수 없는 경우 메서드가 실패합니다. 예를 들어 주제가 없거나 주제에 대한 게시 권한을 부여하지 않은 경우입니다.

승인

모든 클래스룸 API 호출과 마찬가지로 registrations.create() 호출은 승인 토큰으로 승인되어야 합니다. 이 인증 토큰에는 푸시 알림 범위(https://www.googleapis.com/auth/classroom.push-notifications)와 전송 중인 알림에 관한 데이터를 보려면 필요한 모든 범위가 포함되어야 합니다.

  • 명단 변경 피드의 경우 명단 범위 또는 (가급적) 읽기 전용 변형(https://www.googleapis.com/auth/classroom.rosters.readonly 또는 https://www.googleapis.com/auth/classroom.rosters)을 의미합니다.
  • 과정 작업 변경 피드의 경우 과정 작업 범위의 '학생' 버전 또는 (이상적으로는) 읽기 전용 변형(https://www.googleapis.com/auth/classroom.coursework.students.readonly 또는 https://www.googleapis.com/auth/classroom.coursework.students)을 의미합니다.

알림이 전송되려면 애플리케이션에서 필요한 범위가 있는 승인된 사용자의 OAuth 권한을 유지해야 합니다. 사용자가 애플리케이션 연결을 해제하면 알림이 중단됩니다. 현재 이 목적으로 도메인 전체 권한 위임은 지원되지 않습니다. 도메인 전체 위임된 권한만 사용하여 알림을 등록하려고 하면 @MissingGrant 오류가 발생합니다.

알림 수신

알림은 JSON으로 인코딩되며 다음을 포함합니다.

  • 변경된 리소스가 포함된 컬렉션의 이름입니다. 명단 변경 알림의 경우 courses.students 또는 courses.teachers입니다. 수업 과제 변경의 경우 courses.courseWork 또는 courses.courseWork.studentSubmissions입니다.
  • 맵에서 변경된 리소스의 식별자입니다. 이 맵은 인수를 적절한 리소스의 get 메서드에 일치시키도록 설계되었습니다. 명단 변경에 관한 알림의 경우 courseId 및 userId 필드가 채워지며 수정하지 않고 courses.students.get() 또는 courses.teachers.get()로 전송할 수 있습니다. 마찬가지로 courses.courseWork 컬렉션의 변경사항에는 수정하지 않고 courses.courseWork.get()으로 전송할 수 있는 courseId 및 id 필드가 있으며 courses.courseWork.studentSubmissions 컬렉션의 변경사항에는 수정하지 않고 courses.courseWork.studentSubmissions.get()으로 전송할 수 있는 courseId, courseWorkId, id 필드가 있습니다.

다음 코드 스니펫은 샘플 알림을 보여줍니다.

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

알림에는 알림을 트리거한 등록의 식별자를 포함하는 registrationId 메시지 속성도 있습니다. 이 속성은 registrations.delete()와 함께 사용하여 알림에서 등록을 해제하는 데 사용할 수 있습니다.