푸시 알림

이 페이지에서는 리셀러 API로 푸시 알림을 사용하는 방법을 설명합니다.

개요

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

기본 요건

Google Cloud 프로젝트에 대해 Pub/Sub API를 사용 설정합니다.
Cloud 프로젝트에서 서비스 계정에 Pub/Sub IAM 역할을 부여합니다. roles/pubsub.editor 역할을 부여하는 것이 좋지만 더 구체적인 Pub/Sub 권한을 사용할 수도 있습니다.

주제 만들기

주제를 만들려면 resellernotify.register 메서드를 사용하여 리셀러 API에 등록합니다. 이 메서드는 서비스 계정 이메일 주소를 파라미터로 사용합니다. 이 메서드로 승인된 서비스 계정만 주제를 구독할 수 있습니다.

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 주제를 만든 후 애플리케이션이 변경 이벤트를 사용하는 방법을 설정합니다. 다음 중 하나를 선택합니다.

푸시 구독: 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 dependent 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 및 Vault를 사용하는 고객이 Vault가 포함된 Business Plus로 업그레이드합니다.
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를 사용하여 현재 상태를 가져오는 것이 좋습니다.