How to Guide | Digital Realty

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.

Read the Get Started documentation if you are unaware of your client credentials.

2. Permissions

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.

4. Retrieve DCIM Data (POST Method)

Add DCIM information

The method can be used to dcim values of the customers account.

Method	POST
End point	/v2/dcim
Headers	Authorization, Master-Account-Id, Account-Id
Query Parameters	n/a
Body	subset,ddids, profile

Sample Curl Request

curl --location --request POST 'https://api.digitalrealty.com/v2/dcim' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>'
--data-raw '{
    "ddids": "1744365,1744376",
    "profile": "TST10DemoID",
    "subset": 3
}'

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.

Body

Field Name	Mandatory	Type	Description
subset	false	integer	subset allows minor control of the response payload size Available values for subset subset=null subset=0 subset=1 subset=2 subset=3
ddids	true	string	Comma separated list of DCIM device id's.
profile	true	string	DCIM login credential to be provided by Digital Realty.

Query Parameters

n/a

Sample JSON Response for subset = null

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:37:00 PM",
            "functionName": "Total KVA",
            "functionAliasName": "'",
            "functionActive": 1,
            "functionUnits": "kVA",
            "commAlActive": 0,
            "deviceName": "S120_PDUA1",
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 0

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "commAlActive": 0,
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 1

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:37:00 PM",
            "commAlActive": 0,
            "functionRating": "300",
            "utcTimeStamp": "8/31/2023 4:37:00 PM",
            "isAnalogDigital": "Analog",
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 2

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "functionName": "Total KVA",
            "commAlActive": 0,
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 3

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:41:00 PM",
            "functionName": "Total KVA",
            "functionAliasName": "",
            "functionActive": 1,
            "functionUnits": "kVA",
            "commAlActive": 0,
            "deviceName": "S120_PDUA1",
            "functionRating": "300",
            "utcTimeStamp": "8/31/2023 4:41:00 PM",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "globalFunctionName": "kVATtl",
            "customerFunctionName": "",
            "standardisedUnits": "",
            "reportLabel": "",
            "workOrderNumber": "",
            "ID": 1744282
        }
    ]
}

Payload Description

Field Name	Type	Description
functionValue	decimal	The Instantaneous/current value of a device function.
timeStamp	string(date-time)	Time of last data pull in local data center time.
functionName	string(50)	Name of function mapped to each device.
functionAliasName	string(50)	Optional alternate name for the function. For clarity or re-using a function for an alternate purpose, the new name appears here.
functionActive	integer	Indicates if DCIM is actively polling this function.
functionUnits	string(enum)	Units of measure of the DCIM function.
commA1Active	integer	0=Normal, 1=DCIM has lost communication with device/source.
deviceName	string(50)	Name of device in DCIM.
functionRating	integer	Optional Rating for function. Range of this is from 0 to 9999.
utcTimeStamp	string(date-time)	UTC Timestamp.
isAnalogDigital	string	Analog
isInFunctionAlarm	integer	This flag that is set when a function (metric) in DCIM has had an alarm enrollment set AND the alarm condition is TRUE. It is intended to be an indicator for the customer to now when an alarm state is true.
globalFunctionName	string	Digital Standardized function name.
customerFunctionName	string	When in use, Customer’s name for function.
standardisedUnits	string	Digital standardized Units of Measure – refer to this instead of Units, when populated.
reportLabel	string	Internal Use only.
workOrderNumber	string	When populated, indicates that function is currently subject to maintenance or investigation.
ID	integer	DCIM internal ID that is a unique function identifier for a unique device.

5. Retrieve DCIM Data (Get Method)

Get DCIM information

The method can be used to dcim values of the customers account.

Method	GET
End point	/v2/dcim
Headers	Authorization, Master-Account-Id, Account-Id
Query Parameters	ddids, profile, subset
Body	n/a

Sample Curl Request

curl --location --request GET 'https://api.digitalrealty.com/v2/dcim?ddids=<ddids>&profile=<profile>' \
--header 'Master-Account-Id: <Master-Account-Id>' \
--header 'Account-Id: <Account-Id>' \
--header 'Authorization: Bearer <access_token>'

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.

Query Parameters

Field Name	Mandatory	Type	Description
ddids	true	string	Comma separated list of DCIM device id's, maximum of 220 ddid's can be submitted per request.
profile	true	string	DCIM login credential to be provided by Digital Realty.
subset	false	integer	subset allows minor control of the response payload size Available values for subset subset=null subset=0 subset=1 subset=2 subset=3

Body

n/a

Sample JSON Response for subset = null

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:37:00 PM",
            "functionName": "Total KVA",
            "functionAliasName": "'",
            "functionActive": 1,
            "functionUnits": "kVA",
            "commAlActive": 0,
            "deviceName": "S120_PDUA1",
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 0

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "commAlActive": 0,
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 1

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:37:00 PM",
            "commAlActive": 0,
            "functionRating": "300",
            "utcTimeStamp": "8/31/2023 4:37:00 PM",
            "isAnalogDigital": "Analog",
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 2

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "functionName": "Total KVA",
            "commAlActive": 0,
            "functionRating": "300",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "ID": 1744282
        }
    ]
}

Sample JSON Response for subset = 3

{
    "LiveDataPointValues": [
        {
            "functionValue": 53.00,
            "timeStamp": "8/31/2023 7:41:00 PM",
            "functionName": "Total KVA",
            "functionAliasName": "",
            "functionActive": 1,
            "functionUnits": "kVA",
            "commAlActive": 0,
            "deviceName": "S120_PDUA1",
            "functionRating": "300",
            "utcTimeStamp": "8/31/2023 4:41:00 PM",
            "isAnalogDigital": null,
            "isInFunctionAlarm": 0,
            "globalFunctionName": "kVATtl",
            "customerFunctionName": "",
            "standardisedUnits": "",
            "reportLabel": "",
            "workOrderNumber": "",
            "ID": 1744282
        }
    ]
}

Payload Description

Field Name	Type	Description
functionValue	decimal	The Instantaneous/current value of a device function.
timeStamp	string(date-time)	Time of last data pull in local data center time.
functionName	string(50)	Name of function mapped to each device.
functionAliasName	string(50)	Optional alternate name for the function. For clarity or re-using a function for an alternate purpose, the new name appears here.
functionActive	integer	Indicates if DCIM is actively polling this function.
functionUnits	string(enum)	Units of measure of the DCIM function.
commA1Active	integer	0=Normal, 1=DCIM has lost communication with device/source.
deviceName	string(50)	Name of device in DCIM.
functionRating	integer	Optional Rating for function. Range of this is from 0 to 9999.
utcTimeStamp	string(date-time)	UTC Timestamp.
isAnalogDigital	string	Analog
isInFunctionAlarm	integer	This flag that is set when a function (metric) in DCIM has had an alarm enrollment set AND the alarm condition is TRUE. It is intended to be an indicator for the customer to now when an alarm state is true.
globalFunctionName	string	Digital Standardized function name.
customerFunctionName	string	When in use, Customer’s name for function.
standardisedUnits	string	Digital standardized Units of Measure – refer to this instead of Units, when populated.
reportLabel	string	Internal Use only.
workOrderNumber	string	When populated, indicates that function is currently subject to maintenance or investigation.
ID	integer	DCIM internal ID that is a unique function identifier for a unique device.

Response Codes

Please check the Response Codes overview in case of any issues.

DCIM-v2 2.0.1

1. Authenticate

Prerequisites

Authentication

2. Permissions

3. Get Information

Get Account Information

4. Retrieve DCIM Data (POST Method)

Add DCIM information

Sample Curl Request

Headers

Body

Query Parameters

Sample JSON Response for subset = null

Sample JSON Response for subset = 0

Sample JSON Response for subset = 1

Sample JSON Response for subset = 2

Sample JSON Response for subset = 3

Payload Description

5. Retrieve DCIM Data (Get Method)

Get DCIM information

Sample Curl Request

Headers

Query Parameters

Body

Sample JSON Response for subset = null

Sample JSON Response for subset = 0

Sample JSON Response for subset = 1

Sample JSON Response for subset = 2

Sample JSON Response for subset = 3

Payload Description

Response Codes

Need Help?