Fetching a service usage using a stored report

Important

This chapter describes only how to work with json_v2_0 format.

JSON object structure of an API v2 compatible JSON report

Name	Value type	Description
`params`	report data object	An object that contains report-specific parameters and data.
`tenants`	array of tenant service usage objects	An array of objects that contain usage of a specific service of a tenant.

JSON object structure of a report data

Name	Value type	Description
`kind`	number	Kind of the report. See list of available report kinds.
`gen_date`	number	Date when the report was generated represented as UNIX timestamp.
`begin_date`	number	Date when the report starts represented as UNIX timestamp.
`end_date`	number	Date when the report ends represented as UNIX timestamp.
`group_id`	number	API v1 ID of the tenant.
`name`	string	The name of the tenant.
`report_level`	number	Level of report detail. See list of report levels.
`report_type`	number	Kind of report. See list of report kinds.

Available report levels (enum)

Value	Description
1	The report will include direct customers and partners.
2	The report will include all customers and partners.
3	The report will include all customers and partners (including user account details).
4	The report will include all partners.

Available report kinds (enum)

Value	Description
4	This kind of report will contain the service usage metrics day-by-day for provided period.
5	This kind of report will contain the service usage metrics for the end of the specified period, and the difference between the metrics in the beginning and at the end of the specified period. The usage information is actual for 23:59:59 UTC of the start date and the end date of the selected time period.
8	This kind of report will contain current service usage metrics. The usage metrics are calculated within each of the child tenants’ billing periods. If the tenants included in the report have different billing periods, the parent tenant’s usage may differ from the sum of the child tenants’ usages. The usage information is actual for 23:59:59 UTC of the previous day.
9	This kind of report will contain the service usage metrics and their changes for each day of the specified period. The usage information is actual for 23:59:59 UTC of each of the days of the selected time period.

JSON object structure of a tenant service usage

Name	Value type	Description
`application`	service object	The service that is related to this usage.
`date`	number	Date when the collection of this usage was ended.
`infra`	storage object	The information about storage related to this usage.
`is_range`	boolean	Flag, that specifies if this usage is measured for a specified billing period.
`measurement_unit`	string	The unit of measurement. Refer to the list of available measurement units
`name`	string	The name of the usage.
`pricing`	billing information object	An object that contains billing information of this usage.
`quota`	quota object	An object that contains usage quota value.
`tenant`	tenant object	An object that contains information about the tenant related to this usage.
`usage`	usage statistics object	An object that contains statistics of the usage.
`sku`	string	A product SKU.

JSON object structure of a billing information

Name	Value type	Description
`currency`	string	The currency used for pricing.
`mode`	string	The pricing mode of a tenant. The available pricing modes are `production` and `trial`.
`price`	number	The price per measurement unit of the usage.
`total_cost`	number	The overall cost of the usage.

JSON object structure of a usage statistics

Name	Value type	Description
`absolute`	statistics object	Absolute usage for the end of report period.
`delta`	statistics object	Delta usage between report period start date and report period end date.
`effective`	statistics object	Effective usage value for the end of report period. For non-range usages equals to the value on the end of report period (`absolute` value), for range usages – to `delta` value.

JSON object structure of a statistics

Name	Value type	Description
`production`	number	Value of the usage collected from tenants in production mode.
`total`	number	Total value of the usage collected from all tenants.
`trial`	number	Value of the usage collected from tenants in trial mode.

Step-by-step procedure

Authenticate to the cloud platform via the Python shell.

The following variables should be available now:

>>> base_url  # the base URL of the API
'https://eu2-cloud.acronis.com/api/2'
>>> auth  # the 'Authorization' header value with the access token
{'Authorization': 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6ImMwMD...'}
>>> tenant_id  # the UUID of the tenant to which the token provides access
'ede9f834-70b3-476c-83d9-736f9f8c7dae'

Fetch the UUID of the report as described in “Fetching a usage report”. As the result, the following variable with the report UUID should be available:
```
>>> report_id
'20dffb36-d77b-45c6-b2fa-39276e98d5fc'
```
Fetch the UUID of the stored json_v2_0 report as described in “Fetching stored reports”. As the result, the following variable with the report UUID should be available:
```
>>> stored_report_id
'a10bd132-261d-47aa-b7c6-74d39bc2266b'
```

Send a GET request to the /reports/{report_id}/stored/{stored_report_id} endpoint:

>>> response = requests.get(f'{base_url}/reports/{report_id}/stored/{stored_report_id}', headers=auth)

Check the status code of the response:

>>> response.status_code
200

Status code 200 means that the request was successful and the response body contains the report in the JSON format.

A different status code means that an error has occurred. For the details, refer to “Status and error codes”.

Also, the response body contains the report object formatted as a JSON text. When converted to an object, it will look as follows:

>>> pprint.pprint(response.json())
{
    "params": {
        "kind": 5,
        "gen_date": 1580774400,
        "begin_date": 1579046400,
        "end_date": 1580515200,
        "group_id": 1318156,
        "name": "JohnDoe Tenant",
        "report_level": 3,
        "report_type": 5,
        "show_skus": true
    },
    "tenants": [
        {
            "application": {
                "id": "f9c5744e-bd1a-36b6-b0f0-ecd7483e1796",
                "name": "notary"
            },
            "date": 1635638400,
            "infra": {
                "id": null,
                "backend_type": null,
                "name": null,
                "owner_id": null
            },
            "is_range": false,
            "measurement_unit": "bytes",
            "name": "notary_storage",
            "pricing": {
                "currency": null,
                "mode": null,
                "price": null,
                "total_cost": null
            },
            "quota": {
                "value": null
            },
            "tenant": {
                "customer_id": null,
                "id": "ede9f834-70b3-476c-83d9-736f9f8c7dae",
                "kind": "partner",
                "name": "JohnSmith, Inc"
            },
            "usage": {
                "absolute": {
                    "production": 0,
                    "total": 0,
                    "trial": 0
                },
                "delta": {
                    "production": 0,
                    "total": 0,
                    "trial": 0
                },
                "effective": {
                    "production": 0,
                    "total": 0,
                    "trial": 0
                }
            },
            "sku": "SQ6AMSENS"
        },
        ...
    }
}