Unlike the typical behavior considered in the Resource Counters integration procedure, some cloud applications expose API that on a resource usage request returns a set of charges for the resources used on the application side for the specified period. In this document, such data is called “vendor rated data”.
In this case, the APS type of the application that is responsible for the resource usage counting must implement
the RatedDataSupport
APS type considered in this document. Typically, it must be the same APS type that also
implements the SubscriptionService APS type. The APS resources instantiated from that APS type
in the platform are usually called either “tenant”, or “management context”, or “subscription service” and the
corresponding resources on the cloud application side are typically called “tenants”.
The implementation of RatedDataSupport
by an APS type of an APS application makes the platform
periodically poll the APS resources instantiated from that APS type. In those polls, the platform will call
the exportRatedData custom operation on those resources instead of calling
the retrieve operation.
In this document:
The considered APS type (download
) looks as follows:
{
"apsVersion": "2.0",
"name": "RatedDataSupport",
"id": "http://aps-standard.org/types/core/rated-data-support/1.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],
"properties": {
"terminationDate": {
"type": "string",
"format": "date-time",
"required": false
}
},
"operations": {
"exportRatedData": {
"verb": "GET",
"path": "/exportRatedData",
"parameters": {
"lastInvoiceDate": {
"kind": "query",
"type": "string",
"required": true
},
},
"response": {
"type": "object",
"properties": {
"lastInvoiceDate": {
"type": "string",
"format": "date",
"required": true,
"kind": "query"
},
"charges": {
"type": "array",
"items": {
"type": "object",
"properties": {
"accountId": {
"type": "string",
"required": true
},
"chargeType": {
"type": "string",
"enum": [
"COS",
"CHARGE",
"MSRP"
],
"required": true
},
"chargeId": {
"type": "string",
"required": false
},
"invoiceId": {
"type": "string",
"required": false
},
"amount": {
"type": "number",
"required": true
},
"poNumber": {
"type": "string",
"required": false
},
"totalCost": {
"type": "number",
"required": true
},
"currencyCode": {
"type": "string",
"required": true
},
"unitOfMeasure": {
"type": "string",
"required": false,
"default": "unit"
},
"unitPrice": {
"type": "number",
"required": false
},
"skuId": {
"type": "string",
"required": false
},
"description": {
"type": "string",
"required": false
},
"chargeStartDate": {
"type": "string",
"format": "date",
"required": false
},
"chargeEndDate": {
"type": "string",
"format": "date",
"required": false
},
"hash": {
"type": "string",
"required": false
}
}
}
}
}
}
}
}
}
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
GET |
/exportRatedData |
Object |
Return rated data generated on the application side for a period starting from the specified date. |
HTTP Request
GET /aps/2/resources/{aps-id}/exportRatedData?lastInvoiceDate=<start-date>
"APS-Account-Hierarchy" : "List of APS ID of every account in the hierarchical chain starting from the provider"
lastInvoiceDate
- start date of the requested period in the format of YYYY-MM-DD, for example, 2018-09-30
APS-Account-Hierarchy
HTTP header - a string containing comma-separated APS IDs of the provider and all subsidiary
resellers in the chain that leads to the customer, for example:
“d257f87a-4bff-43ab-9ff7-11e217f3b93e, b3325a5f-3644-4d47-a936-0ec77c8e1e15, a3cab1f8-04b2-4ce6-a696-a956dd8f9071”
In the example, the first APS ID belongs to the provider, then goes the customer’s parent reseller, and finally the customer itself.
Description
The operation is called by the platform VRD collector service to get a set of charges from an application.
Returns
An object with the following structure:
{
"lastInvoiceDate": "<end-date>",
"charges": [
{<charge-1>},
{<charge-2>},
...
]
}
A charge is a structure containing the following properties:
NAME |
TYPE |
ATTRIBUTES |
DEFAULT |
DESCRIPTION |
---|---|---|---|---|
|
String |
Required |
Not applicable |
APS ID of an account consuming the application service or a reseller. |
|
String enum: “COS” | “CHARGE” | “MSRP” |
Required |
Not applicable |
Type of the rated data entity:
* “COS” - cost of service (how much it costs for the provider).
* “CHARGE” - charge for the used service (the final price for the specified account).
* “MSRP” - manufacturer’s suggested retail price.
|
|
String |
Not required |
“” |
Vendor specific charge ID, unique in scope of all charges reported by the application. |
|
String |
Not required |
“” |
Vendor specific invoice ID. It can be the same for several charges. |
|
Number |
Required |
Not applicable |
The used amount of the resource. |
|
String |
Not required |
“” |
Customer purchase order number is a reseller specific number assigned to a subscription through the sales order when creating the subscription. |
|
Number |
Required |
Not applicable |
Total sum for the resource usage in this charge. |
|
Enum string |
Required |
Not applicable |
Currency code in accordance with ISO 4217, for example, “USD”. |
|
String |
Not required |
“” |
Vendor specified unit of resource measure. |
|
Number |
Not required |
0 |
Price per resource |
|
String |
Not required |
“” |
Vendor specific SKU assigned to the charged service component. |
|
String |
Not required |
“” |
Charge description given by the vendor. |
|
String in the form of date-time. |
Not required |
“” |
Start date of the period charged by the vendor. |
|
String in the form of date-time. |
Not required |
“” |
End date of the period charged by the vendor. |
|
String no longer than 255 symbols |
Not required |
“” |
If used, the application must guarantee the uniqueness of the value in scope of all generated charges. For example, it can be the MD5 hash of the charge JSON structure. |