Fetching a service usage using a stored report

Important

This section 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. See 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.

To fetch service usage using a stored report

  1. Authenticate to the cloud platform via the Python shell.

    The following variables should be available now:

    >>> base_url  # the base URL of the API
    '<the data center URL>/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'
    
  2. 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'
    
  3. 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'
    
  4. 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)
    
  5. Check the status code of the response:

    >>> response.status_code
    200
    

    Status code 200 means that the request was successful.

    Note

    A different status code means that an error has occurred. For details of the error, see HTTP status response codes and API error codes.

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

    >>> 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"
            },
            ...
        }
    }