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 함수로 전송합니다.
3a단계: Cloud Run 함수 만들기
이 단계에서는 수신된 메시지를 로깅하는 Cloud Run 함수를 만듭니다.
- Google Cloud 콘솔의 Cloud Run 함수 섹션으로 이동합니다. Cloud Run 함수 API를 사용 설정해야 할 수 있습니다.
- 함수 만들기를 클릭합니다.
- 구성 화면에서 다음을 수행합니다.
- 함수 이름을 변경합니다. 원하는 경우 다른 리전을 선택합니다.
- HTTP 트리거에서 인증을 인증되지 않은 호출 허용으로 변경하고 저장을 클릭합니다.
- 트리거 URL을 기록해 둡니다. 다음 단계에 이 항목이 필요합니다.
- 다음을 클릭합니다.
코드 화면에서 다음을 수행합니다.
- 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 콘솔에서 함수로 이동하여 로그 탭을 엽니다. 다음은 표시되는 화면의 예시입니다.
삭제
- 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 사용 가능 라이선스 수 변경사항을 추적할 수 있습니다.