Classroom API의 푸시 알림

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

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

클래스룸 푸시 알림 개요

Classroom API 푸시 알림 기능을 사용하면 Classroom API를 사용하는 애플리케이션이 Classroom에서 데이터가 변경될 때 알림을 구독할 수 있습니다. 알림은 일반적으로 변경 후 몇 분 이내에 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 주제를 설정하려면 다음 단계를 따르세요.

Cloud Pub/Sub 기본 요건을 충족하는지 확인합니다.
Cloud Pub/Sub 클라이언트 설정
Cloud Pub/Sub 가격 책정을 검토하고 개발자 콘솔 프로젝트에 결제를 사용 설정합니다.
개발자 콘솔(가장 쉬움), 명령줄 도구(간단한 프로그래매틱 사용) 또는 Cloud Pub/Sub API를 사용하여 Cloud Pub/Sub 주제를 만듭니다. Cloud Pub/Sub는 제한된 수의 주제만 허용하므로 하나의 주제를 사용하여 모든 알림을 수신하면 애플리케이션이 인기를 얻게 되더라도 확장 문제가 발생하지 않습니다.
Cloud Pub/Sub에서 구독을 만들어 Cloud Pub/Sub에 알림을 전달하는 방법을 알려줍니다.
마지막으로 푸시 알림을 등록하기 전에 주제에 게시할 수 있도록 푸시 알림 서비스 계정(classroom-notifications@system.gserviceaccount.com)에 권한을 부여해야 합니다.

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

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 컬렉션의 변경사항에는 courseId 및 id 필드가 있으며 수정되지 않은 상태로 courses.courseWork.get()에 전송될 수 있습니다. courses.courseWork.studentSubmissions 컬렉션의 변경사항에는 courseId, courseWorkId, id 필드가 있으며 수정되지 않은 상태로 courses.courseWork.studentSubmissions.get()에 전송될 수 있습니다.

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

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

알림에는 알림을 발생시킨 등록의 식별자가 포함된 registrationId 메시지 속성도 있습니다. 이 속성은 registrations.delete()와 함께 사용하여 알림에서 등록 해제할 수 있습니다.