Accounts-accountId-products-productId-usage:GET
From Hostway API Documentation
(Difference between revisions)
Mike.robski (Talk | contribs) m (1 revision) |
Mike.robski (Talk | contribs) m (1 revision: Release 100) |
||
(3 intermediate revisions by 3 users not shown) | |||
Line 1: | Line 1: | ||
− | = GET /accounts/''{accountId}''/products/''{productId}''/usage?from=''{fromDate}''&to=''{toDate}'' = | + | = GET /accounts/''{accountId}''/products/''{productId}''/usage?from=''{fromDate}''&to=''{toDate}''&rate=''true'' = |
Get an aggregated services usage report of a product | Get an aggregated services usage report of a product | ||
Line 11: | Line 11: | ||
== Request == | == Request == | ||
− | <code>GET /accounts/''{accountId}''/products/''{productId}''/usage?from=''{fromDate}''&to=''{toDate}''</code> | + | <code>GET /accounts/''{accountId}''/products/''{productId}''/usage?from=''{fromDate}''&to=''{toDate}''&rate=''true''</code> |
==== Request Parameters ==== | ==== Request Parameters ==== | ||
− | ; accountId - ''string'' | + | ; accountId - ''string'' : The Id of the account. |
− | : The Id of the account. | + | ; productId - ''string'' : The Id of the product. |
− | + | ||
− | ; productId - ''string'' | + | |
− | : The Id of the product. | + | |
=== URI Parameters === | === URI Parameters === | ||
− | ; fromDate - ''string'' - ''required'' | + | ; fromDate - ''string'' - ''required'' : Start date of the usage report. Should be in '''YYYY-MM-DD''' format. The usage returned includes usage with dates from '''fromDate 00:00:00 UTC'''. ''fromDate'' must be older or equal to ''toDate''. |
− | : Start date of the usage report. Should be in '''YYYY-MM-DD''' format. The usage returned includes usage with dates from '''fromDate 00:00:00 UTC'''. ''fromDate'' must be older or equal to ''toDate''. | + | |
− | ; toDate - ''string'' - ''required'' | + | ; toDate - ''string'' - ''required'' : Start date of the usage report. Should be in '''YYYY-MM-DD''' format. The usage returned includes usage with dates to '''toDate 23:59:59 UTC'''. ''toDate'' must be older than today's date in UTC. |
− | : Start date of the usage report. Should be in '''YYYY-MM-DD''' format. The usage returned includes usage with dates to '''toDate 23:59:59 UTC'''. ''toDate'' must be older than today's date in UTC. | + | |
+ | ; rate - ''string'' - ''optional'' : If set to ''true'', the response will include the price for each usage. | ||
=== Request Headers === | === Request Headers === | ||
{{Authorization}} | {{Authorization}} | ||
Line 36: | Line 32: | ||
=== Status Code === | === Status Code === | ||
− | ;200 OK | + | ; 200 OK : Success. |
− | : Success. | + | |
− | ;400 Bad Request | + | ; 400 Bad Request : A request is considered ''bad'' any of the following situation is available: |
− | : A request is considered ''bad'' any of the following situation is available: | + | |
:: - '''fromDate''' or '''toDate''' URI parameter is missing; | :: - '''fromDate''' or '''toDate''' URI parameter is missing; | ||
:: - '''toDate''' is older than '''fromDate'''; | :: - '''toDate''' is older than '''fromDate'''; | ||
:: - today is older than or equal to '''toDate''' or '''fromDate'''; | :: - today is older than or equal to '''toDate''' or '''fromDate'''; | ||
− | ;403 Forbidden | + | ; 403 Forbidden : Forbidden access to regular accounts. Only Sales Agents have access to an ''usage'' resource. |
− | : Forbidden access to regular accounts. Only Sales Agents have access to an ''usage'' resource. | + | |
− | ;404 Not Found | + | ; 404 Not Found : The account Id or product Id was not found. |
− | : The account Id or product Id was not found. | + | |
=== Response Body === | === Response Body === | ||
<nowiki> | <nowiki> | ||
{ | { | ||
− | + | "list": [ | |
− | + | { | |
− | + | "instance": {instanceName}, | |
− | + | "amount" : {amount}, | |
− | + | "type": {usageType}, | |
− | + | "unit": {usageUnit}, | |
− | + | "ratedAmount": 0.95 | |
− | + | } ,..., | |
− | + | { | |
− | + | "instance": {instanceName}, | |
− | + | "amount": {amount}, | |
− | + | "type": {usageType}, | |
− | + | "unit": {usageUnit}, | |
− | "links" : [ | + | "ratedAmount": 10.00 |
− | "href" : "{{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31", | + | } |
− | + | ], | |
− | + | "links": [ | |
− | } | + | { |
− | + | "href": "{{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31", | |
+ | "rel": "self" | ||
+ | } | ||
+ | ] | ||
+ | }</nowiki> | ||
==== Parameters ==== | ==== Parameters ==== | ||
Line 85: | Line 81: | ||
;: unit - ''string'' | ;: unit - ''string'' | ||
::: measurement unit of the resource used | ::: measurement unit of the resource used | ||
+ | ;: ratedAmount - ''integer/float'' - (optional) | ||
+ | ::: the calculated price (charge) for the usage | ||
; links - ''list'' | ; links - ''list'' | ||
Line 144: | Line 142: | ||
| vpn.remote5 || hour || VPN uptime for 5 remote points | | vpn.remote5 || hour || VPN uptime for 5 remote points | ||
|- | |- | ||
− | | vpn.sitetosite || hour || VPN uptime for site-to-site access | + | | vpn.sitetosite || hour || VPN uptime for site-to-site access |
+ | |- | ||
+ | | hex2013.additionalquota * || mb|| Additional quota for HEX 2013 | ||
|} | |} | ||
+ | |||
+ | '''Note:''' The additional quota unlike the other usage types is not directly retrieved, but rather it is calculated with the following formula: | ||
+ | <nowiki> | ||
+ | CoSM = Count of standard mailboxes | ||
+ | QfSM = Quota for standard mailboxes | ||
+ | CoPM = Count of premium mailboxes | ||
+ | QfPM = Quota for premium mailboxes | ||
+ | |||
+ | Additional Quota = Quota - CoSM * QfSM - CoPM * QfPM</nowiki> | ||
== Examples == | == Examples == | ||
Line 153: | Line 162: | ||
<nowiki> | <nowiki> | ||
− | GET {{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31 | + | GET {{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31&rate=true |
</nowiki> | </nowiki> | ||
Line 164: | Line 173: | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.disk.10gb", | "type" : "vm.disk.10gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.0", | "instance" : "smith182278-Test-VM.0", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.disk.10gb", | "type" : "vm.disk.10gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0.95 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.3", | "instance" : "smith182278-Test-VM.3", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.disk.10gb", | "type" : "vm.disk.10gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.2", | "instance" : "smith182278-Test-VM.2", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.disk.10gb", | "type" : "vm.disk.10gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.4", | "instance" : "smith182278-Test-VM.4", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.disk.10gb", | "type" : "vm.disk.10gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.1", | "instance" : "smith182278-Test-VM.1", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.0", | "instance" : "smith182278-Test-VM.0", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.3", | "instance" : "smith182278-Test-VM.3", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 10.00 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.2", | "instance" : "smith182278-Test-VM.2", | ||
Line 209: | Line 226: | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 11.05 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.4", | "instance" : "smith182278-Test-VM.4", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 10.0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.7", | "instance" : "smith182278-Test-VM.7", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 10 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.6", | "instance" : "smith182278-Test-VM.6", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.memory.1gb", | "type" : "vm.memory.1gb", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0.5 | ||
}, { | }, { | ||
"instance" : "", | "instance" : "", | ||
"amount" : 6488, | "amount" : 6488, | ||
"type" : "vm.traffic.total", | "type" : "vm.traffic.total", | ||
− | "unit" : "mb" | + | "unit" : "mb", |
+ | "ratedAmount" : 0.99 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM", | "instance" : "smith182278-Test-VM", | ||
"amount" : 354, | "amount" : 354, | ||
"type" : "vm.traffic.in", | "type" : "vm.traffic.in", | ||
− | "unit" : "mb" | + | "unit" : "mb", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM", | "instance" : "smith182278-Test-VM", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.app.plesk", | "type" : "vm.app.plesk", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.1", | "instance" : "smith182278-Test-VM.1", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.cpu", | "type" : "vm.cpu", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.0", | "instance" : "smith182278-Test-VM.0", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.cpu", | "type" : "vm.cpu", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.3", | "instance" : "smith182278-Test-VM.3", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.cpu", | "type" : "vm.cpu", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM.2", | "instance" : "smith182278-Test-VM.2", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm.cpu", | "type" : "vm.cpu", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM", | "instance" : "smith182278-Test-VM", | ||
"amount" : 24, | "amount" : 24, | ||
"type" : "vm", | "type" : "vm", | ||
− | "unit" : "hour" | + | "unit" : "hour", |
+ | "ratedAmount" : 0 | ||
}, { | }, { | ||
"instance" : "smith182278-Test-VM", | "instance" : "smith182278-Test-VM", | ||
"amount" : 6134, | "amount" : 6134, | ||
"type" : "vm.traffic.out", | "type" : "vm.traffic.out", | ||
− | "unit" : "mb" | + | "unit" : "mb", |
+ | "ratedAmount" : 0 | ||
+ | }, { | ||
+ | "instance" : "smith182278-Test-VM", | ||
+ | "amount" : 1024, | ||
+ | "type" : "hex2013.additionalquota", | ||
+ | "unit" : "mb", | ||
+ | "ratedAmount" : 0 | ||
} ], | } ], | ||
"links" : [ { | "links" : [ { |
Latest revision as of 00:07, 19 November 2014
[edit] GET /accounts/{accountId}/products/{productId}/usage?from={fromDate}&to={toDate}&rate=true
Get an aggregated services usage report of a product
Products that currently generate usage data:
- FlexCloud Server
- Exchange 2010 Mailbox Archiving
- Exchange 2010 E-mail Encryption
Contents |
[edit] Request
GET /accounts/{accountId}/products/{productId}/usage?from={fromDate}&to={toDate}&rate=true
[edit] Request Parameters
- accountId - string
- The Id of the account.
- productId - string
- The Id of the product.
[edit] URI Parameters
- fromDate - string - required
- Start date of the usage report. Should be in YYYY-MM-DD format. The usage returned includes usage with dates from fromDate 00:00:00 UTC. fromDate must be older or equal to toDate.
- toDate - string - required
- Start date of the usage report. Should be in YYYY-MM-DD format. The usage returned includes usage with dates to toDate 23:59:59 UTC. toDate must be older than today's date in UTC.
- rate - string - optional
- If set to true, the response will include the price for each usage.
[edit] Request Headers
- Authorization - HTTP Authorization header [1]
- The Authentication credentials of the client application.
[edit] Request Body
None
[edit] Response
[edit] Status Code
- 200 OK
- Success.
- 400 Bad Request
- A request is considered bad any of the following situation is available:
- - fromDate or toDate URI parameter is missing;
- - toDate is older than fromDate;
- - today is older than or equal to toDate or fromDate;
- 403 Forbidden
- Forbidden access to regular accounts. Only Sales Agents have access to an usage resource.
- 404 Not Found
- The account Id or product Id was not found.
[edit] Response Body
{ "list": [ { "instance": {instanceName}, "amount" : {amount}, "type": {usageType}, "unit": {usageUnit}, "ratedAmount": 0.95 } ,..., { "instance": {instanceName}, "amount": {amount}, "type": {usageType}, "unit": {usageUnit}, "ratedAmount": 10.00 } ], "links": [ { "href": "{{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31", "rel": "self" } ] }
[edit] Parameters
- list - list
- a list of all services usage records. Each record consists of:
- instanceName - string
- name of a service instance
- usageType - string
- type of a resource used
- amount - integer
- used resouce amount
- unit - string
- measurement unit of the resource used
- ratedAmount - integer/float - (optional)
- the calculated price (charge) for the usage
- links - list
- Hypermedia for this resource. Links to self.
[edit] Usage Types
Usage types under monitoring are the following:
Type | Unit | Description |
---|---|---|
ipaddress | hour | Flexible IP address uptime |
loadbalancer | hour | Load Balancer uptime |
vm | hour | Virtual Machine uptime |
vm.app.office.2007.pro | hour | Virtual Machine uptime for Office 2007 Professional |
vm.app.office.2007.std | hour | Virtual Machine uptime for Office 2007 Standard |
vm.app.plesk | hour | Virtual Machine uptime for Plesk Control Panel |
vm.app.plesk.domain100 | hour | Virtual Machine uptime for 100 Plesk domains |
vm.app.plesk.powerpack | hour | Virtual Machine uptime for Plesk Powerpack |
vm.app.plesk.powerpack | hour | Virtual Machine uptime for Plesk Powerpack |
vm.app.sqlserver.std | hour | Virtual Machine uptime for SQL Server Standard Edition |
vm.app.sqlserver.web | hour | Virtual Machine uptime for SQL Server Web Edition |
vm.app.terminalservices.cal | hour | Virtual Machine uptime for 1 TS CAL |
vm.cpu | hour | Virtual Machine CPU uptime |
vm.disk.10gb | hour | Virtual Machine uptime for 10GB Disk Space |
vm.memory.1gb | hour | Virtual Machine uptime for 1GB of Memory |
vm.monitoring.port | hour | Virtual Machine uptime for Port Monitoring |
vm.monitoring.url | hour | Virtual Machine uptime for URL Monitoring |
vm.os.redhat | hour | Virtual Machine uptime for RedHat OS |
vm.traffic.in | mb | Virtual Machine Incoming Traffic |
vm.traffic.out | mb | Virtual Machine Outgoing Traffic |
vm.traffic.total | mb | Virtual Machine Total Traffic |
volume.disk.10gb | hour | Storage Volume uptime for 10GB of Space |
vpn | hour | VPN uptime |
vpn.remote5 | hour | VPN uptime for 5 remote points |
vpn.sitetosite | hour | VPN uptime for site-to-site access |
hex2013.additionalquota * | mb | Additional quota for HEX 2013 |
Note: The additional quota unlike the other usage types is not directly retrieved, but rather it is calculated with the following formula:
CoSM = Count of standard mailboxes QfSM = Quota for standard mailboxes CoPM = Count of premium mailboxes QfPM = Quota for premium mailboxes Additional Quota = Quota - CoSM * QfSM - CoPM * QfPM
[edit] Examples
[edit] GET call
Request
GET {{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31&rate=true
Response
HTTP/1.1 200 OK { "list" : [ { "instance" : "smith182278-Test-VM.1", "amount" : 24, "type" : "vm.disk.10gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.0", "amount" : 24, "type" : "vm.disk.10gb", "unit" : "hour", "ratedAmount" : 0.95 }, { "instance" : "smith182278-Test-VM.3", "amount" : 24, "type" : "vm.disk.10gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.2", "amount" : 24, "type" : "vm.disk.10gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.4", "amount" : 24, "type" : "vm.disk.10gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.1", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.0", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.3", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 10.00 }, { "instance" : "smith182278-Test-VM.2", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour" }, { "instance" : "smith182278-Test-VM.5", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 11.05 }, { "instance" : "smith182278-Test-VM.4", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 10.0 }, { "instance" : "smith182278-Test-VM.7", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 10 }, { "instance" : "smith182278-Test-VM.6", "amount" : 24, "type" : "vm.memory.1gb", "unit" : "hour", "ratedAmount" : 0.5 }, { "instance" : "", "amount" : 6488, "type" : "vm.traffic.total", "unit" : "mb", "ratedAmount" : 0.99 }, { "instance" : "smith182278-Test-VM", "amount" : 354, "type" : "vm.traffic.in", "unit" : "mb", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM", "amount" : 24, "type" : "vm.app.plesk", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.1", "amount" : 24, "type" : "vm.cpu", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.0", "amount" : 24, "type" : "vm.cpu", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.3", "amount" : 24, "type" : "vm.cpu", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM.2", "amount" : 24, "type" : "vm.cpu", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM", "amount" : 24, "type" : "vm", "unit" : "hour", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM", "amount" : 6134, "type" : "vm.traffic.out", "unit" : "mb", "ratedAmount" : 0 }, { "instance" : "smith182278-Test-VM", "amount" : 1024, "type" : "hex2013.additionalquota", "unit" : "mb", "ratedAmount" : 0 } ], "links" : [ { "href" : "{{APIBaseURL}}/accounts/smith182278/products/smith182278-0000013534cbbc0dc7182cea000aa37f798db0/usage?from=2012-01-01&to=2012-12-31", "rel" : "self" } ] }
[edit] See also