이 페이지는 Cloud Translation API를 통해 번역되었습니다.

푸시 알림

개요

Reseller API는 Pub/Sub API를 사용하여 다양한 Google Workspace 구독 이벤트에 관한 푸시 알림을 전송합니다. 예를 들어 고객의 구독 상태가 변경될 때 알림을 받기 위해 푸시 알림을 설정할 수 있습니다.

기본 요건

Google Cloud 프로젝트에 Pub/Sub API를 사용 설정합니다.
Cloud 프로젝트의 서비스 계정에 Pub/Sub IAM 역할을 부여합니다. roles/pubsub.editor 역할을 부여하는 것이 좋습니다 (쉽고 범위가 너무 넓지 않음). 하지만 더 구체적인 Pub/Sub 권한을 사용하는 것이 좋습니다.

주제 만들기

주제를 만들려면 resellernotify.register 메서드를 사용하여 Reseller API에 등록해야 합니다. resellernotify.register 메서드는 서비스 계정 이메일 주소를 매개변수로 사용합니다. 이 메서드로 승인된 서비스 계정만 새로 만든 주제를 구독할 수 있습니다.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/register
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

응답이 성공하면 HTTP 200 상태 코드와 Pub/Sub 주제 이름이 포함된 JSON 응답이 반환됩니다.

다음은 응답 예시입니다.

{
  "topicName": "projects/partner-watch/topics/C0abcdefg"
}

주제를 사용할 수 있도록 추가 서비스 계정을 승인하려면 resellernotify.register를 다시 호출하면 됩니다.

서비스 계정의 액세스 권한 취소

Reseller API는 resellernotify.unregister 엔드포인트를 사용하여 서비스 계정을 등록 취소하는 기능도 제공합니다.

POST https://reseller.googleapis.com/apps/reseller/v1/resellernotify/unregister
{
  "serviceAccountEmailAddress": "reseller@reseller-project.iam.gserviceaccount.com"
}

주제 구독

Pub/Sub 주제를 만든 후에는 애플리케이션이 변경 이벤트를 사용하는 방법을 설정해야 합니다. 다음 옵션 중 하나를 선택합니다.

푸시(push) 구독: HTTP POST 콜백을 제공합니다. Pub/Sub는 이 콜백을 사용하여 애플리케이션에 새 이벤트를 알립니다.
풀(pull) 구독: 애플리케이션이 주기적으로 HTTP 호출을 수행하여 큐에 추가된 모든 변경사항을 가져옵니다.

다음은 주제를 구독하는 요청의 예입니다.

PUT https://pubsub.googleapis.com/v1/projects/PROJECT/subscriptions/SUBSCRIPTION_NAME
{
  "topic": "TOPIC_NAME"
  // Only needed for push configurations
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
  },
}

다음을 바꿉니다.

PROJECT: Google Cloud 프로젝트입니다.
SUBSCRIPTION_NAME: 구독을 식별하는 이름입니다.
TOPIC_NAME: 이전에 만든 Pub/Sub 주제입니다.
PUSH_NOTIFICATION_ENDPOINT: 푸시 알림 핸들러 엔드포인트입니다.

응답이 성공하면 HTTP 200 상태 코드가 반환됩니다. 다음은 응답 예시입니다.

{
  "name": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME",
  "topic": "TOPIC_NAME",
  "pushConfig": {
    "pushEndpoint": "PUSH_NOTIFICATION_ENDPOINT"
    },
  "ackDeadlineSeconds": 10
}

알림 형식

다음은 Pub/Sub 알림의 예시입니다. 메시지 데이터는 base64로 인코딩된 JSON 문자열로 전송됩니다.

{
  "message": {
    "attributes": {},
    "data": "eyJza3VfaWQiOiAiR29vZ2xlLUFwcHMtVW5saW1pdGVkIiwgImV2ZW50X3R5cGUiOiAiU1VCU0NSSVBUSU9OX0NBTkNFTExFRCIsICJjdXN0b21lcl9kb21haW5fbmFtZSI6ICJkb21haW4uY29tIiwgInN1YnNjcmlwdGlvbl9pZCI6ICIxMjM0NTY3IiwgImN1c3RvbWVyX2lkIjogIkMwYWJjZGVmIiwgIm1lc3NhZ2VfaWQiOiAiODY3NTMwOSIsICJwdWJsaXNoX3RpbWUiOiB7InNlY29uZHMiOiAxNDU3NzMxODQ2LCAibmFub3MiOiAzNDkwMDAwMDB9LCAicmVzZWxsZXJfY3VzdG9tZXJfaWQiOiAiQzByZXNlbGxlciJ9",
    "message_id": 1234567891012131
  },
  "subscription": "projects/PROJECT/subscriptions/SUBSCRIPTION_NAME"
}

다음은 디코딩 후 message.data 객체의 예입니다.

{
  "customer_id": "C0abcdef",
  "customer_domain_name": "domain.com",
  "event_type": "SUBSCRIPTION_CANCELLED",
  "sku_id": "Google-Apps-Unlimited",
  "subscription_id": "1234567",
  // Optional fields depended on event_type
  "subscription_suspension_reasons": [],
  "subscription_cancellation_reason": "REASON"
}

이벤트 유형

다음 목록에는 가능한 모든 이벤트 유형이 포함되어 있습니다.

NEW_SUBSCRIPTION_CREATED: 새 정기 결제가 생성되었습니다.
SUBSCRIPTION_TRIAL_ENDED: 구독 무료 체험이 종료되었습니다.
PRICE_PLAN_SWITCHED: 고객이 탄력 요금제에서 연간 요금제로 전환했습니다. 고객이 갱신의 일환으로 약정 유형 요금제에서 탄력 요금제로 전환하는 경우에는 이 이벤트가 트리거되지 않습니다.
COMMITMENT_CHANGED: 연간 약정이 증가 또는 감소했습니다.
SUBSCRIPTION_RENEWED: 연간 정기 결제가 갱신되었습니다.
SUBSCRIPTION_SUSPENDED: 정기 결제가 정지되었습니다. subscription_suspension_reasons 필드를 참고하세요.
SUBSCRIPTION_SUSPENSION_REVOKED: 이전에 정지된 정기 결제의 정지가 취소되었습니다.
SUBSCRIPTION_CANCELLED: 정기 결제가 취소되었습니다. subscription_cancellation_reason 필드를 참고하세요. 송금을 감지하는 데도 사용할 수 있습니다.
SUBSCRIPTION_CONVERTED: 정기 결제가 전환되었습니다. 이 이벤트의 예는 다음과 같습니다.
- 직접 구독을 리셀러 구독으로 전환합니다.
- 유료 정기 결제를 유예 기간 혜택으로 전환합니다.
- 온라인 구독을 오프라인 구독으로 전환합니다.
SUBSCRIPTION_UPGRADE: 정기 결제 SKU가 업그레이드되었습니다. 예를 들어 구독이 Google Workspace Business Starter에서 Business Standard로 업그레이드되었습니다.
SUBSCRIPTION_DOWNGRADE: 구독 SKU가 다운그레이드되었습니다. 예를 들어 구독이 Google Workspace Business Standard에서 Business Starter로 다운그레이드되었습니다.
LICENSE_ASSIGNMENT_CHANGED: 사용자에게 라이선스가 할당되거나 취소되었습니다. 이 이벤트를 사용하여 유연한 구독의 좌석 수 변경사항을 사후적으로 추적할 수 있습니다.

정기 결제 취소 이유

정기 결제 취소 사유는 event_type가 SUBSCRIPTION_CANCELLED인 경우 채워집니다. 다음과 같은 이유로 취소될 수 있습니다.

TRANSFERRED_OUT: 고객이 직접 결제 또는 다른 리셀러로 이전했습니다.
PURCHASE_OF_SUBSUMING_SKU: 고객이 다른 SKU를 재정의하는 SKU로 업그레이드했습니다. 예를 들어 Google Workspace Business Starter 및 Google Vault를 사용하는 고객이 Google Workspace Business Plus로 업그레이드하면 Vault 구독이 Google Workspace Business Plus에 포함되어 있으므로 Vault 구독이 포함됩니다.
RESELLER_INITIATED: 리셀러가 정기 결제를 취소했습니다.
OTHER: 나열된 것 이외의 이유로 정기 결제가 취소되었습니다.

구독 정지 이유

구독 정지 사유는 event_type가 SUBSCRIPTION_SUSPENDED인 경우 채워집니다. 다음은 계정이 정지될 수 있는 이유입니다.

PENDING_TOS_ACCEPTANCE: 고객이 로그인하여 Google Workspace 재판매 서비스 약관에 동의하지 않았습니다.
RENEWAL_WITH_TYPE_CANCEL: 고객의 약정이 종료되고 계약 기간이 끝나면 서비스가 취소되었습니다.
RESELLER_INITIATED: 리셀러가 구독을 수동으로 정지했습니다.
TRIAL_ENDED: 고객의 무료 체험이 만료되었으나 고객이 무료 체험이 아닌 요금제를 선택하지 않았습니다.
OTHER: 악용 등 Google 내부 사유로 고객이 정지되었습니다.

Pub/Sub 제한사항

푸시 알림 순서는 보장되지 않습니다. 메시지가 여러 번 전송되거나 극단적인 상황에서는 전송되지 않을 수도 있습니다. 변경된 모든 정기 결제에서 reseller.subscriptions.get를 사용하여 현재 상태를 가져오는 것이 좋습니다.