Classroom API의 푸시 알림

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

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

클래스룸 푸시 알림 개요

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

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

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

  • 대상은 알림이 전송되는 위치입니다.
  • 피드는 서드 파티 애플리케이션이 구독할 수 있는 알림 유형입니다. 예: '1234 수업의 출석부 변경'
  • 등록은 특정 피드에서 대상으로 알림을 전달하도록 Classroom 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를 사용하여 Play Console에서(가장 쉬움) 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를 클라이언트 측에 저장하므로 최종 사용자가 Play Console 프로젝트에서 요청을 할 수 있습니다. 이 경우에 해당하고 최종 사용자가 Cloud Pub/Sub 주제로 원치 않는 알림을 보내거나 푸시 알림에 사용하는 Cloud Pub/Sub 주제의 이름을 알고 있을까 봐 걱정된다면 다른 Play Console 프로젝트의 푸시 알림을 등록하는 것이 좋습니다.

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

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

승인

Classroom 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으로 인코딩되며 다음을 포함합니다.

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

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

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