Introduction
IBM Cloud® Usage Metering is a platform service that enables service providers to submit metrics collected for resource instances provisioned by IBM Cloud users. IBM and third-party service providers that are delivering an integrated billing service in IBM Cloud are required to submit usage for all active service instances every hour. This is important because inability to report usage can lead to loss of revenue collection for IBM, in turn causing loss of revenue share for the service providers.
The IBM Cloud Usage Metering API is mostly internal for IBM service providers like IBM Cloudant, API Connect, dashDB, with the exception of third party service providers. Before using the IBM Cloud Usage Metering API, users need the following prerequisite knowledge. Cloud computing, security, error handling, Webapp interaction, and alerts and monitoring.
SDKs for Java, Node, Python, and Go are available to make it easier to programmatically access the API from your code. The client libraries that are provided by the SDKs implement best practices for using the API and reduce the amount of code that you need to write. The tab for each language includes code examples that demonstrate how to use the client libraries. For more information about using the SDKs, see the IBM Cloud SDK Common project on GitHub.
Installing the Java SDK
Maven
<dependency>
<groupId>com.ibm.cloud</groupId>
<artifactId>usage-metering</artifactId>
<version>${version}</version>
</dependency>
Gradle
compile 'com.ibm.cloud:usage-metering:{version}'
View on GitHub https://github.com/IBM/platform-services-java-sdk
Installing the Node SDK
npm install @ibm-cloud/platform-services
View on GitHub
Installing the Python SDK
pip install --upgrade "ibm-platform-services"
View on GitHub
Installing the Go SDK
Go modules (recommended): Add the following import in your code, and then run go build
or go mod tidy
import (
"github.com/IBM/platform-services-go-sdk/usagemeteringv4"
)
Go get
go get -u github.com/IBM/platform-services-go-sdk/usagemeteringv4
View on GitHub
Prerequisites
- You must be approved to deliver an integrated billing service in IBM Cloud.
- You must have a registered service in the resource management console.
- Your pricing plan must be successfully published to the IBM Cloud catalog, and updated with prices for all chargeable metrics in the plans of the resource.
- Metering and rating definitions for all the plans in the resource have been verified.
Usage records
Usage records contain metrics that are accumulated over a small window of time. Depending on the metric, the accumulation window can be anywhere between 15 minutes to 24 hours. Service providers should ensure that the metrics are not accumulated with overlapping time windows. A usage record has the following fields.
Field Name | Description |
---|---|
resource_instance_id |
The ID of the resource instance as registered in the resource controller (the IBM Cloud provisioning layer) |
plan_id |
The contract by which the usage record should be aggregated and rated. |
start |
Time from which the usage was measured. This value is specified in milliseconds since epoch. |
end |
Time to which the usage was measured. This value is specified in milliseconds since epoch. |
region |
The service provider region in which the usage was measured. |
measured_usage |
An array of measures with its accumulated values. |
consumer_id |
Optional field. If aggregation is required at a consumer level, then this field is required. Having a value for consumer_id for any other reason might result in incorrect aggregation. The consumer_id is known only to the service provider. |
Guidelines
- The start time and end time represent the time range during which the measures were collected, and they are not dependent on the time at which the usage record is submitted to the metering APIs.
- Usage records are facts. After a usage record is created, its contents can't be altered. The metering service acknowledges with a location when a usage record is successfully created. If an error code is returned, see the error description for the actions that you might have to take.
- A usage record is uniquely identified by the signature
account_id/resource_group_id/resource_instance_id/consumer_id/plan_id/region/start/end
. After a usage record is processed, any other usage record with the same signature is rejected as a duplicate. - Usage records must be submitted within two days from the time at which the measurement was completed. Older usage records are rejected.
Submitting usage records
Metering supports submitting multiple usage records in one API call. A maximum of 100 usage records can be submitted per API call. When the HTTP response status code is 202
, the response body will include the acceptance status of every usage record. Any status other than 201
is accompanied with an error code and indicates that there is some problem with the usage record and was not accepted. See Error handling for the usage acceptance status codes and the necessary action that's required.
Best practices
- All service providers must submit usage every hour so that the end user doesn't see a delay between the time that the resource was used and the time that the cost is reflected in their accounts.
- Retry submission of usage records only if there was a genuine failure with the previous request. Do not resubmit usage records that were successfully accepted.
Aggregation levels
Usage is always aggregated to the service plan and pricing plan. For example, your service might have a standard
plan with a pricing plan of $0.80 per 1,000 API calls. Additional aggregations happen at the following three levels.
- Instance and consumer
- Resource group
- Account (Invoices are generated from the aggregated values in the account)
After an instance is provisioned, it has the same pricing plan for the entire billing period (month). The pricing plan is determined based on the date on which the instance is provisioned.
Endpoint URLs
The Usage Metering API uses the following global endpoint URL for all regions. When you call the API, add the path for each method to form the complete API endpoint for your requests.
https://billing.cloud.ibm.com
If you enabled service endpoints in your account, you can send API requests over the IBM Cloud® private network at the following base endpoint URLs. For more information, see Enabling VRF and service endpoints.
- Private endpoint URL for VPC infrastructure:
https://private.billing.cloud.ibm.com
- Private endpoint URLs for classic infrastructure:
- Dallas:
https://private.us-south.billing.cloud.ibm.com
- Washington DC:
https://private.us-east.billing.cloud.ibm.com
- Dallas:
Authentication
Authorization to the Usage Metering API is enforced by using an IBM Cloud Identity and Access Management (IAM) access token. The token is used to determine the actions that a user or service ID has access to when they use the API.
Obtaining an IAM token for an authenticated user or service ID is described in the IAM Identity Services API documentation.
To use the API, add a valid IAM token to the HTTP Authorization request header, for example, -H 'Authorization: Bearer <TOKEN>'
.
When you use the SDK, configure an IAM authenticator with the IAM API key. The authenticator automatically obtains the IAM access token for the API key and includes it with each request. You can construct an authenticator in either of two ways:
- Programmatically by constructing an IAM authenticator instance and supplying your IAM API key
- By defining the API key in external configuration properties and then using the SDK authenticator factory to construct an IAM authenticator that uses the configured IAM API key
In this example of using external configuration properties, an IAM authenticator instance is created with the configured API key, and then the service client is constructed with this authenticator instance and the configured service URL.
For more information, see the Authentication section of the IBM Cloud SDK Common documentation.
To call each method, you'll need to be assigned a role that includes the required IAM actions. Each method lists the associated action. For more information about IAM actions and how they map to roles, see Assigning access to account management services.
To retrieve your access token:
curl -X POST "https://iam.test.cloud.ibm.com/identity/token" --header 'Content-Type: application/x-www-form-urlencoded' --header 'Accept: application/json' --data-urlencode 'grant_type=urn:ibm:params:oauth:grant-type:apikey' --data-urlencode 'apikey=<API_KEY>'
Replace <API_KEY>
with your IAM API key.
Setting client options through external configuration
Example environment variables, where <SERVICE_URL>
is the endpoint URL and <API_KEY>
is your IAM API key
export USAGE_METERING_URL=<SERVICE_URL>
export USAGE_METERING_AUTHTYPE=iam
export USAGE_METERING_APIKEY=<API_KEY>
Example of constructing the service client
import {
"github.com/IBM/platform-services-go-sdk/usagemeteringv4"
}
...
serviceClientOptions := &usagemeteringv4.UsageMeteringV4Options{}
serviceClient, err := usagemeteringv4.NewUsageMeteringV4UsingExternalConfig(serviceClientOptions)
Setting client options through external configuration
Example environment variables, where <SERVICE_URL>
is the endpoint URL and <API_KEY>
is your IAM API key
export USAGE_METERING_URL=<SERVICE_URL>
export USAGE_METERING_AUTHTYPE=iam
export USAGE_METERING_APIKEY=<API_KEY>
Example of constructing the service client
import com.ibm.cloud.platform_services.usage_metering.v4.UsageMetering;
...
UsageMetering serviceClient = UsageMetering.newInstance();
Setting client options through external configuration
Example environment variables, where <SERVICE_URL>
is the endpoint URL and <API_KEY>
is your IAM API key
export USAGE_METERING_URL=<SERVICE_URL>
export USAGE_METERING_AUTHTYPE=iam
export USAGE_METERING_APIKEY=<API_KEY>
Example of constructing the service client
const UsageMeteringV4 = require('@ibm-cloud/platform-services/usage-metering/v4');
...
const serviceClient = UsageMeteringV4.newInstance({});
Setting client options through external configuration
Example environment variables, where <SERVICE_URL>
is the endpoint URL and <API_KEY>
is your IAM API key
export USAGE_METERING_URL=<SERVICE_URL>
export USAGE_METERING_AUTHTYPE=iam
export USAGE_METERING_APIKEY=<API_KEY>
Example of constructing the service client
from ibm_platform_services import UsageMeteringV4
...
service_client = UsageMeteringV4.new_instance()
HTTP status codes
HTTP Status Code | Descriptions |
---|---|
400 | The payload is in an incorrect format. |
401 | The IAM token that was used in the authorization header is invalid or expired. |
403 | The subject in the supplied token does not authorization to submit usage. Contact IBM representative to get access. |
413 | The number of usage records in the payload exceeds 100. |
|
Resubmit the usage record. If problem persists, contact your IBM representative. |
Usage acceptance status codes
Status Code | Action Required |
---|---|
400 | The usage record is not in a correct format. Possible reasons for this status include that the schema validation failed, the measures in the usage records are incorrect, or the start and end times do not fall between the provisioned and de-provisioned times. Fix the usage record and resubmit. |
404 | The metering definition has not been onboarded. Work with your IBM representative to check if the resource is onboarded, and resubmit the usage record. |
409 | The usage record is a duplicate. Do not retry. |
424 | The resource instance's metadata in the resource controller has some errors. Fix the resource instance details and resubmit usage. |
|
Resubmit the usage record. If problem persists, contact your IBM representative. |
Methods
Report Resource Controller resource usage
The Resource Controller is responsible for controlling and tracking the lifecycle of resources in an IBM Cloud account. Resources can mean anything from an instance of a service, or entities associated with an account. Report usage for these resource instances that were provisioned through the resource controller.
Report usage for resource instances that were provisioned through the resource controller.
Report usage for resource instances that were provisioned through the resource controller.
Report usage for resource instances that were provisioned through the resource controller.
Report usage for resource instances that were provisioned through the resource controller.
POST /v4/metering/resources/{resource_id}/usage
(usageMetering *UsageMeteringV4) ReportResourceUsage(reportResourceUsageOptions *ReportResourceUsageOptions) (result *ResponseAccepted, response *core.DetailedResponse, err error)
(usageMetering *UsageMeteringV4) ReportResourceUsageWithContext(ctx context.Context, reportResourceUsageOptions *ReportResourceUsageOptions) (result *ResponseAccepted, response *core.DetailedResponse, err error)
ServiceCall<ResponseAccepted> reportResourceUsage(ReportResourceUsageOptions reportResourceUsageOptions)
reportResourceUsage(params)
report_resource_usage(self,
resource_id: str,
resource_usage: List['ResourceInstanceUsage'],
**kwargs
) -> DetailedResponse
Request
Instantiate the ReportResourceUsageOptions
struct and set the fields to provide parameter values for the ReportResourceUsage
method.
Use the ReportResourceUsageOptions.Builder
to create a ReportResourceUsageOptions
object that contains the parameter values for the reportResourceUsage
method.
Path Parameters
The resource for which the usage is submitted. You can find this value as the Global catalog ID listed on the Brokers tab in Partner Center.
Example:
93d21e40-aafd-451c-a393-5273d09d056a
Usage information for a resource instance.
[
{
"start": 1485907200001,
"end": 1485910800000,
"region": "us-south",
"resource_instance_id": "crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::",
"plan_id": "database-lite",
"measured_usage": [
{
"measure": "QUERIES",
"quantity": 100
},
{
"measure": "STORAGE",
"quantity": 123.456
}
]
},
{
"start": 1485910800000,
"end": 1485910800000,
"resource_instance_id": "ed20abbe-8870-44e6-90f7-56d764c21127",
"plan_id": "database-lite",
"measured_usage": [
{
"measure": "instances",
"quantity": {
"previous": 0,
"current": 1
}
}
]
}
]
The ID of the instance that incurred the usage. The ID is a CRN for instances that are provisioned with the resource controller.
Example:
crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::
The ID of the pricing plan with which the instance's usage should be metered.
Example:
da40662d-2f72-4a19-8c79-8c77cf285e17
The time from which the resource instance was metered in the format milliseconds since epoch.
Example:
1485907200000
The time until which the resource instance was metered in the format milliseconds since epoch. This value is the same as start value for event-based submissions.
Example:
1485907200000
Usage measurements for the resource instance
The pricing region to which the usage must be aggregated. This field is required if the ID is not a CRN or if the CRN does not have a region.
Example:
us-south
If an instance's usage should be aggregated at the consumer level, specify the ID of the consumer. Usage is accumulated to the instance-consumer combination.
Example:
cf-application:ed20abbe-8870-44e6-90f7-56d764c21127
WithContext method only
A context.Context instance that you can use to specify a timeout for the operation or to cancel an in-flight request.
The ReportResourceUsage options.
The resource for which the usage is submitted.
Array of usage records.
Examples:[ { "start": 1485907200001, "end": 1485910800000, "region": "us-south", "resource_instance_id": "crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::", "plan_id": "database-lite", "measured_usage": [ { "measure": "QUERIES", "quantity": 100 }, { "measure": "STORAGE", "quantity": 123.456 } ] }, { "start": 1485910800000, "end": 1485910800000, "resource_instance_id": "ed20abbe-8870-44e6-90f7-56d764c21127", "plan_id": "database-lite", "measured_usage": [ { "measure": "instances", "quantity": { "previous": 0, "current": 1 } } ] } ]
- ResourceUsage
The ID of the instance that incurred the usage. The ID is a CRN for instances that are provisioned with the resource controller.
Examples:crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::
The plan with which the instance's usage should be metered.
Examples:example-corp-my-new-pricing-plan
The pricing region to which the usage must be aggregated. This field is required if the ID is not a CRN or if the CRN does not have a region.
Examples:us-south
The time from which the resource instance was metered in the format milliseconds since epoch.
Examples:1485907200000
The time until which the resource instance was metered in the format milliseconds since epoch. This value is the same as start value for event-based submissions.
Examples:1485907200000
Usage measurements for the resource instance.
- MeasuredUsage
The name of the measure.
Examples:STORAGE
For consumption-based submissions,
quantity
can be a double or integer value. For event-based submissions that do not have binary states, previous and current values are required, such as{ "previous": 1, "current": 2 }
.Examples:1
If an instance's usage should be aggregated at the consumer level, specify the ID of the consumer. Usage is accumulated to the instance-consumer combination.
Examples:cf-application:ed20abbe-8870-44e6-90f7-56d764c21127
The reportResourceUsage options.
The resource for which the usage is submitted.
Array of usage records.
Examples:[ { "start": 1485907200001, "end": 1485910800000, "region": "us-south", "resource_instance_id": "crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::", "plan_id": "database-lite", "measured_usage": [ { "measure": "QUERIES", "quantity": 100 }, { "measure": "STORAGE", "quantity": 123.456 } ] }, { "start": 1485910800000, "end": 1485910800000, "resource_instance_id": "ed20abbe-8870-44e6-90f7-56d764c21127", "plan_id": "database-lite", "measured_usage": [ { "measure": "instances", "quantity": { "previous": 0, "current": 1 } } ] } ]
- resourceUsage
The ID of the instance that incurred the usage. The ID is a CRN for instances that are provisioned with the resource controller.
Examples:crn:v1:bluemix:staging:database-service:us-south:a/1c8ae972c35e470d994b6faff9494ce1:793ff3d3-9fe3-4329-9ea0-404703a3c371::
The plan with which the instance's usage should be metered.
Examples:example-corp-my-new-pricing-plan
The pricing region to which the usage must be aggregated. This field is required if the ID is not a CRN or if the CRN does not have a region.
Examples:us-south
The time from which the resource instance was metered in the format milliseconds since epoch.
Examples:1485907200000
The time until which the resource instance was metered in the format milliseconds since epoch. This value is the same as start value for event-based submissions.
Examples:1485907200000
Usage measurements for the resource instance.
- measuredUsage
The name of the measure.
Examples:STORAGE
For consumption-based submissions,
quantity
can be a double or integer value. For event-based submissions that do not have binary states, previous and current values are required, such as{ "previous": 1, "current": 2 }
.Examples:1
If an instance's usage should be aggregated at the consumer level, specify the ID of the consumer. Usage is accumulated to the instance-consumer combination.
Examples:cf-application:ed20abbe-8870-44e6-90f7-56d764c21127
parameters
The resource for which the usage is submitted.
parameters
The resource for which the usage is submitted.
# Report usage for a mythical resource. # Use zero for quantities since this is only an example. event_time=`date +%s%3N` # Currenttime in ms since epoch # Build request body read -r -d '' REQUEST_BODY <<EOF [{ "resource_instance_id": "crn:v1:staging:public:cloudantnosqldb:us-south:a/f5086e3df886495991303628d21da513:3aafbbee-88e2-4d29-b144-9d267d97064c::", "plan_id": "da40662d-2f72-4a19-8c79-8c77cf285e17", "region": "us-south", "start": {event_time}, "end": {event_time}, "measured_usage": [ { "measure": "LOOKUP", "quantity": 0 }, { "measure": "WRITE", "quantity": 0 }, { "measure": "QUERY", "quantity": 0 }, { "measure": "GIGABYTE", "quantity": 0 } ] }] EOF curl -X POST -H "Authorization: {iam_token}" -H "Accept: application/json" -H "Content-Type: application/json" -d "{REQUEST_BODY}" "{base_url}/v4/metering/resources/{resource_id}/usage"
// Report usage for a mythical resource. // Use zero for quantities since this is only an example. resourceInstanceUsageModel := usagemeteringv4.ResourceInstanceUsage{ ResourceInstanceID: &resourceInstanceID, PlanID: &planID, Region: ®ion, Start: &startTime, End: &endTime, MeasuredUsage: []usagemeteringv4.MeasureAndQuantity{ usagemeteringv4.MeasureAndQuantity{ Measure: core.StringPtr("LOOKUP"), Quantity: core.Int64Ptr(0), }, usagemeteringv4.MeasureAndQuantity{ Measure: core.StringPtr("WRITE"), Quantity: core.Int64Ptr(0), }, usagemeteringv4.MeasureAndQuantity{ Measure: core.StringPtr("QUERY"), Quantity: core.Int64Ptr(0), }, usagemeteringv4.MeasureAndQuantity{ Measure: core.StringPtr("GIGABYTE"), Quantity: core.Int64Ptr(0), }, }, } reportResourceUsageOptions := usageMeteringService.NewReportResourceUsageOptions( resourceID, []usagemeteringv4.ResourceInstanceUsage{resourceInstanceUsageModel}, ) responseAccepted, response, err := usageMeteringService.ReportResourceUsage(reportResourceUsageOptions) if err != nil { panic(err) } b, _ := json.MarshalIndent(responseAccepted, "", " ") fmt.Println(string(b))
// Report usage for a mythical resource. // Use zero for quantities since this is only an example. MeasureAndQuantity lookupMeasure = new MeasureAndQuantity.Builder() .measure("LOOKUP") .quantity(Long.valueOf(0)) .build(); MeasureAndQuantity writeMeasure = new MeasureAndQuantity.Builder() .measure("WRITE") .quantity(Long.valueOf(0)) .build(); MeasureAndQuantity queryMeasure = new MeasureAndQuantity.Builder() .measure("QUERY") .quantity(Long.valueOf(0)) .build(); MeasureAndQuantity gbMeasure = new MeasureAndQuantity.Builder() .measure("GIGABYTE") .quantity(Long.valueOf(0)) .build(); List<MeasureAndQuantity> measures = new ArrayList<>(); measures.add(lookupMeasure); measures.add(writeMeasure); measures.add(queryMeasure); measures.add(gbMeasure); ResourceInstanceUsage resourceInstanceUsageModel = new ResourceInstanceUsage.Builder() .resourceInstanceId(resourceInstanceId) .planId(planId) .region(region) .start(startTime) .end(endTime) .measuredUsage(measures) .build(); ReportResourceUsageOptions reportResourceUsageOptions = new ReportResourceUsageOptions.Builder() .resourceId(resourceId) .resourceUsage(new java.util.ArrayList<ResourceInstanceUsage>( java.util.Arrays.asList(resourceInstanceUsageModel))) .build(); Response<ResponseAccepted> response = service.reportResourceUsage(reportResourceUsageOptions).execute(); ResponseAccepted responseAccepted = response.getResult(); System.out.println(responseAccepted);
// Report usage for a mythical resource. // Use zero for quantities since this is only an example. const measures = [{ measure: 'LOOKUP', quantity: 0, }, { measure: 'WRITE', quantity: 0, }, { measure: 'QUERY', quantity: 0, }, { measure: 'GIGABYTE', quantity: 0, }]; const resourceInstanceUsageModel = { resource_instance_id: resourceInstanceId, plan_id: planId, region: region, start: startTime, end: endTime, measured_usage: measures, }; const params = { resourceId: resourceId, resourceUsage: [resourceInstanceUsageModel], }; usageMeteringService.reportResourceUsage(params) .then(res => { console.log(JSON.stringify(res.result, null, 2)); }) .catch(err => { console.warn(err) });
# Report usage for a mythical resource. # Use zero for quantities since this is only an example. measures = [ { 'measure': 'LOOKUP', 'quantity': 0, }, { 'measure': 'WRITE', 'quantity': 0, }, { 'measure': 'QUERY', 'quantity': 0, }, { 'measure': 'GIGABYTE', 'quantity': 0, }, ] resource_instance_usage_model = { 'resource_instance_id': resource_instance_id, 'plan_id': plan_id, 'region': region, 'start': start_time, 'end': end_time, 'measured_usage': measures, } response_accepted = usage_metering_service.report_resource_usage( resource_id=resource_id, resource_usage=[resource_instance_usage_model]).get_result() print(json.dumps(response_accepted, indent=2))
Response
Response when usage submitted is accepted
Response body that contains the status of each submitted usage record.
Response when usage submitted is accepted.
Response body that contains the status of each submitted usage record.
- Resources
A response code similar to HTTP status codes.
The location of the usage.
The error code that was encountered.
A description of the error.
Response when usage submitted is accepted.
Response body that contains the status of each submitted usage record.
- resources
A response code similar to HTTP status codes.
The location of the usage.
The error code that was encountered.
A description of the error.
Response when usage submitted is accepted.
Response body that contains the status of each submitted usage record.
- resources
A response code similar to HTTP status codes.
The location of the usage.
The error code that was encountered.
A description of the error.
Response when usage submitted is accepted.
Response body that contains the status of each submitted usage record.
- resources
A response code similar to HTTP status codes.
The location of the usage.
The error code that was encountered.
A description of the error.
Status Code
Indicates that the submitted payload was successfully stored. The status of individual usage records is available as a part of the resources array, and it has one-to-one correspondence with the usage records in the payload. A status value of
201
indicates that they will be rated, and any other value indicates a failure.Schema validation failed for the payload.
The requesting service is unauthenticated.
The requesting service is not authorized to submit usage for the resource.
The resource definition was not found.
The payload is too large.
{ "resources": [ { "code": "schema_validation_failed", "status": 400, "message": "Schema validation failed for usage", "details": [ { "field": "data.resource_instance_id", "message": "is required", "value": { "start": 1501282845663, "end": 1501282845664, "region": "us-south", "plan_id": "04082014.ibm.node.default", "measured_usage": [ { "measure": "current_running_instances", "quantity": 1 }, { "measure": "current_instance_memory", "quantity": 1 } ] }, "type": "object" } ] }, { "status": 201, "location": "/v4/metering/resources/sdk-for-nodejs/usage/normalized/t%2F0001501468312892-0-0-1-0%2Fk%2F265d9d22597d4ee589138929093f1246" }, { "code": "invalid_usage", "status": 400, "message": "Usage cannot have an end date earlier than start date" }, { "code": "plan_not_found", "status": 404, "message": "Plan idonotexist not found in resource sdk-for-nodejs" }, { "code": "expired_usage", "status": 400, "message": "Usage should be submitted within 172800000ms" } ] }
{ "resources": [ { "code": "schema_validation_failed", "status": 400, "message": "Schema validation failed for usage", "details": [ { "field": "data.resource_instance_id", "message": "is required", "value": { "start": 1501282845663, "end": 1501282845664, "region": "us-south", "plan_id": "04082014.ibm.node.default", "measured_usage": [ { "measure": "current_running_instances", "quantity": 1 }, { "measure": "current_instance_memory", "quantity": 1 } ] }, "type": "object" } ] }, { "status": 201, "location": "/v4/metering/resources/sdk-for-nodejs/usage/normalized/t%2F0001501468312892-0-0-1-0%2Fk%2F265d9d22597d4ee589138929093f1246" }, { "code": "invalid_usage", "status": 400, "message": "Usage cannot have an end date earlier than start date" }, { "code": "plan_not_found", "status": 404, "message": "Plan idonotexist not found in resource sdk-for-nodejs" }, { "code": "expired_usage", "status": 400, "message": "Usage should be submitted within 172800000ms" } ] }
{ "errors": [ { "code": "schema_validation_failed", "message": "Schema validation failed for resource", "details": [ { "field": "data", "message": "is the wrong type", "value": { "payload": "Not a valid payload" }, "type": "array" } ] } ] }
{ "errors": [ { "code": "schema_validation_failed", "message": "Schema validation failed for resource", "details": [ { "field": "data", "message": "is the wrong type", "value": { "payload": "Not a valid payload" }, "type": "array" } ] } ] }
{ "errors": [ { "code": "authentication_failed", "message": "Invalid or no authorization header provided" } ] }
{ "errors": [ { "code": "authentication_failed", "message": "Invalid or no authorization header provided" } ] }
{ "errors": [ { "code": "authorization_failed", "message": "Authorization failed" } ] }
{ "errors": [ { "code": "authorization_failed", "message": "Authorization failed" } ] }
{ "errors": [ { "code": "provisioning_plan_not_found", "message": "Plan test-plan not found" } ] }
{ "errors": [ { "code": "provisioning_plan_not_found", "message": "Plan test-plan not found" } ] }
{ "errors": [ { "code": "payload_too_large", "message": "'Maximum of 100 usage records can be submitted per request'" } ] }
{ "errors": [ { "code": "payload_too_large", "message": "'Maximum of 100 usage records can be submitted per request'" } ] }
Report Cloud Foundry resource usage
Report usage for resource instances that were provisioned by using the Cloud Foundry provisioning broker.
POST /v1/metering/resources/{resource_id}/usage
Request
Path Parameters
The resource for which the usage is submitted. You can find this value as the Global catalog ID listed on the Brokers tab in Partner Center.
Example:
93d21e40-aafd-451c-a393-5273d09d056a
Usage information for a Cloud Foundry resource instance.
[
{
"start": 1485907200001,
"end": 1485910800000,
"region": "eu-gb",
"resource_instance_id": "793ff3d3-9fe3-4329-9ea0-404703a3c371",
"organization_id": "eu-gb:23250568-51e6-4fd4-b192-98b23a7a33dd",
"space_id": "0d02373e-0f30-4773-9c2d-969b12cbd89a",
"plan_id": "database-lite",
"measured_usage": [
{
"measure": "QUERIES",
"quantity": 100
},
{
"measure": "STORAGE",
"quantity": 123.456
}
]
},
{
"start": 1485907200001,
"end": 1485910800000,
"region": "us-south",
"resource_instance_id": "4ec8cc68-4a03-4dab-914e-e14359e4e44b",
"organization_id": "ibm:dys0:us-south:4a238800-7287-49dd-87f4-58d4cd136339",
"space_id": "cdfbc17d-edbc-4ff6-a572-e8c5e7003fd9",
"plan_id": "database-lite",
"measured_usage": [
{
"measure": "QUERIES",
"quantity": 10
},
{
"measure": "STORAGE",
"quantity": 12.34
}
]
}
]
The ID of the organization to which the instance belongs. If the usage is for the instance is in a public cloud region, then the organization ID format is
{mccp_region_name}:{guid}
. If the usage is for a syndicated instance, then the organization ID format is{mccp_region_id}:{guid}
.Example:
Public: us-south:102d9527-315a-4a71-afc2-068b1db6d68e Syndicated: ibm:dys0:us-south:e2566380-89cf-4c38-9290-7eb48cfca8f9
The ID of the space under which the instance is provisioned.
Example:
89f0839a-812c-4180-8494-a453514c55e6
The ID of the instance provisioned using the Cloud Foundry service controller.
Example:
5ca426de-5091-4f2f-8d87-28d37e7ff711
The ID of the pricing plan with which the instance's usage should be metered.
Example:
da40662d-2f72-4a19-8c79-8c77cf285e17
The pricing region for the usage. For public regions, the region parameter value is the mccp region name in which the organization is present. For syndicated usage, use
us-south
.Example:
us-south
The time from which the resource instance was metered in the format milliseconds since epoch.
Example:
1485907200000
The time until which the resource instance was metered in the format milliseconds since epoch. This value is the same as start value for event-based submissions.
Example:
1485907200000
Usage measurements for the resource instance
If an instance's usage should be aggregated at the consumer level, specify the ID of the consumer. Usage is accumulated to instance-consumer combination.
Example:
cf-application:ed20abbe-8870-44e6-90f7-56d764c21127
Response
Response when usage submitted is accepted
Response body that contains the status of each submitted usage record.
Status Code
Indicates that the submitted payload was successfully stored. The status of individual usage records are available as a part of the resources array, and it has one-to-one correspondence with the usage records in the payload. A status value of
201
indicates that they will be rated, and any other value indicates a failure.Schema validation failed for the payload
The requesting service is unauthenticated.
The requesting service is not authorized to submit usage for the resource.
The resource definition was not found.
The payload is too large.
{ "resources": [ { "code": "schema_validation_failed", "status": 400, "message": "Schema validation failed for usage", "details": [ { "field": "data.organization_id", "message": "is required", "value": { "start": 1485907200001, "end": 1485910800000, "region": "eu-gb", "resource_instance_id": "793ff3d3-9fe3-4329-9ea0-404703a3c371", "plan_id": "database-lite", "measured_usage": [{ "measure": "QUERIES", "quantity": 10 }] }, "type": "object" } ] }, { "status": 201, "location": "/v1/metering/resources/sdk-for-nodejs/usage/normalized/t%2F0001501468312892-0-0-1-0%2Fk%2F265d9d22597d4ee589138929093f1246" }, { "code": "invalid_usage", "status": 400, "message": "Usage cannot have an end date earlier than start date" }, { "code": "plan_not_found", "status": 404, "message": "Plan idonotexist not found in resource sdk-for-nodejs" }, { "code": "expired_usage", "status": 400, "message": "Usage should be submitted within 172800000ms" } ] }
{ "errors": [ { "code": "schema_validation_failed", "message": "Schema validation failed for resource", "details": [ { "field": "data", "message": "is the wrong type", "value": { "payload": "Not a valid payload" }, "type": "array" } ] } ] }
{ "errors": [ { "code": "authentication_failed", "message": "Invalid or no authorization header provided" } ] }
{ "errors": [ { "code": "authorization_failed", "message": "Authorization failed" } ] }
{ "errors": [ { "code": "provisioning_plan_not_found", "message": "Plan test-plan not found" } ] }
{ "errors": [ { "code": "payload_too_large", "message": "'Maximum of 100 usage records can be submitted per request'" } ] }