사용자가 Google Meet에서 클래스룸을 사용 중인가요? Google Meet에서 학생의 참석 여부를 확인하는 방법 관련 Apps Script 빠른 시작을 확인하세요.

Classroom API의 푸시 알림

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

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

클래스룸 푸시 알림 개요

클래스룸 API 푸시 알림 기능을 사용하면 클래스룸 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 가격 책정을 검토하고 개발자 콘솔 프로젝트에 결제를 사용 설정합니다.
  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 주제에 게시할 수 있는 권한을 부여하면 개발자 콘솔 프로젝트에서 요청을 할 수 있는 사용자가 해당 항목이 존재하는지 확인하고 알림을 등록할 수 있게 됩니다. 대부분의 애플리케이션은 클라이언트 측에 OAuth 클라이언트 ID를 저장하므로 최종 사용자가 개발자 콘솔 프로젝트에서 요청을 할 수 있습니다. 이에 해당하며 최종 사용자가 Cloud Pub/Sub 주제에 원치 않는 알림을 보내거나 푸시 알림에 사용하는 Cloud Pub/Sub 주제의 이름을 알고 있는 것이 우려된다면 다른 개발자 콘솔 프로젝트의 푸시 알림에 등록하는 것이 좋습니다.

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

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

확인할 내용

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

  • 출석부 변경 피드의 경우 이는 Rosters 범위 또는 읽기 전용 변형(이상적으로는 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 메서드와 일치하도록 설계되었습니다. 출석부 변경사항에 대한 알림의 경우 courseIduserId 필드가 채워지고 courses.students.get() 또는 courses.teachers.get()으로 수정되지 않은 상태로 전송될 수 있습니다. 마찬가지로 courses.courseWork 컬렉션에 변경된 사항은 courses.courseWork.get()에 수정되지 않고 보낼 수 있는 courseIdid 필드가 포함되며, uncourses.course.course.course.mission.mission.course.mission.course.mission.course.mission.course.mission.course.mission.course.mission.course.mission.course.mission.course.course.mission.course.course.use.course.course.use.course.use.course.선임 해야 합니다.

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

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

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