Pub/Sub 알림

Google Cloud 프로젝트를 설정하고 Cloud Channel API를 호출하는 서비스 계정을 만들려면 API 설정 Codelab을 완료해야 합니다.
이 Codelab에는 테스트 Partner Sales Console을 사용하는 것이 좋습니다.
Pub/Sub 개념 숙지

개요

Cloud Channel API는 Pub/Sub를 사용하여 다양한 고객 및 사용 권한 이벤트에 대한 알림을 전달합니다.

이는 다음과 같은 경우에 특히 유용합니다.

Partner Sales Console에서 직접 자체 시스템의 변경된 사항을 반영합니다(예: 지원팀 담당자가 Google Workspace 사용 권한을 취소함).
리셀러 고객이 트리거한 중요한 이벤트를 감지합니다. 예를 들면 다음과 같습니다.
- Google Workspace 고객이 서비스 약관에 동의함
- Google Workspace 고객이 도메인을 인증함
- Google Workspace 고객이 탄력 요금제 사용 권한으로 사용자를 추가함
- Google Workspace 고객이 다른 곳으로 이전함

Pub/Sub 설정은 다음 세 단계로 구성됩니다.

Pub/Sub API를 사용 설정하고 서비스 계정을 준비합니다.
Pub/Sub 주제를 만듭니다. 이 주제는 채널 서비스에 적용되고 구독을 만들 수 있는 서비스 계정을 지정하게 됩니다.
Pub/Sub 구독을 만듭니다. 이 구독은 웹훅(권장 방법)을 사용하는 푸시 또는 풀일 수 있습니다.

푸시 구독의 경우 채널 서비스에서 내보낸 이벤트를 수신하는 웹훅을 호스팅합니다.

채널 서비스 푸시 알림

알림 형식

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

{
  "message": {
    "attributes": {
      "event_type": "LICENSE_ASSIGNMENT_CHANGED",
      "subscriber_event_type": "ENTITLEMENT_EVENT"
    },
    "data": "eyJlbnRpdGxlbWVudF9ldmVudCI6eyJldmVudF90eXBlIjoiTElDRU5TRV9BU1NJR05NRU5UX0NIQU5HRUQiLCJlbnRpdGxlbWVudCI6ImFjY291bnRzL0MwMTIzNDU2L2N1c3RvbWVycy9TMDEyMzQ1NjcvZW50aXRsZW1lbnRzL1NhYmNkZWYxMjM0NSJ9fQ==",
    "message_id": 1918124788439510,
    "publish_time": "2021-01-14T01:23:45.678Z"
  },
  "subscription": "projects/project/subscriptions/channel-pubsub-test"
}

동일한 메시지 데이터가 디코딩됩니다.

{
  "entitlement_event": {
    "event_type": "LICENSE_ASSIGNMENT_CHANGED",
    "entitlement": "accounts/C0123456/customers/S01234567/entitlements/Sabcdef12345"}
  }
}

1단계: Pub/Sub API 사용 설정 및 서비스 계정 준비

이 Codelab을 실행하려면 다음이 필요합니다.

프로젝트 기반 서비스 계정의 이메일 주소 이 주소는 service-account@project.iam.gserviceaccount.com과 같은 형식입니다.
리셀러 도메인 최고 관리자 계정 액세스 권한(테스트 Partner Sales Console 권장)
계정 ID Partner Sales Console의 설정에서 확인할 수 있습니다.

서비스 계정을 준비하려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 API 라이브러리 섹션으로 이동하여 Pub/Sub API를 사용 설정합니다.
서비스 계정에 프로젝트에 대한 Pub/Sub IAM 역할을 부여합니다. roles/pubsub.editor (역할 이름 = 'Pub/Sub 편집자') 부여는 이 Codelab에 충분하지만 프로덕션 통합에서는 보다 세분화된 권한을 사용해 볼 수 있습니다. Pub/Sub 액세스 제어 페이지에서 전체 IAM 역할 세부정보를 확인할 수 있습니다.
대신 커스텀 역할을 적용하려면 해당 역할에 구독을 만들 수 있는 pubsub.subscriptions.create 권한을 부여해야 합니다.

계정에 이러한 역할 및 권한을 적용한 후 지연이 발생할 수 있습니다.

2단계: 계정의 주제 만들기

Pub/Sub 주제를 만들려면 accounts.register 메서드를 사용해야 합니다. 이 메서드는 서비스 계정 이메일을 파라미터로 사용합니다. 이 메서드를 통해 승인된 서비스 계정만 새 주제를 구독할 수 있습니다.

accounts.register 문서로 이동하여 사용해 보기를 클릭합니다.
account 필드에 accounts/ACCOUNT_ID을(를) 입력하고 ACCOUNT_ID을(를) 계정 ID로 바꿉니다.
요청 본문 매개변수 추가를 클릭하고 serviceAccount을(를) 선택한 다음 서비스 계정 이메일 주소를 입력합니다.
실행을 클릭하고 리셀러 도메인의 최고 관리자로 로그인해야 합니다.

다음과 비슷한 응답 200개가 표시됩니다.

{
  "topic": "projects/cloud-channel-pubsub/topics/C0123456-notify"
}

이벤트가 게시될 Pub/Sub 주제입니다.

3단계: 주제 구독하기

Pub/Sub 주제를 만든 후에는 애플리케이션이 변경 이벤트를 사용하는 방법을 설정해야 합니다. 다음과 같은 두 가지 옵션이 있습니다.

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

이 Codelab에서는 푸시를 사용하고 모든 이벤트를 Cloud Logging에 로깅하는 Cloud Run 함수로 전송합니다.

Cloud Run 함수에 채널 서비스 알림 푸시

3a단계: Cloud Run 함수 만들기

이 단계에서는 수신된 메시지를 로깅하는 Cloud Run 함수를 만듭니다.

Google Cloud 콘솔의 Cloud Run 함수 섹션으로 이동합니다. Cloud Run 함수 API를 사용 설정해야 할 수 있습니다.
함수 만들기를 클릭합니다.
구성 화면에서 다음을 수행합니다.
1. 함수 이름을 변경합니다. 원하는 경우 다른 리전을 선택합니다.
2. HTTP 트리거에서 인증을 인증되지 않은 호출 허용으로 변경하고 저장을 클릭합니다.
3. 트리거 URL을 기록해 둡니다. 다음 단계에 이 항목이 필요합니다.
4. 다음을 클릭합니다.

코드 화면에서 다음을 수행합니다.

Node.js 런타임 선택
진입점을 log(으)로 변경
index.js 파일에서 샘플 코드를 다음으로 바꿉니다.

exports.log = (req, res) => {
  if (req.body && req.body.message) {
    console.log(req.body);
    const message = req.body.message;
    // data is base64-encoded JSON
    const data = new Buffer.from(message.data, 'base64').toString();
    console.log(data);
  }
  res.status(200).send('OK');
};

Cloud Run 함수가 배포되는 동안 다음 단계를 진행할 수 있습니다.

3b단계: 구독 만들기

채널 서비스 주제에 등록된 서비스 계정(2단계 참고)만 구독을 만들 수 있습니다.

코드에서 서비스 계정 사용자 인증 정보를 사용하여 Pub/Sub API를 호출하면 됩니다. Cloud Channel API를 호출할 때 필요한 리셀러 도메인의 최고 관리자를 가장하지 않는지 확인합니다.

이 Codelab에서는 Cloud Shell에서 gcloud CLI 도구를 사용합니다.

Google Cloud 콘솔 상단에서 Cloud Shell 활성화를 클릭합니다.
셸이 준비되면 다음 명령어를 실행합니다. SERVICE_ACCOUNT 값을 서비스 계정의 이메일 주소로, TOPIC을 2단계에서 만든 주제로, PUSH_ENDPOINT를 3a단계에서 만든 Cloud Run 함수의 트리거 URL로 바꿉니다.
```
SERVICE_ACCOUNT=service-account@project.iam.gserviceaccount.com
TOPIC=projects/cloud-channel-pubsub/topics/C0123456-notify
PUSH_ENDPOINT=https://us-central1-project.cloudfunctions.net/pubsub
```

셸에서 서비스 계정을 활성화합니다.

gcloud iam service-accounts keys create sa-keys.json \
    --iam-account=$SERVICE_ACCOUNT
gcloud auth activate-service-account --key-file=sa-keys.json

구독을 만듭니다.

gcloud pubsub subscriptions create channel-pubsub-test \
    --topic=$TOPIC \
    --push-endpoint=$PUSH_ENDPOINT

Pub/Sub 구독 섹션으로 이동하여 구독이 설정되었는지 확인할 수 있습니다.

일부 데이터 생성

이전 단계를 완료하면 데이터를 수신할 준비가 되었습니다.

가장 쉬운 방법은 Partner Sales Console에서 고객을 만들고 제품을 프로비저닝하는 것입니다. 엔드 투 엔드 Workspace 프로비저닝 Codelab을 완료했으면 샘플 코드를 실행하여 Google Workspace 고객을 만들 수 있습니다.

Google Cloud 콘솔에서 함수로 이동하여 로그 탭을 엽니다. 다음은 표시되는 화면의 예시입니다.

Pub/Sub 이벤트 샘플 로그

삭제

Cloud Run 함수 삭제
구독 삭제

남아 있는 구독자가 없으면 주제가 자동으로 삭제됩니다.

다음 단계

이 Codelab에서는 채널 서비스가 Pub/Sub를 활용하여 반응형 방식으로 대규모 통합을 빌드할 수 있는 방법을 알아봤습니다.

이벤트 참조

채널 서비스에서 생성되는 이벤트 목록은 RPC 참조를 참고하세요.

API 참조

이 Codelab에서는 Google Cloud 콘솔을 사용하지만 이러한 단계를 프로그래매틱 방식으로 수행할 수도 있습니다. 방법은 다음과 같습니다.

accounts.register(을)를 사용하여 주제를 만듭니다.
Pub/Sub API의 subscriptions.create을(를) 사용하여 Pub/Sub 구독을 만듭니다.
통합에 사용할 수 있는 추가 엔드포인트는 accounts.listSubscribers 및 accounts.unregister을(를) 참조하세요.

Pub/Sub 보증 및 권장사항

이벤트와 알림 사이의 지연은 확실하지 않습니다. 마찬가지로 알림 순서도 보장되지 않습니다. 마지막으로 메시지는 여러 번 전송될 수 있습니다.

푸시 엔드포인트 권장사항:

메시지가 지연되거나 순서에 맞지 않게 전송되거나 여러 번 전송될 수 있으므로 엔드포인트는 멱등성을 가지며 customers.get과(와) entitlements.get을(를) 사용해야 합니다.
푸시의 기본 Pub/Sub 제한 시간은 10초이지만(Pub/Sub 구독의 ackDeadline을(를) 통해 늘릴 수 있음) 메시지 기반 아키텍처를 사용하고 엔드포인트가 최대한 빠르게 응답하도록 하는 것이 좋습니다.
엔드포인트가 다운되거나 5xx 오류를 반환하면 Pub/Sub가 재시도합니다. 푸시를 통해 메시지를 수신하는 방법에 대한 자세한 내용은 Pub/Sub 문서를 참고하세요.

풀을 사용하려면 Pub/Sub 문서의 풀을 통해 메시지를 수신하는 방법을 참조하세요.

이벤트 필터링

채널 서비스 알림에는 attributes이(가) 포함되어 있으므로 Pub/Sub 필터링이 적용된 구체적인 Pub/Sub 구독을 만들어 세분화된 구독을 만들 수 있습니다.

예를 들어 attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED"이(가) 적용된 필터링을 통해 모든 Google Workspace 사용 가능 라이선스 수 변경사항을 추적할 수 있습니다.