Configure usage reporting to Google

If you choose usage-based pricing for your product, you must report your app's usage to the Service Control API .

For an introduction to Service Control, see the Getting Started Guide .

Before you begin

• Set up access to the Cloud Commerce Partner Procurement API, as described in Integrate your app .
• We recommend that you use Producer Portal to create a service account for use with Service Control.

(For usage-based pricing) Report usage

When an entitlement is created, you must call the Partner Procurement API to retrieve a usageReportingId , using the following HTTP GET request:

GET v1/providers/ YOUR_PARTNER_ID 
/entitlements/ ENTITLEMENT_ID 

The response contains information about the entitlement, in the following format:

 { 
  
 "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" 
 : 
  
 "..." 
 } 

To report usage, you must first make a services.check API call, to check the service's configuration. In the response, if the checkErrors[] object is empty, make a services.report API call to send the usage report.

The usage report is a Service Control API Operation . The following is an example of a usage report for example-messaging-service that sends information about the storage being used by the customer:

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" 
  
 }] 
  
 }], 
  
 "userLabels" 
 : 
  
 { 
  
 "cloudmarketplace.googleapis.com/resource_name" 
 : 
  
 "order_history_cache" 
 , 
  
 "cloudmarketplace.googleapis.com/container_name" 
 : 
  
 "storefront_prod" 
 , 
  
 "environment" 
 : 
  
 "prod" 
 , 
  
 "region" 
 : 
  
 "us-west2" 
  
 } 
  
 }] 
 } 

where:

• operationId is a unique string that your service instance generates. Use the same operationId for your check and report operations.
• consumerId is the same as the usageReportingId from the entitlement.
• startTime and endTime represent the start and end times of the total interval for the report Operation. In most cases, the startTime of a report Operation should have the same value as the endTime of the previous report Operation. If a customer's service is disabled before the startTime of a report Operation, the services.check API call sends an error in the checkErrors[] object, and the customer isn't charged for the corresponding interval.
• MetricValueSet contains one or more intermediate time intervals and corresponding updated metric values. You define your service's metrics when you choose and submit your pricing model . You view and reference the identifiers for your metrics in the Technical integrationsection of Producer Portal.
• userLabels are user-created labels, defined as key-value strings that follow specific syntax requirements . These labels are forwarded to Cloud Billing cost management tools for attribution. For recommendations related to usage labeling, see Best practices for usage labeling .

If the services.check API returns one or more of the following errors, we recommend that you stop providing your service to the customer until the error is resolved:

• SERVICE_NOT_ACTIVATED
• BILLING_DISABLED
• PROJECT_DELETED