이 페이지에서는 Google Workspace Events API의 개요를 살펴보고 API를 사용하여 Google Workspace에서 이벤트를 구독하는 방법을 설명합니다.
Google Workspace 이벤트는 리소스가 생성, 업데이트, 삭제되는 등 Google Workspace 리소스의 변경사항을 나타냅니다. 관심 있는 관련 이벤트를 수신할 수 있도록 앱에서 Google Workspace 리소스를 구독할 수 있습니다.
앱에서 이벤트를 수신하는 방법
앱이 Google Workspace 이벤트를 수신하도록 하려면 Google Workspace Events API를 사용하여 Google Workspace 리소스에 대한 구독을 만듭니다.
Google Workspace Events API에서 구독을 통해 앱에 이벤트를 전송하는 방법은 다음과 같습니다.
- 앱이 Google Chat 스페이스와 같은 Google Workspace 애플리케이션의 리소스를 구독합니다.
- 구독 중인 리소스가 변경됩니다.
- Google Workspace 애플리케이션은 Google Workspace 구독의 알림 엔드포인트 역할을 하는 Google Cloud Pub/Sub의 주제로 이벤트를 전송합니다. 이벤트에는 리소스 변경사항에 대한 데이터가 포함됩니다.
- 앱은 이벤트가 포함된 Google Cloud Pub/Sub 메시지를 처리하고 필요한 경우 작업을 수행합니다.
중요한 용어
다음은 Google Workspace Events API에서 사용되는 일반적인 용어 목록입니다.
- Google Workspace 이벤트
Google Workspace 리소스 변경사항 이벤트 형식은 CloudEvents 사양에 따라 지정되며 정기 결제 이벤트 또는 수명 주기 이벤트일 수 있습니다.
- 구독 이벤트
- 모니터링 중인 Google Workspace 리소스의 변경사항(예: Google Chat 스페이스의 새 메시지) 변경된 리소스에 대해 수신하려는 세부정보를 지정할 수 있습니다. 자세한 내용은 Google Workspace 이벤트의 구조를 참고하세요.
- 수명 주기 이벤트
- Google Workspace 구독에 관한 이벤트입니다. 수명 주기 이벤트는 정기 결제 이벤트 누락을 피할 수 있도록 문제와 정기 결제 상태를 알려줍니다. 기본적으로 정기 결제는 항상 수명 주기 이벤트를 수신합니다. 자세한 내용은 Google Workspace 구독의 수명 주기 이벤트를 참고하세요.
- Google Workspace 구독
Google Workspace 애플리케이션의 리소스를 모니터링하는 이름이 지정된 항목입니다. 정기 결제는
Subscription리소스로 표현됩니다. 정기 결제는 다음 정보로 정의됩니다.- 대상 리소스
- 모니터링할 Google Workspace 리소스입니다.
이 리소스는 Google Workspace 구독의
targetResource필드에 표시됩니다. 각 구독은 하나의 리소스만 모니터링할 수 있습니다. Google Workspace Events API에서 지원하는 Google Workspace 리소스를 확인하려면 지원되는 Google Workspace 이벤트를 참고하세요. - 이벤트 유형
- 대상 리소스에 대해 알림을 받을 변경 유형입니다. 예를 들어 Google Chat 스페이스를 구독한 경우 스페이스 및 하위 리소스(예: 멤버십, 메시지)에 관한 이벤트를 수신할지 선택할 수 있습니다.
- 알림 엔드포인트
- Google Workspace 구독이 이벤트를 수신하는 엔드포인트입니다. Google Workspace Events API는 Google Cloud Pub/Sub 주제를 알림 엔드포인트로 지원합니다. Google Cloud Pub/Sub 사용에 대한 자세한 내용은 Google Cloud Pub/Sub 문서를 참조하세요.
- 페이로드 옵션
- 변경된 리소스에 관해 수신할 이벤트 데이터입니다.
지원되는 Google Workspace 이벤트
앱에서 이벤트를 수신할 수 있는 이벤트는 정기 결제의 타겟 리소스에 따라 다릅니다. 다음 표에는 가능한 각 타겟 리소스에 지원되는 이벤트가 나와 있습니다.
| 대상 리소스 | 방식 | 지원되는 이벤트 | 제한사항 (해당하는 경우) | |
|---|---|---|---|---|
| Google Chat | ||||
| Google Chat 스페이스 | //chat.googleapis.com/spaces/SPACE_ID |
자세한 내용은 Google Chat 이벤트 구독하기를 참고하세요. |
구독을 승인하는 Google Chat 사용자는 Google Workspace 또는 Google 계정을 통해 스페이스 구성원이어야 합니다. | |
| Google Chat 사용자 | //cloudidentity.googleapis.com/users/USER_ID |
자세한 내용은 Google Chat 이벤트 구독하기를 참고하세요. |
구독은 구독을 승인한 사용자에 대한 이벤트만 수신합니다. 사용자는 다른 사용자를 대신하여 정기 결제를 승인할 수 없습니다. |
|
| Google Meet | ||||
| Google Meet 회의 공간 | //meet.googleapis.com/spaces/SPACE_ID |
자세한 내용은 Google Meet 이벤트 구독하기를 참고하세요. |
||
| Google Meet 사용자 | //cloudidentity.googleapis.com/users/USER_ID |
자세한 내용은 Google Meet 이벤트 구독하기를 참고하세요. |
구독은 사용자가 다음 중 하나에 해당하는 회의 공간에 관한 이벤트를 수신합니다.
|
|
Google Workspace 이벤트의 구조
Google Workspace 이벤트는 이벤트 데이터를 설명하는 업계 표준 방법인 CloudEvents 사양을 따릅니다. Google Workspace 이벤트에는 다음이 포함됩니다.
- CloudEvent의 Attributes입니다.
- 이벤트로 인해 변경된 Google Workspace 리소스에 대한 데이터
다음 섹션에서는 Google Workspace 이벤트의 속성과 데이터 구조를 설명합니다.
CloudEvent 속성
Google Workspace 이벤트에는 다음과 같은 필수 CloudEvents 속성이 포함됩니다.
| 속성 | 설명 | 예 |
|---|---|---|
|
이벤트에 전달된 데이터의 유형입니다. |
|
|
CloudEvent의 식별자입니다. |
|
|
이벤트의 소스입니다. Google Workspace 이벤트의 경우 구독의 전체 리소스 이름입니다. |
//workspaceevents.googleapis.com/subscriptions/chat-spaces-abcdefg
|
|
이 이벤트에 사용된 CloudEvents 사양 버전입니다. |
|
|
이벤트가 발생한 Google Workspace 리소스입니다. |
|
|
이벤트가 발생한 타임스탬프입니다. RFC 3339 형식입니다. |
|
|
Google Workspace 이벤트의 유형입니다. |
|
이벤트 데이터
이벤트 데이터는 대상 리소스의 하위 리소스를 포함하여 구독의 대상 리소스 변경을 나타내는 페이로드입니다. 구독에서 페이로드에 변경된 리소스에 대한 데이터를 포함할지 아니면 변경된 리소스의 이름만 포함할지 지정할 수 있습니다.
예를 들어 Chat 스페이스를 구독하는 경우 스페이스의 새 메시지에 관한 이벤트를 수신할 수 있습니다. 새 메시지에 대한 이벤트의 경우 이벤트 데이터에 생성된 Chat spaces.message 리소스가 포함된 페이로드가 포함됩니다.
정기 결제를 만들 때 앱이 수신하는 이벤트에 리소스 데이터를 얼마나 포함할지 지정할 수 있습니다.
- 리소스 데이터 포함: 변경된 리소스의 일부 또는 모든 필드를 포함합니다. 리소스 데이터를 포함하도록 선택하면 구독 기간이 최대 4시간(도메인 전체 위임을 사용하는 경우 24시간)으로 제한됩니다.
- 리소스 데이터 제외: 변경된 리소스의 이름만 포함됩니다. 구독 기간은 최대 7일입니다. 이벤트에 대한 세부정보를 얻으려면 리소스 이름을 사용하여 리소스를 쿼리하면 됩니다.
이러한 이벤트 데이터 옵션은 정기 결제의 payloadOptions 필드에 표시됩니다.
Google Cloud Pub/Sub 메시지로 이벤트
Google Workspace Events API 구독은 Google Cloud Pub/Sub 주제를 Google Workspace 이벤트를 수신하는 알림 엔드포인트로 사용합니다. 이벤트는 Google Cloud Pub/Sub 메시지로 인코딩됩니다. 앱은 Google Cloud Pub/Sub 메시지를 처리하여 조치를 취하거나 이벤트에 응답할 수 있습니다.
다음 예시는 Chat 스페이스의 업데이트된 메시지에 대한 이벤트가 포함된 Google Cloud Pub/Sub 메시지를 보여줍니다.
{
"message":
{
"attributes":
{
"ce-datacontenttype": "application/json",
"ce-id": "spaces/SPACE_ID/spaceEvents/SPACE_EVENT_ID",
"ce-source": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"ce-specversion": "1.0",
"ce-subject": "//chat.googleapis.com/spaces/SPACE_ID",
"ce-time": "2023-09-07T21:37:53.274191Z",
"ce-type": "google.workspace.chat.message.v1.updated"
},
"data": "EVENT_DATA",
"messageId": "PUBSUB_MESSAGE_ID",
"orderingKey": "//workspaceevents.googleapis.com/subscriptions/SUBSCRIPTION_ID",
"publishTime": "2023-09-07T21:37:53.713Z"
}
}
다음 필드를 참고하세요.
attributes: CloudEvent의 속성으로, 이벤트 유형이 포함됩니다. 이 경우 이벤트는 스페이스의 업데이트된 메시지에 관한 이벤트입니다.data: 업데이트된spaces.message리소스에 대한 세부정보가 포함된 이벤트 데이터로, Base64 인코딩 문자열 형식으로 지정됩니다.messageId: Google Cloud Pub/Sub 메시지의 식별자입니다.
CloudEvents가 Google Cloud Pub/Sub 메시지에 지정되는 방식을 자세히 알아보려면 CloudEvents용 Google Cloud Pub/Sub 프로토콜 바인딩을 참조하세요.
관련 주제
- Google Chat 이벤트 구독하기
- Google Workspace 구독의 수명 주기 이벤트
- Google Workspace Events API 범위 선택하기
- Google Workspace 구독 만들기