Pub/Sub 알림

API 설정 Codelab을 완료하여 Google Cloud 프로젝트를 설정하고 Cloud Channel API를 호출할 서비스 계정을 만들어야 합니다.
이 코드랩에는 테스트 채널 서비스 콘솔을 사용하는 것이 좋습니다.
Pub/Sub 개념을 숙지합니다.

개요

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

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

자체 시스템의 채널 서비스 콘솔에서 직접 적용한 변경사항을 반영합니다 (예: 지원팀 구성원이 Google 작업공간 자격을 취소하는 경우).
리셀러 고객이 트리거하는 중요 이벤트를 감지합니다. 예를 들면 다음과 같습니다.
- 서비스 약관을 수락하는 Google 작업공간 고객
- 도메인을 확인하는 Google 작업공간 고객
- 유연한 자격에 사용자를 추가하는 Google Workspace 고객
- Google 작업공간 고객이 다른 곳으로 이전하는 경우

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

Pub/Sub API를 사용 설정하고 서비스 계정을 준비합니다.
Pub/Sub 주제를 만듭니다. 이 주제는 채널 서비스에서 소유하며 구독을 만들 수 있는 서비스 계정을 지정합니다.
Pub/Sub 구독을 만듭니다. 웹 This은 웹 webhook (권장 방법)을 사용하여 푸시하거나 pull할 수 있습니다.

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

채널 서비스의 푸시 알림

알림 형식

다음은 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 사용 설정 및 서비스 계정 준비

이 코드랩을 실행하려면 다음이 필요합니다.

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

서비스 계정을 준비하는 방법은 다음과 같습니다.

Google Cloud Console에서 API 라이브러리 섹션으로 이동하여 Pub/Sub API를 사용 설정합니다.
서비스 계정에 프로젝트의 Pub/Sub IAM 역할을 서비스 계정에 부여합니다. 이 Codelab에는 roles/pubsub.editor 권한을 부여하는 것이 좋지만 프로덕션 통합에서 더 세분화된 권한을 사용해야 할 수 있습니다. Pub/Sub 액세스 제어 페이지에서 전체 참조를 확인할 수 있습니다.

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 주제를 만든 후에는 애플리케이션에서 변경 이벤트를 사용하는 방식을 설정해야 합니다. 다음과 같은 옵션을 선택할 수 있습니다.

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

이 Codelab에서는 Push를 사용하여 모든 이벤트를 Cloud Logging에 로깅할 Cloud 함수에 보냅니다.

채널 서비스 알림을 Cloud 함수로 푸시

3a단계: Cloud 함수 만들기

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

Google Cloud Console의 Cloud Functions 섹션으로 이동합니다. Cloud Functions 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 함수가 배포되는 동안 다음 단계를 진행할 수 있습니다.

3b 단계: 구독 만들기

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

서비스 계정 사용자 인증 정보로 Pub/Sub API를 호출하여 이 작업을 수행할 수 있습니다. Cloud Channel API를 호출할 때 필요한 리셀러 도메인의 최고 관리자를 가장하지 않았는지 확인합니다.

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

Google Cloud Console 상단에서 Cloud Shell 활성화를 클릭합니다.
셸이 준비되면 다음 명령어를 실행합니다. SERVICE_ACCOUNT 값을 서비스 계정의 이메일 주소로, TOPIC를 2단계에서 만든 주제로 바꾸고 PUSH_ENDPOINT을 Cloud의 트리거 URL로 바꿉니다. 3a 단계에서 만든 함수는 다음과 같습니다.
```
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 구독 섹션으로 이동하여 정기 결제 설정이 설정되었는지 확인할 수 있습니다.

일부 데이터 생성

이전 단계를 완료하면 데이터를 받을 수 있습니다.

채널 서비스 콘솔에서 고객을 만들고 제품을 프로비저닝하는 가장 쉬운 방법입니다. 엔드 투 엔드 작업공간 프로비저닝 Codelab을 완료했으면 샘플 코드를 실행하여 Google 작업공간으로 고객을 만들 수 있습니다.

Google Cloud Console에서 함수로 이동하여 로그 탭을 엽니다. 다음은 확인 가능한 예입니다.

Pub/Sub 이벤트의 샘플 로그

정리

Cloud 함수 삭제
구독 삭제

주제에 남은 구독자가 없으면 주제가 자동으로 정리됩니다.

다음 단계

이 코드랩에서는 채널 서비스가 Pub/Sub를 활용하여 통일된 방식으로 통합을 구축하는 방법을 살펴보았습니다.

이벤트 참조

채널 서비스에서 생성된 이벤트 목록은 RPC 참조를 확인하세요.

API 참조

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

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

Pub/Sub 보증 및 권장사항

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

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

메시지가 지연되거나, 순서대로 정렬되거나, 여러 번 전송될 수 있으므로 엔드포인트는 idempotent등성이 있어야 하며 customers.get와 entitlements.get
푸시의 기본 Pub/Sub 제한 시간은 10초(Pub/Sub 구독의 ackDeadline를 통해 늘릴 수 있음)이지만 메시지 기반 아키텍처를 사용하여 엔드포인트가 가능한 한 빠르게 응답합니다.
엔드포인트가 다운되었거나 5xx 오류를 반환하면 Pub/Sub가 다시 시도합니다. Pub/Sub 문서에서 푸시를 통해 메시지를 수신하는 방법에 대한 자세한 정보를 확인할 수 있습니다.

pull을 사용하려는 경우 Pub/Sub 문서의 pull을 통해 메시지를 수신하는 방법에 대한 정보를 찾을 수 있습니다.

이벤트 필터링

채널 서비스의 알림에는 attributes가 포함되어 있으므로 Pub/Sub 필터링으로 특정 Pub/Sub 구독을 만들어 세분화된 구독을 만들 수 있습니다.

예를 들어 attributes.event_type = "LICENSE_ASSIGNMENT_CHANGED"로 필터링하면 모든 Google 작업공간 시트 변경사항을 추적할 수 있습니다.