이제 Google 클래스룸 부가기능이 일반적으로 개발자에게 제공됩니다. 자세한 내용은
부가기능 문서를 참고하세요.
Classroom API의 푸시 알림
컬렉션을 사용해 정리하기
내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.
Registrations 컬렉션의 메서드를 사용하여 클래스룸에서 데이터가 변경될 때 알림을 받을 수 있습니다.
이 도움말에서는 푸시 알림 수신을 시작하는 방법에 관한 간단한 안내와 함께 개념적 개요를 제공합니다.
클래스룸 푸시 알림 개요
Classroom 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 주제를 설정하려면 다음을 실행해야 합니다.
- Cloud Pub/Sub 기본 요건을 충족해야 합니다.
- Cloud Pub/Sub 클라이언트를 설정합니다.
- Cloud Pub/Sub 요금을 검토하고 Developer Console 프로젝트에 결제를 사용 설정합니다.
개발자 콘솔(가장 쉬움), 명령줄 도구(간단한 프로그래매틱 사용) 또는 Cloud Pub/Sub API를 사용하여 Cloud Pub/Sub 주제를 만듭니다.
Cloud Pub/Sub는 제한된 수의 주제만 허용하므로 하나의 주제를 사용하여 모든 알림을 수신하면 애플리케이션이 인기를 얻더라도 확장 문제가 발생하지 않습니다.
Cloud Pub/Sub에서 구독을 만들어 Cloud Pub/Sub에 알림을 전송하는 방법을 알려줍니다.
마지막으로 푸시 알림을 등록하기 전에 주제에 게시할 수 있는 푸시 알림 서비스 계정(classroom-notifications@system.gserviceaccount.com) 권한을 부여해야 합니다.
참고: 푸시 알림 서비스 계정에 Cloud Pub/Sub 주제에 게시할 권한을 부여하면 Developer Console 프로젝트에서 요청할 수 있는 사용자는 주제가 존재하는지 확인하고 주제에 알림을 등록할 수 있습니다. 많은 애플리케이션은 클라이언트 측에 OAuth 클라이언트 ID를 저장하므로 최종 사용자가 개발자 콘솔 프로젝트에서 요청할 수 있습니다. 이 경우 최종 사용자가 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 컬렉션의 변경사항에는 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()와 함께 사용하여 알림에서 등록을 해제하는 데 사용할 수 있습니다.
달리 명시되지 않는 한 이 페이지의 콘텐츠에는 Creative Commons Attribution 4.0 라이선스에 따라 라이선스가 부여되며, 코드 샘플에는 Apache 2.0 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 Google Developers 사이트 정책을 참조하세요. 자바는 Oracle 및/또는 Oracle 계열사의 등록 상표입니다.
최종 업데이트: 2025-05-26(UTC)
[null,null,["최종 업데이트: 2025-05-26(UTC)"],[],[],null,["# Push notifications in the Classroom API\n\nYou can use the methods on the\n[`Registrations`](/workspace/classroom/reference/rest/v1/registrations)\ncollection to receive notifications when data changes in Classroom.\n\nThis article provides a conceptual overview along with simple instructions on\nhow to start receiving push notifications.\n\nOverview of Classroom push notifications\n----------------------------------------\n\nThe Classroom API push notifications feature allows applications using the\nClassroom API to subscribe for notifications when data changes in Classroom.\nNotifications are delivered to a [Cloud\nPub/Sub](https://cloud.google.com/pubsub) topic, usually within a few minutes of\nthe change.\n\nTo receive push notifications, you need to [set up a Cloud Pub/Sub\ntopic](#topic-setup) and provide that topic's name when you create a\n**registration** for the appropriate **feed** of notifications.\n\nBelow are definitions of key concepts used in this documentation:\n\n- A **destination** is a place where notifications are sent.\n- A **feed** is a type of notifications that a third party application can subscribe to. For example, \"roster changes for course 1234\".\n- A **registration** is an instruction to the Classroom API to deliver notifications from a particular *feed* to a *destination*.\n\nOnce you create a registration for a feed, that registration's Cloud Pub/Sub\ntopic receives notifications from that feed until it expires. Your registration\nlasts a week, but you can extend it at any point before it expires by making an\nidentical request to `registrations.create()`.\n\nYour Cloud Pub/Sub topic only receives notifications about resources that you\ncan view with the credentials you supply when creating a registration. For\nexample, if the user revokes permission from your application or is removed as a\nteacher, notifications are no longer delivered.\n\n### Types of feeds\n\nThe Classroom API currently offers three types of feed:\n\n- Each domain has a **roster changes for domain** feed, which exposes notifications when students and teachers join and leave courses in that domain.\n- Each course has a **roster changes for course** feed, which exposes notifications when students and teachers join and leave courses in that course.\n- Each course has a **course work changes for course** feed, which exposes notifications when any course work or student submission objects are created or modified in that course.\n\nSetting up a Cloud Pub/Sub topic\n--------------------------------\n\nNotifications are delivered to Cloud Pub/Sub topics. From Cloud Pub/Sub, you can\nreceive notifications on a webhook, or by polling a subscription endpoint.\n\nTo set up a Cloud Pub/Sub topic, you need to do the following:\n\n1. Make sure you fulfill the [Cloud Pub/Sub\n Prerequisites](https://cloud.google.com/pubsub/prereqs).\n2. [Set up a Cloud Pub/Sub client](https://cloud.google.com/pubsub/configure).\n3. Review the [Cloud Pub/Sub pricing](https://cloud.google.com/pubsub/pricing), and enable billing for your Developer Console project.\n4. Create a Cloud Pub/Sub topic [in the Developer\n Console](https://cloud.google.com/pubsub/docs/quickstart-console#create_a_topic)\n (easiest), [via the command line\n tool](https://cloud.google.com/pubsub/docs/quickstart-cli#use_the_gcloud_command-line_tool)\n (for simple programmatic use) or using the [Cloud Pub/Sub\n API](https://cloud.google.com/pubsub/docs/quickstart-client-libraries#create_a_topic_and_a_subscription).\n Note that Cloud Pub/Sub [only allows a limited number of\n topics](https://cloud.google.com/pubsub/quotas), so using one topic to\n receive all your notifications ensures you do not hit scaling issues if your\n application becomes popular.\n\n5. [Create a Subscription in Cloud\n Pub/Sub](https://cloud.google.com/pubsub/docs/subscriber), to tell Cloud\n Pub/Sub how to deliver your notifications.\n\n6. Finally, before registering for Push Notifications, you need to [grant the\n Push Notifications service account\n (`classroom-notifications@system.gserviceaccount.com`)\n permission](https://cloud.google.com/pubsub/docs/access_control#console) to\n publish to your topic.\n\nNOTE: If you grant the Push Notifications service account permission to publish\nto your Cloud Pub/Sub topic, users who can make requests from your Developer\nConsole project will be able to determine that it exists, and register for\nnotifications to it. Many applications store OAuth Client IDs on the client\nside, so end-users might be able to make requests from your Developer Console\nproject. If this applies to you, and you are concerned about end-users sending\nunwanted notifications to your Cloud Pub/Sub topic or knowing the names of Cloud\nPub/Sub topics that you use for push notifications, you should consider\nregistering for push notifications from a different Developer Console project.\n\nRegister your application for notifications\n-------------------------------------------\n\nOnce you have a topic that the Classroom API push notifications service account\ncan publish to, you can register for notifications, using the\n[`registrations.create()`](/workspace/classroom/reference/rest/v1/registrations/create)\nmethod. The `registrations.create()` method validates that the provided Cloud\nPub/Sub topic can be reached by the push notifications service account. The\nmethod fails if the push notifications service account cannot reach the topic;\nfor example, if the topic does not exist or you have not granted it publish\npermission on that topic.\n\n### Authorization\n\nLike all calls to the Classroom API, calls to `registrations.create()` [must be\nauthorized](/workspace/classroom/guides/auth) with an authorization token. This\nauthentication token must include the Push Notifications scope\n(`https://www.googleapis.com/auth/classroom.push-notifications`) and whatever\nscopes are required to view the data about which notifications are being sent.\n\n- For roster change feeds, this means the Rosters scope or (ideally) its read-only variant (`https://www.googleapis.com/auth/classroom.rosters.readonly` or `https://www.googleapis.com/auth/classroom.rosters`).\n- For course work change feeds, this means the \"students\" versions of the course work scope or (ideally) its read-only variant (`https://www.googleapis.com/auth/classroom.coursework.students.readonly` or `https://www.googleapis.com/auth/classroom.coursework.students`).\n\nFor notifications to be delivered, the application must retain an OAuth grant\nfrom the authorized user with the required scopes. If the user disconnects the\napplication, notifications cease. Note that currently, domain-wide delegation of\nauthority is not supported for this purpose. If you attempt to register for\nnotifications using only domain-wide delegated authority, you will receive a\n`@MissingGrant` error.\n\nReceiving notifications\n-----------------------\n\nNotifications are encoded with JSON, and contain:\n\n- The name of the collection containing the resource that changed. For notifications about roster changes, this is either `courses.students` or `courses.teachers`. For course work changes, this is either `courses.courseWork` or `courses.courseWork.studentSubmissions`.\n- Identifiers for the resource that changed, in a map. This map is designed to match the arguments to the `get` method of the appropriate resource. For notifications about roster changes, the `courseId` and `userId` fields will be populated, and can be sent unmodified to [courses.students.get()](/workspace/classroom/reference/rest/v1/courses.students/get) or [courses.teachers.get()](/workspace/classroom/reference/rest/v1/courses.teachers/get). Similarly, changes to the courses.courseWork collection will have `courseId` and `id` fields that can be sent unmodified to [courses.courseWork.get()](/workspace/classroom/reference/rest/v1/courses.courseWork/get) and changes to the courses.courseWork.studentSubmissions collection will have `courseId`, `courseWorkId`, and `id` fields that can be sent unmodified to [courses.courseWork.studentSubmissions.get()](/workspace/classroom/reference/rest/v1/courses.courseWork.studentSubmissions/get).\n\nThe following code snippet demonstrates a sample notification: \n\n {\n \"collection\": \"courses.students\",\n \"eventType\": \"CREATED\",\n \"resourceId\": {\n \"courseId\": \"12345\",\n \"userId\": \"45678\"\n }\n }\n\nNotifications also have a `registrationId` message attribute, containing the\nidentifier for the registration that caused the notification, which can be used\nwith\n[`registrations.delete()`](/workspace/classroom/reference/rest/v1/registrations/delete)\nto unregister from notifications."]]
