애플리케이션의 백엔드 통합

이 섹션에서는 애플리케이션의 백엔드를 Google Cloud Marketplace와 통합하는 단계를 설명합니다. 이 통합을 통해 사용자가 Google Cloud Marketplace에서 제품을 구매했음을 나타내는 사용자 계정 및 자격을 관리할 수 있습니다. 사용량 기준 가격 책정 모델을 선택한 경우 백엔드를 통합하여 사용량을 Google에 보고합니다.

기본 애플리케이션을 Google Cloud Marketplace와 통합하는 예와 샘플코드 둘러보기는 관리 서비스 통합을 위한 codelab을 참조하십시오.

Codelab에 사용된 샘플 코드는 GitHub 저장소를 참조하세요.

시작하기 전에

  • 애플리케이션 통합: 설정에 설명된 대로 Cloud Commerce Partner Procurement API에 대한 액세스를 설정합니다.
  • 사용량 기준 가격 책정 방식을 선택한 경우, 사용량을 보고할 수 있는 서비스를 파트너 엔지니어가 만들었는지 확인합니다.

사용자 계정 작업

대략적으로 애플리케이션은 다음 시나리오를 처리해야 합니다.

  1. 사용자가 솔루션 등록과 같은 요청 또는 변경을 Google Cloud Marketplace에서 수행합니다.

  2. Google Cloud Marketplace는 Pub/Sub를 통해 eventType 필드의 요청 정보가 포함된 알림을 애플리케이션에 보냅니다. 예를 들어 사용자가 자격을 변경하면 eventTypeENTITLEMENT_PLAN_CHANGE가 됩니다.

    가능한 eventType의 전체 목록을 참조하세요.

  3. 요청을 승인하기 위해 애플리케이션은 Partner Procurement API에 HTTP POST 요청을 보냅니다.

다음 섹션에서는 사용자가 수행할 수 있는 요청 유형 및 애플리케이션이 요청을 처리하기 위해 수행해야 하는 작업을 설명합니다.

이 섹션에 설명된 API 호출에 대해 다음 엔드포인트를 사용합니다.

https://cloudcommerceprocurement.googleapis.com/

새 사용자를 위한 계정 만들기

사용자가 처음으로 솔루션을 구입하면 Google Cloud Marketplace가 사용자와 개발자와의 관계를 추적하는 계정 리소스를 만듭니다. 계정 리소스가 생성되면 생성된 Pub/Sub 주제를 통해 알림을 받습니다. Pub/Sub 메시지의 형식은 다음과 같습니다.

{
  "eventId": "...",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "..."
  }
}

여기서 USER_ACCOUNT_ID는 Google Cloud Marketplace에서 생성된 계정 ID입니다.

동시에 사용자가 등록 페이지로 연결되고, 여기에서 개발자 시스템의 계정을 만듭니다. 등록 페이지 만들기에 대한 자세한 내용은 애플리케이션의 프런트엔드 통합을 참조하세요.

사용자가 성공적으로 가입한 후 애플리케이션은 조달 API를 호출하고 계정이 승인되었음을 표시해야 합니다. 계정은 ACCOUNT_ACTIVE 상태로 작성되지만 signup라고 불리는 approvals 필드에 PENDING 항목이 있으며 이는 사용자가 아직 가입하지 않았음을 나타냅니다. 사용자가 가입한 후 계정을 승인하려면 다음 HTTP POST 요청을 사용하십시오.

POST v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID:approve {'approvalName': 'signup'}

여기서 YOUR_PARTNER_ID는 파트너 엔지니어가 Partner Procurement API에 대한 액세스를 사용 설정할 때 개발자에게 지정된 ID입니다.

연결된 계정의 상태를 확인하려면 다음 HTTP GET 요청을 사용하세요.

GET v1/providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID

응답은 다음 형식입니다.

{
  "name": "providers/YOUR_PARTNER_ID/accounts/USER_ACCOUNT_ID",
  "provider": "acme-services",
  "state": "ACCOUNT_ACTIVE",
  "approvals": [{
    "name": "signup",
    "state": "APPROVED",
    "updateTime": "...",
  }],
  "updateTime": "...",
  "createTime": "..."
}

가능한 계정 상태 목록은 providers.accounts API 참조를 참조하세요.

자격 만들기

고객이 소프트웨어 요금제를 선택하면 Google은 자격을 생성하여 고객이 Google Cloud Marketplace에서 솔루션을 구매했음을 나타냅니다.

고객이 요금제를 선택하면 다음 Pub/Sub 메시지가 애플리케이션으로 전송됩니다.

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_CREATION_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}

여기서 ENTITLEMENT_ID는 Google Cloud Marketplace에서 만든 ID입니다.

시스템에서 사용자가 요금제를 구입한 것이 반영되도록 사용자 계정을 업데이트합니다. 그런 다음 자격을 승인하기 위해 Partner Procurement API에 대해 HTTP POST 요청을 실행하고 승인 중인 ENTITLEMENT_ID를 보냅니다.

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approve

자격 요금제 변경

가격 책정 요금제를 설정한 방법에 따라 고객은 자신의 요금제를 변경할 수 있습니다. 고객이 새로운 가격 책정 요금제를 선택하면, 다음 형식의 Pub/Sub 메시지가 수신됩니다.

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_PLAN_CHANGE_REQUESTED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "newPlan": "ultimate",   // New plan
    "updateTime": "...",
  },
}

요금제 변경을 승인하려면 파트너 API에 다음 HTTP POST 요청을 작성하십시오.

POST v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID:approvePlanChange

요청 본문에는 승인 중인 요금제가 있어야 합니다.

{
  "pendingPlanName": PLAN_NAME
}

변경이 승인된 후에는 변경이 적용될 때 또 다른 Pub/Sub 메시지가 수신됩니다. 메시지에서 eventType 필드가 ENTITLEMENT_PLAN_CHANGED로 변경됩니다. 요금제 상태를 확인하려면 Partner Procurement API에 다음 HTTP GET 요청을 수행합니다.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

응답은 다음과 유사하며 state 필드는 새 요금제의 활성화 여부 또는 요금제 변경이 여전히 보류 중인지 여부를 나타냅니다.

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-server",
  "plan": "pro",
  "state": "ENTITLEMENT_PENDING_PLAN_CHANGE",
  "newPendingPlan": "ultimate",
  ...
}

사용자에게 상태 메시지 전송

사용자가 가격 책정 요금제를 선택한 시점과 백엔드가 자격을 승인한 시점 사이의 시간이 몇 시간 이상인 경우, 사용자에게 상태 메시지를 제공하는 것이 좋습니다. 이 메시지에서는 승인 진행 상태와 승인이 완료될 예상 시간을 표시합니다.

상태 메시지를 제공하려면 Procurement API에 다음 HTTP POST 요청을 수행합니다.

POST v1/providers/your-partner-id/entitlements/entitlement_id:updateUserMessage

요청 본문에서 다음 예와 비슷한 메시지 텍스트를 제공합니다.

{
  "message": "Approval expected in 2 days"
}

자격 취소

사용자가 자격을 취소하기로 결정하면 Pub/Sub 알림을 받습니다. 요금제 변경과 비슷하게, 실제 취소는 현재 청구 주기가 종료될 때 적용될 수 있습니다.

알림은 다음 형식입니다.

{
  "eventId": "...",
  // If the entitlement is cancelled at the end of the month,
  // eventType is ENTITLEMENT_PENDING_CANCELLATION
  "eventType": "ENTITLEMENT_CANCELLED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "cancellationDate": "...",
    "updateTime": "..."
  },
}

자격 삭제

사용자가 직접 요청을 수행하거나 Google 플랫폼을 떠나면, 사용자의 자격이 취소 및 삭제되고 계정이 삭제됩니다. 사용자의 개인정보 보호를 위해서는 알림을 받았을 때 서버에서 해당 데이터를 삭제해야 합니다.

자격이 취소되고 계정이 삭제되면 다음과 비슷한 알림이 수신됩니다.

{
  "eventId": "...",
  "eventType": "ENTITLEMENT_DELETED",
  "entitlement": {
    "id": "ENTITLEMENT_ID",
    "updateTime": "...",
  },
}
{
  "eventId": "...",
  "eventType": "ACCOUNT_DELETED",
  "account": {
    "id": "USER_ACCOUNT_ID",
    "updateTime": "...",
  },
}

계정 작업의 이벤트 유형 목록

다음은 앱이 Pub/Sub 메시지에서 받을 수 있는 eventType 목록입니다.

eventType설명
ACCOUNT_CREATION_REQUESTED지원 중단됨
ACCOUNT_ACTIVE고객의 계정이 생성되었음을 나타냅니다.
ACCOUNT_DELETED고객의 계정이 Google Cloud 시스템에서 삭제되었음을 나타냅니다.
ENTITLEMENT_CREATION_REQUESTED고객이 요금제 중 하나를 선택했음을 나타냅니다.
ENTITLEMENT_ACTIVE고객이 선택한 요금제가 활성화 되었음을 나타냅니다.
ENTITLEMENT_PLAN_CHANGE_REQUESTED고객이 새로운 요금제를 선택했음을 나타냅니다.
ENTITLEMENT_PLAN_CHANGED고객의 요금제 변경이 승인되었으며 변경 사항이 적용되었음을 나타냅니다.
ENTITLEMENT_PLAN_CHANGE_CANCELLED고객의 요금제 변경이 승인되지 않았거나 이전 요금제로 다시 전환되었기 때문에 취소되었음을 나타냅니다.
ENTITLEMENT_PENDING_CANCELLATION고객이 요금제를 취소했으며 결제 주기가 끝날 때까지 취소가 보류 중임을 나타냅니다.
ENTITLEMENT_CANCELLATION_REVERTED고객의 대기 중인 취소가 되돌려졌음을 나타냅니다. 취소는 완료된 후에는 취소를 되돌릴 수 없습니다.
ENTITLEMENT_CANCELLED고객의 요금제가 취소되었음을 나타냅니다.
ENTITLEMENT_CANCELLING고객의 요금제가 취소되고 있음을 나타냅니다.
ENTITLEMENT_DELETED고객의 요금제에 대한 정보가 Google Cloud Marketplace에서 삭제되었음을 나타냅니다.

(사용량 기반 가격 책정의 경우) Google에 사용량 보고

솔루션에 대해 사용량 기준 가격 책정을 선택한 경우, 애플리케이션의 사용량을 Service Control API에 보고해야 합니다.

파트너 엔지니어는 솔루션에 해당하는 서비스를 만들고 개발자의 서비스 계정에 해당 서비스에 대한 사용량을 보고할 수 있는 액세스 권한을 부여합니다.

Service Control에 대한 소개는 시작하기 가이드를 참조하세요.

자격이 생성되면, 다음 HTTP GET 요청을 사용하여 파트너 조달 API를 호출하여 usageReportingId을 검색해야 합니다.

GET v1/providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID

응답에는 다음 형식의 자격 관련 정보가 포함됩니다.

{
  "name": "providers/YOUR_PARTNER_ID/entitlements/ENTITLEMENT_ID",
  "provider": "YOUR_PARTNER_ID",
  "account": "USER_ACCOUNT_ID",
  "product": "example-messaging-service",
  "plan": "pro",
  "usageReportingId": "USAGE_REPORTING_ID",
  "state": "ENTITLEMENT_ACTIVATION_REQUESTED",
  "updateTime": "...",
  "createTime": "..."
}

사용량을 보고하려면 먼저 services.check API 호출을 작성하여 서비스 구성을 확인해야 합니다. 응답에서 checkErrors[] 객체가 비어 있으면 services.report API 호출을 수행하여 사용량 보고서를 보내십시오.

사용량 보고서는 Operation이며 가격 측정항목에 대한 MetricValueSet를 포함합니다. Operation에는 자격에서 USAGE_REPORTING_ID로 설정된 consumerId 필드도 포함됩니다.

다음은 고객이 사용중인 스토리지에 대한 정보를 보내는 example-messaging-service에 대한 사용량 보고서의 예입니다.

POST https://servicecontrol.googleapis.com/v1/services/example-messaging-service.gcpmarketplace.example.com:report
{
  "operations": [{
    "operationId": "1234-example-operation-id-4567",
    "operationName": "Hourly Usage Report",
    "consumerId": "USAGE_REPORTING_ID",
    "startTime": "2019-02-06T12:00:00Z",
    "endTime": "2019-02-06T13:00:00Z",
    "metricValueSets": [{
      "metricName": "example-messaging-service/UsageInGiB",
      "metricValues": [{ "int64Value": "150" }]
    }]
  }]
}

애플리케이션 사용량을 시간별로 보고해야 합니다. 사용량에 대한 startTimeendTime이 정확한지 확인하십시오. startTime 이전에 사용자 서비스가 사용중지된 경우 services.check API가 checkErrors[] 객체에서 오류를 전송하고 해당 기간 동안 고객에게 요금이 청구되지 않습니다.

services.check API가 다음 오류 중 하나 이상을 리턴하면 오류가 해결될 때까지 고객에게 서비스 제공을 중지하는 것이 좋습니다.

  • SERVICE_NOT_ACTIVATED
  • BILLING_DISABLED
  • PROJECT_DELETED