Producer Portal을 사용하여 SaaS 솔루션을 Google Cloud Marketplace API와 통합 (Python)

1. 소개

Google Cloud Marketplace의 SaaS 솔루션은 위치에 관계없이 개발자의 인프라에서 실행되지만 Google에서 청구하는 소프트웨어 솔루션입니다.

이 Codelab에서는 Google Cloud Marketplace와 통합되는 기본 SaaS 솔루션을 설정하여 다음 작업을 실행합니다.

• 사용자가 샘플 솔루션에 가입하면 알림을 받습니다.
• 가입을 원하는 고객을 승인하고 데이터베이스에 추가합니다.
• 고객이 결제 요금제를 변경하거나 취소하려는 시나리오를 처리합니다.
• 사용 보고서를 Google에 전송합니다.

이 Codelab에서는 Google Cloud Marketplace 조달 및 서비스 제어 API에 익숙해질 수 있습니다. 이 가이드에서는 테스트를 위한 전체 제품 환경을 제공하지 않습니다.

2. 시작하기 전에

• 아직 사용 설정하지 않은 경우 Producer Portal을 사용하여 프로젝트에 Codelab을 사용 설정합니다.

Producer Portal에 바로 연결되는 링크는 다음과 같습니다.

https://console.cloud.google.com/producer-portal?project=YOUR_PROJECT_ID

코드랩을 사용 설정하려면 화면 오른쪽의 코드랩 패널에서 사용 설정을 클릭합니다.

• 다음 모듈을 사용하여 머신에 Python 3을 설치합니다.
• Python Google 클라이언트 API
• google-cloud-pubsub 클라이언트 라이브러리

Python 모듈을 설치하려면 다음 명령어를 사용합니다.

pip install --upgrade google-api-python-client google-cloud-pubsub

• 다음 명령어를 사용하여 이 Codelab의 GitHub 저장소를 클론하거나 다운로드합니다.

git clone https://github.com/googlecodelabs/gcp-marketplace-integrated-saas.git
cd gcp-marketplace-integrated-saas

ZIP 파일 다운로드

• GOOGLE_CLOUD_PROJECT 환경 변수를 이 프로젝트의 ID로 설정합니다.
• Linux:

export GOOGLE_CLOUD_PROJECT="YOUR_PROJECT_ID"

• Windows:

set GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

• 서비스 계정 saas-codelab에 Pub/Sub 편집자 역할을 부여합니다. 역할을 부여하고 관리하는 단계는 리소스에 대한 액세스 권한 부여, 변경, 취소를 참고하세요.
• 서비스 계정의 JSON 키를 만들고 다운로드합니다. 키를 만드는 단계는 서비스 계정 키 만들기 및 관리를 참고하세요.

주의: 샘플 코드를 GitHub 또는 Cloud Source Repositories와 같은 온라인 소스 저장소에 업로드하려면 이 키를 저장소에 업로드하지 마세요.

• GOOGLE_APPLICATION_CREDENTIALS 환경 변수를 다운로드한 파일의 전체 경로로 설정합니다.
• Linux:

export GOOGLE_APPLICATION_CREDENTIALS="[YOUR_MACHINE]/path/service-account-key.json"

• Windows:

set GOOGLE_APPLICATION_CREDENTIALS=[YOUR_MACHINE]/path/service-account-key.json

• Google Cloud Marketplace에서 샘플 솔루션을 보려면 Producer Portal로 이동하여 Codelabs 패널에서 Codelab 제품을 클릭합니다. https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab에서 솔루션에 직접 액세스할 수도 있습니다.
• Google Cloud 콘솔의 새 프로젝트에서 Partner Procurement API를 사용 설정합니다.

다음으로 샘플 솔루션의 백엔드를 설정합니다.

3. Google Cloud Marketplace와 통합

개략적으로 샘플 솔루션을 Google Cloud Marketplace와 통합하는 방법은 다음과 같습니다.

• Cloud Pub/Sub와 통합하여 사용자가 솔루션에 등록할 때와 같이 Google Cloud Marketplace에서 알림을 받습니다. 파트너 엔지니어가 Cloud Pub/Sub 주제를 만들며, 알림을 받으려면 이 주제를 구독해야 합니다.
• Partner Procurement API와 통합하여 신규 고객의 계정을 만듭니다. 사용자가 구독 요금제를 선택, 변경 또는 취소할 때 Partner Procurement API를 사용하여 계정을 업데이트합니다. API와 통합하려면 자체 클라이언트 라이브러리를 빌드해야 합니다.
• Google Service Control과 통합하여 사용량 정보를 보고합니다.

4. Cloud Pub/Sub 주제 구독

사용자가 구독 요금제를 선택하면 Cloud Pub/Sub 주제를 통해 Google Cloud Marketplace에서 알림을 받습니다.

Cloud Pub/Sub 주제의 메시지를 수신하려면 먼저 구독을 만들어야 합니다.

구독을 만들려면 create_subscription.py 스크립트를 사용합니다.

cd gcp-marketplace-integrated-saas/tools
python create_subscription.py

구독을 확인하려면 Cloud Console에서 Cloud Pub/Sub 대시보드를 엽니다.

https://console.cloud.google.com/cloudpubsub/subscriptions

테스트 정기 결제 요청 시도

이 샘플 앱을 사용자로 테스트하려면 https://console.cloud.google.com/marketplace/product/DEMO-YOUR_PROJECT_ID/isaas-codelab로 이동하여 Marketplace에서 Codelab 제품을 엽니다. Codelab 프로젝트가 선택되어 있는지 확인하고 구독 요금제를 선택합니다.

참고: 데모 제품에 표시된 가격은 샘플입니다. 선택한 요금제와 관계없이 솔루션에 대한 요금이 청구되지 않습니다.

요금제를 선택할 때 전송되는 Cloud Pub/Sub 메시지를 확인하려면 저장소에서 python3 디렉터리의 루트로 이동하여 다음 명령어를 실행합니다.

~/gcp-marketplace-integrated-saas/python3$ python -m impl.step_1_pubsub.app

Cloud Pub/Sub 메시지를 수신하는 샘플 코드를 보려면 https://github.com/googlecodelabs/gcp-marketplace-integrated-saas/blob/master/python3/impl/step_1_pubsub/app.py를 참고하세요.

Cloud Pub/Sub 메시지에서 eventType 필드는 메시지가 전송된 이유를 보여줍니다. 요금제를 선택하면 이전에 선택한 정기 결제 요금제를 나타내는 eventType: ENTITLEMENT_CREATION_REQUESTED 메시지가 표시됩니다.

이 스크립트가 실행되는 동안 요금제를 취소하면 eventType: ENTITLEMENT_CANCELLED에 대한 새로운 메시지가 표시됩니다.

위 샘플은 메시지를 승인하지 않습니다. 이렇게 하면 앱을 실행할 때마다 동일한 메시지를 수신하여 더 쉽게 테스트할 수 있습니다.

스크립트를 닫으려면 CTRL + \를 누릅니다.

5. 계정 요청 승인

이제 Google Cloud Marketplace에서 메시지를 수신할 수 있으므로 Google Cloud Marketplace 조달 서비스가 고객을 대신하여 생성하는 리소스를 처리해야 합니다.

첫 번째는 account 리소스입니다. 계정은 고객이 제품에 연결된 상태를 나타냅니다. 고객의 Google 계정과 서비스 계정 간의 관계를 매핑하려면 데이터베이스에 고객의 조달 계정 ID를 저장해야 합니다.

고객이 요금제를 선택하면 Google Cloud Marketplace에서 고객이 계정을 요청하고 있음을 알리는 Cloud Pub/Sub 알림을 보냅니다. 앱에서 요청을 승인해야 합니다. 이 Codelab에서는 Cloud Pub/Sub 메시지를 수신할 때 계정 요청을 승인합니다.

참고: 정식 버전 통합에서 Google Cloud Marketplace는 고객을 제품의 프런트엔드로 안내하며, 여기에서 고객은 계정 요청을 승인하기 전에 소프트웨어에 가입합니다. 최종 통합에서는 프런트엔드에서 가입 페이지도 설정해야 합니다. 앱의 프런트엔드 통합에 대한 자세한 내용은 Google Cloud Marketplace 문서를 참고하세요.

계정 정보 데이터베이스 만들기

이 Codelab에서는 고객 계정 및 구매를 추적할 수 있는 간단한 JSON 데이터베이스를 사용합니다.

이 샘플을 테스트하려면 워크스테이션의 아무 곳에나 빈 JSON 객체가 포함된 파일을 만드세요.

{}

PROCUREMENT_CODELAB_DATABASE 환경 변수를 이 파일의 전체 경로로 설정합니다.

• Linux:

export PROCUREMENT_CODELAB_DATABASE="YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json"

• Windows:

set PROCUREMENT_CODELAB_DATABASE=YOUR_MACHINE/path/EMPTY_JSON_OBJECT.json

데이터베이스를 읽고 쓰는 모듈은 python3/impl/database에 있습니다.

샘플 구현에서는 Google Cloud Marketplace와 두 개 이상의 제품을 통합하는 경우 확장할 수 있는 스키마를 사용합니다. 다음은 샘플 앱에서 Very Good 요금을 구독한 사용자의 데이터베이스 항목 예시입니다.

{
   "a2b3c4d5-b3f1-4dea-b134-generated_id":{
      "procurement_account_id":"generated-b3f1-4dea-b134-4a1d100c0335",
      "internal_account_id":"generated-45b7-4f4d-1bcd-2abb114f77de",
      "products":{
         "isaas-codelab":{
            "start_time":"2019-01-04T01:21:16.188Z",
            "plan_id":"very-good",
            "product_id":"isaas-codelab",
            "consumer_id":"project_number:123123345345"
         }
      }
   }
}

최종 구현에서는 고객의 Google Cloud Marketplace 계정을 자체 고객 리소스와 연결하기 위해 앱을 자체 데이터베이스와 연결해야 합니다.

계정 승인

계정 요청을 승인하려면 다음 명령어를 실행합니다.

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_2_account.app

계정을 승인하는 샘플 코드는 impl/step_2_account에 있습니다.

참고: 일반적인 통합에서 계정을 승인하면 고객이 프런트엔드를 통해 앱에 가입했음을 나타냅니다. 최종 구현에서는 가입 흐름을 통해서만 계정을 승인해야 합니다.

코드랩의 marketplaceui 디렉터리에는 인증된 JWT 토큰에서 조달 계정 ID를 표시하는 데모 페이지가 있습니다.

샘플 구현에서는 조달 API와의 상호작용을 처리하는 Procurement 클래스를 사용합니다. get_account() 및 approve_account() 메서드는 다음과 같습니다.

step_2_account/app.py

def _get_account_name(self, account_id):
    return 'providers/DEMO-{}/accounts/{}'.format(PROJECT_ID,
                                                  account_id)

def get_account(self, account_id):
    """Gets an account from the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().get(name=name)
    try:
        response = request.execute()
        return response
    except HttpError as err:
        if err.resp.status == 404:
            return None

def approve_account(self, account_id):
    """Approves the account in the Procurement Service."""
    name = self._get_account_name(account_id)
    request = self.service.providers().accounts().approve(
        name=name, body={'approvalName': 'signup'})
    request.execute()

이 Codelab의 경우 조달 서비스에서 제공업체 ID는 DEMO-YOUR_PROJECT_ID입니다. 여기서 YOUR_PROJECT_ID는 생성한 프로젝트입니다. Procurement API와 상호작용하는 동안 계정 이름은 다음 형식을 사용해야 합니다.

providers/DEMO-YOUR_PROJECT_ID/accounts/account-id

그런 다음 고객의 구매 기록인 사용 권한을 승인합니다.

6. 사용 권한 승인

고객이 Google Cloud Marketplace에서 구독 요금제를 선택하면 계정이 생성되고 즉시 새 자격 요청이 생성됩니다. 사용 권한은 서비스 구매를 나타냅니다. 고객이 서비스를 사용하려면 먼저 사용 권한 요청을 승인한 후 고객이 서비스를 사용할 수 있도록 설정해야 합니다.

샘플 앱이 eventType ENTITLEMENT_CREATION_REQUESTED이 포함된 Cloud Pub/Sub 메시지를 수신하면 권한이 승인되고 앱은 ENTITLEMENT_ACTIVE 메시지를 기다려 데이터베이스에 권한을 기록한 다음 고객의 리소스를 설정해야 합니다.

권장사항: 이미 승인한 계정에 대해서만 권한을 만드세요. 데이터베이스에 계정 기록이 없는 경우 새 권한을 만들지 마세요.

권한을 만들려면 다음 명령어를 실행합니다.

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_3_entitlement_create.app

권한을 승인하는 코드는 샘플 구현에 있습니다.

다음으로 고객이 구독 요금제 변경을 요청하는 상황을 처리합니다.

7. 사용 권한 변경 승인

서비스에 여러 요금제가 있는 경우 기존 요금제를 업그레이드하거나 다운그레이드하려는 고객의 요청을 처리해야 합니다.

서비스에 요금제가 하나만 있는 경우 취소된 구매 처리로 건너뜁니다.

혜택이 처음 활성화되는 경우와 요금제 변경 후 활성화되는 경우 간에는 기술적인 차이가 없습니다. 따라서 샘플 구현에는 두 경우 모두에 대해 공유되는 handleActiveEntitlement() 메서드가 있습니다. 이 메서드는 수신 메시지에서 권한 관련 이벤트를 확인합니다.

step_4_entitlement_change/app.py

def handleActiveEntitlement(self, entitlement, customer, accountId):
  """Updates the database to match the active entitlement."""

  product = {
      'product_id': entitlement['product'],
      'plan_id': entitlement['plan'],
  }

  if 'consumerId' in entitlement:
    product['consumer_id'] = entitlement['consumerId']

  customer['products'][entitlement['product']] = product

  self.db.write(accountId, customer)

다음 스니펫은 eventType가 ENTITLEMENT_PLAN_CHANGE_REQUESTED인지 ENTITLEMENT_PLAN_CHANGED인지 확인합니다.

step_4_entitlement_change/app.py

elif eventType == 'ENTITLEMENT_PLAN_CHANGE_REQUESTED':
  if state == 'ENTITLEMENT_PENDING_PLAN_CHANGE_APPROVAL':
    # Don't write anything to our database until the entitlement becomes
    # active within the Procurement Service.
    self.approveEntitlementPlanChange(id, entitlement['newPendingPlan'])
    return True

elif eventType == 'ENTITLEMENT_PLAN_CHANGED':
  if state == 'ENTITLEMENT_ACTIVE':
    # Handle an active entitlement after a plan change.
    self.handleActiveEntitlement(entitlement, customer, accountId)
    return True

최종 구현에서 권한이 ENTITLEMENT_ACTIVE 상태로 다시 전환되면 리스너 메서드는 변경사항을 반영하도록 데이터베이스를 업데이트하고 필요한 프로비저닝을 실행해야 합니다.

파트너 엔지니어와 함께 제품을 설정한 방식에 따라 결제 주기가 끝날 때까지 서비스의 다운그레이드나 취소가 허용되지 않을 수 있습니다. 이 경우 승인 후에도 요금제 변경이 계속 대기 중이지만 요금제 변경이 완료될 때까지 혜택이 ENTITLEMENT_ACTIVE 상태로 돌아가지 않습니다.

혜택 변경사항을 확인하고 승인하는 코드는 샘플 구현을 참고하세요.

다음으로 고객이 구매를 취소하는 상황을 처리합니다.

8. 취소된 구매 처리

고객은 구매를 취소할 수 있습니다. 파트너 엔지니어와 함께 제품을 설정한 방식에 따라 취소가 즉시 적용되거나 결제 주기가 끝날 때 적용될 수 있습니다.

고객이 구매를 취소하면 eventType ENTITLEMENT_PENDING_CANCELLATION이 포함된 메시지가 전송됩니다. 취소를 즉시 처리하도록 제품을 설정한 경우 eventType ENTITLEMENT_CANCELLED이 포함된 메시지가 곧 전송됩니다.

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_CANCELLED':
  # Clear out our records of the customer's plan.
  if entitlement['product'] in customer['products']:
    del customer['products'][entitlement['product']]

  ### TODO: Turn off customer's service. ###
  self.db.write(accountId, customer)
  return True

elif eventType == 'ENTITLEMENT_PENDING_CANCELLATION':
  # Do nothing. We want to cancel once it's truly canceled. For now it's
  # just set to not renew at the end of the billing cycle.
  return True

elif eventType == 'ENTITLEMENT_CANCELLATION_REVERTED':
  # Do nothing. The service was already active, but now it's set to renew
  # automatically at the end of the billing cycle.
  return True

서비스는 ENTITLEMENT_CANCELLED 메시지를 기다린 후 데이터베이스에서 권한을 삭제하고 고객의 서비스를 사용 중지해야 합니다.

권한이 취소되면 Google 시스템에서 삭제되고 eventType ENTITLEMENT_DELETED 메시지가 전송됩니다.

step_5_entitlement_cancel/app.py

elif eventType == 'ENTITLEMENT_DELETED':
  # Do nothing. Entitlements can only be deleted when they are already
  # cancelled, so our state is already up-to-date.
  return True

권한을 취소하는 코드는 샘플 구현을 참고하세요.

9. 사용량 보고서 보내기

일부 서비스에는 사용량 기반 구성요소가 있으며, Google은 고객에게 올바른 금액을 청구하기 위해 고객의 서비스 사용에 대해 알아야 합니다. 서비스는 Google Service Control API를 통해 사용량을 보고해야 합니다.

서비스에 사용량 기반 구성요소가 없는 경우 이 섹션을 건너뛰세요.

사용 보고서 전송에 관한 자세한 내용은 온보딩 문서를 참고하세요.

사용량 보고서는 Google Service Control API에 매시간 전송해야 합니다. 이 Codelab에서는 크론 작업으로 예약할 수 있는 스크립트를 사용하여 보고서를 전송합니다. 스크립트는 마지막 사용량 보고 시간을 데이터베이스에 저장하고 이를 사용량 측정의 시작 시간으로 사용합니다.

스크립트는 서비스의 각 활성 고객을 확인하고 고객 권한의 consumer_id 필드를 사용하여 Google Service Control에 사용량 보고서를 전송합니다. 그런 다음 스크립트는 고객의 데이터베이스 항목을 업데이트하여 last_report_time이 방금 전송된 사용 보고서의 종료 시간으로 설정되도록 합니다.

Google 서비스 컨트롤은 check 및 report의 두 가지 메서드를 노출합니다. 전자는 후자를 호출하기 직전에 항상 호출해야 합니다. 전자에 오류가 있는 경우 오류가 수정될 때까지 고객의 서비스가 사용 중지되어야 합니다.

주어진 사용 권한의 모든 사용량이 단일 usageReportingId에 대해 청구됩니다. 하지만 SaaS 제품의 경우 이 사용량은 Google Cloud Billing의 [Charges not specific to a project] 항목과 연결됩니다. SaaS 제품이 고객의 조직 내에서 광범위하게 공유될 수 있고 비용 기여 분석을 지원하려는 경우 모든 서비스의 사용량 보고서 작업에 선택사항 userLabels 필드를 포함하는 것이 좋습니다.

Google Cloud Marketplace는 cloudmarketplace.googleapis.com/resource_name 및 cloudmarketplace.googleapis.com/container_name 라벨 키를 예약합니다. 이러한 라벨은 기본 서비스 및 리소스 계층 구조 내에서 사용의 컨텍스트를 포착하기 위한 것입니다. 이러한 리소스의 고객 할당 이름은 사용 보고서에 라벨 값으로 포함됩니다. 기본적으로 사용 보고서에 이러한 라벨을 포함하는 것이 좋습니다.

라벨 키	라벨 값	설명
cloudmarketplace.googleapis.com/resource_name	RESOURCE_NAME	사용량 측정항목과 연결된 리소스의 이름입니다.
cloudmarketplace.googleapis.com/container_name	CONTAINER_NAME	리소스 컨테이너의 이름입니다.

다음 스니펫은 데모 앱의 사용량을 보고 SaaS 제품의 사용량을 products_db라는 고객 할당 리소스에 귀속시킵니다. 이 Codelab에서는 service_name이 isaas-codelab.mp-marketplace-partner-demos.appspot.com입니다.

operation = {
  'operationId': '<UUID>',
  'operationName': 'Codelab Usage Report',
  'consumerId': 'project_number:<Project Number>',
  'startTime': '<Timestamp>',
  'endTime': '<Timestamp>',
  'metricValues': [{
      'int64Value': 100,
  }],
  'userLabels': {
    'cloudmarketplace.googleapis.com/container_name': 'saas-storage-solutions',
    'cloudmarketplace.googleapis.com/resource_name': 'products_db'
  }
}

service.services().report(
    serviceName=service_name, body={
        'operations': [operation]
    }).execute()
product['last_report_time'] = end_time
database.write(customer_id, customer)

전체 코드는 이 스크립트의 샘플 구현을 참고하세요. 샘플 사용 보고서를 만들려면 다음 명령어를 실행합니다.

~/gcp-marketplace-integrated-saas/python3$ python3 -m impl.step_6_usage_reporting.report isaas-codelab.mp-marketplace-partner-demos.appspot.com

10. 축하합니다.

SaaS 솔루션을 Google Cloud Marketplace와 통합하여 고객 계정 및 권한을 처리하고 서비스에 대한 사용량을 보고하는 방법을 알아보았습니다. 전체 통합 단계는 백엔드 통합 문서를 참고하세요.

도움말: 구독 흐름을 다시 시도하려면 reset_account 스크립트를 실행하여 계정의 승인 및 권한을 재설정하세요. 스크립트를 실행하기 전에 서비스 계정에 결제 계정 관리자 역할을 부여합니다.

~/gcp-marketplace-integrated-saas$ python3 tools/reset_account.py

계정 ID는 EMPTY_JSON_OBJECT.json 파일에서 확인할 수 있습니다.

삭제

더 이상 사용하지 않을 계획이라면 다음 리소스를 삭제하세요.

• Cloud Pub/Sub 구독
• 서비스 계정 및 키
• 선택사항: 생성한 프로젝트
• 선택사항: 생성한 결제 계정

다음 단계

프런트엔드 통합

이 Codelab의 샘플은 계정과 권한을 자동으로 승인합니다. 실제로 고객은 개발자가 만든 가입 페이지로 연결되어야 하며, 여기에서 개발자 시스템의 계정을 만들 수 있습니다. 사용자가 가입에 성공하면 API 요청을 통해 계정과 권한을 승인해야 합니다.

앱의 프런트엔드 통합에 대한 자세한 내용은 Google Cloud Marketplace 문서를 참고하세요.

SaaS 솔루션 제공에 대해 자세히 알아보기

Google Cloud Marketplace에서 SaaS 솔루션을 제공하는 개요는 SaaS 솔루션 제공을 참고하세요.