1. Authenticate
Prerequisites
- You should have registered in our developer portal. Check this link about how to register an Account.
- You should request access to the playground, sandbox and production environment using our Support page. Here is the link to support page to request access to our environments.
- You should have an App created in your account to get the client id and client secret. Check this link about how to create an App.
Note : The time data attribute on APIs follows a 24-hour clock starting at 00:00 and ending at 23:59.
Authentication
The bearer token obtained after successful authentication should be passed as credential when calling this API for authentication. Check the Access Token API link for instructions on how to generate your bearer token.
2. Permisssions
To Access PoP/POE room, the user must have "DCIM-enabled location data" permission. If you are unaware of your user permissions, contact your Account Administrator.
3. Get Information
Get Account Information
Master account Id and account Id need to be passed in the header for this API call. This is needed to indicate your legal entity.
Refer to the Accounts API for instructions on how to retrieve your account information. You may skip this step if you already know your master account Id and account Id.
Get Site Information
Retrieve the available facility information which are assigned to you. You need the site code to indicate to which facility you want to make a request.
Refer to the Sites API for instructions on how to retrieve your site information. You may skip this step if you already know your sites.
Get Location Information
Retrieve the available location information which are assigned to you. You need the location name to indicate to which location in the facility you want to make a request.
Refer to the Locations API for instructions on how to retrieve your location information. You may skip this step if you already know your locations.
4. Retrieve Device Controllers meta-data
| Method | GET |
|---|---|
| End point | /v1/dcim-devices/{locationId}/chart-metadata |
| Headers | Authorization, Master-Account-Id, Account-Id, Content-Type |
| Query Parameters | n/a |
| Body | n/a |
Sample Curl Request
curl --location --request GET'https://api.digitalrealty.com/v1/dcim-devices/{locationId}/chart-metadata' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \Headers
| Field Name | Mandatory | Type | Description |
|---|---|---|---|
| Master-Account-Id | true | string | Customer master account identifier. |
| Account-Id | true | string | Customer account identifier. |
| Authorization | true | string | Token-based authentication. |
| Content-Type | true | string | Indicates the request body format. value: [application/json] |
Query Parameters
n/a
Body
n/a
Sample JSON Response
[
{
"TDCID": "24",
"SubCategory": "PDU",
"DefaultFunctionAliasName": "kWTtl",
"DeviceFunctions": [
"AmpC",
"kWTtl",
"AmpB",
"AmpA",
"kVATtl"
],
"DisplayOrder": 47,
"TrendValueType": "AVG"
}
]Payload Description
| Field Name | Type | Description |
|---|---|---|
| TDCID | int | Index |
| SubCategory | string | Insite asset subcategory. |
| DefaultFunctionAliasName | string | When loading summary page, if this value exists in the insite record for this SubCatagory, use this function for summary page data. |
| DeviceFunctions | array | When in device detail chart, get all functions from insite record for this SubCatagory. |
| DisplayOrder | int | Numerical value that determines the display order of subcategories in the summary page. |
| TrendValueType | string | AVG or MAX is a parameter that is passed to the Get Trend data call. AVG returns average values from within the date intervals, whereas Max returns the Maximum value in a data interval. This helps display on/off data in a meaningful way. |
5. Retrieve Device Controllers chart-data
| Method | GET |
|---|---|
| End point | /v1/dcim-devices/{locationId}/chart-metadata |
| Headers | Authorization, Master-Account-Id, Account-Id, Content-Type |
| Query Parameters | n/a |
| Body | n/a |
Sample Curl Request
curl --location --request GET'https://api.digitalrealty.com/v1/dcim-devices/{locationId}/chart-metadata' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>' \
--header 'Content-Type: application/json' \Headers
| Field Name | Mandatory | Type | Description |
|---|---|---|---|
| Master-Account-Id | true | string | Customer master account identifier. |
| Account-Id | true | string | Customer account identifier. |
| Authorization | true | string | Token-based authentication. |
| Content-Type | true | string | Indicates the request body format. value: [application/json] |
Query Parameters
n/a
Body
n/a
Sample JSON Response
{
"StartDateTime": "2024-08-22T14:18:16Z",
"EndDateTime": "2024-08-29T14:18:16Z",
"Interval": "hour",
"PortalTrendData": [
{
"DeviceName": "TOR1_CR3_PDU-3/4C1",
"DeviceDataID": "2227427",
"FunctionName": "KW",
"FunctionUnits": "kW",
"TrendData": [
{
"PointValue": "152.51",
"PollDateTime": "2024-08-22 01:00:00",
"UTCPollDateTime": "2024-08-22 01:00:00",
"MinValue": "151.20",
"MaxValue": "154.00"
}
]
}
]
}Payload Description
| Field Name | Type | Description |
|---|---|---|
| StartDateTime | date-time | Data requested to start from the beginning of this day YYYY-MM-DD (UTC) at 00:00:00 hrs |
| EndDateTime | date-time | Data requested to stop at the end of this day YYYY-MM-DD (UTC) at 23:59:00 hrs |
| Interval | string | Interval must be determined based on DDiD count and Number of days using DataPointCount. Find the calculation details below the table. Minute: (minute interval data) 5 Minute: Data in 5-minute summaries 15 Minute: Data in 15-minute summaries Hour: Data in 60 min summaries Day: Data in Daily summaries |
| PortalTrendData | array | Array of device identification information, function information, and trend data array. Each field is described in detail in this table. |
| DeviceName | string | Name of device in DCIM. |
| DeviceDataID | Int | Unique id to retrieve a specific function's value. List of DDIDs and their associated functions and devices are provided as part of the onboarding process |
| FunctionName | string | Name of function mapped to each device. |
| FunctionUnits | string(enum) | Units of measure of the DCIM function. |
| TrendData | array | Array that includes poll date and time in both local and UTC formats, as well as the minimum, maximum, and actual point values. Each field is described in detail in this table. |
| PointValue | float | The data result of the Interval setting and Start/End time |
| PollDateTime | date-time | The timestamp that data was acquired in local data center time at |
| UTCPollDateTime | date-time | The timestamp that data was acquired in UTC at |
| MinValue | float | When interval is set to any value other than minute, returns the minimum value of the data array based upon our 1-minute data model |
| MaxValue | float | When interval is set to any value other than minute, returns the maximum value of the data array based upon our 1-minute data model |
Note :
Data Point Count
Data volume limiter calculation to determine interval and duration. There is a limit set for the combination of number of DDIDs, the date range and the data interval. i.e. you can ask for a long period of time for a single DDID, but it halves every time you double the number of DDIDs in a single call.
The calculation is Number of Datapoints per day X number of DDiDs X Number of Days requested = DatapointCount.
Limitations per interval:
- Day: 1350
- Hour: 15000
- 15 Minute: 50000
- 5 Minute: 60500
- 1 Minute: 60500
So as an example you can request 2 DDiDs of data at Day interval for just under 6745 days without an error or 42 DDIDs for 1 day at 5 Minute interval.
