OpenManage Enterprise Power Manager RESTful API Guide version 1.1 June 2020 Rev.
Notes, cautions, and warnings NOTE: A NOTE indicates important information that helps you make better use of your product. CAUTION: A CAUTION indicates either potential damage to hardware or loss of data and tells you how to avoid the problem. WARNING: A WARNING indicates a potential for property damage, personal injury, or death. © 2019 - 2020 Dell Inc. or its subsidiaries. All rights reserved. Dell, EMC, and other trademarks are trademarks of Dell Inc. or its subsidiaries.
Contents Chapter 1: About this document.................................................................................................... 6 Chapter 2: Overview......................................................................................................................7 Introduction to Power Manager....................................................................................................................................... 7 RESTful application programming interface.......................
/api/PowerService/CapableGroups............................................................................................................................. 27 GET method for Representing Capable Groups...................................................................................................27 /api/PowerService/CapableGroups()/Devices................................................................................... 28 GET method for Representing All Devices from Capable Group............
Post method for creating a custom Power Manager Report...........................................................................
1 About this document This document contains information about the resource models for Dell EMC OpenManage Enterprise Power Manager. Each RESTful API specification includes the URI, method, parameters, request codes, and response codes. For OpenManage Enterprise RESTful API specifications, see OpenManage Enterprise and OpenManage Enterprise - Modular Edition RESTful API Guide .
2 Overview RESTful API support in Dell EMC OpenManage Enterprise Power Manager Power Manager supports RESTful API. APIs on these products enhances the systems management capabilities. The RESTful interface is provided over HTTPS in JSON format based on ODATA v4 usable by clients, scripts, and browser-based GUIs. The APIs enable you to build console management tools based on common programming and scripting languages such as Python, Java, and C.
JSON data Console API represents data using JSON. JSON is a lightweight data-interchange format that is readable and can also be easily parsed by machines. JSON is based on a subset of the JavaScript Programming Language. JSON uses a text format that is language independent but uses conventions familiar to programmers of the C-family of languages such as C, C++, C#, Java, JavaScript, PERL, and Python. These properties make JSON an ideal data-interchange language.
3 Key integration concepts This section describes the key integration concepts that are applicable to the use cases and resource model. Topics: • • • • • • • • • • • • • Base URI Security Authentication Authorization Resource addressing Resource operations Security considerations Data filtering Data sorting Data pagination Request headers Response codes Response headers Base URI REST API tree structure The console software provides a web-based hypermedia driven API using a simple folder structure.
Resource model https://[IP or DNS name]/api/$metadata Security To improve security, only HTTPS is supported. You can also update the SSL self-signed certificate with a custom certificate. For example, you can upload a PKCS-12 certificate or sign an application-generated Certificate Signing Request (CSR). Authentication Several common schemes are available for enabling authentication of REST requests. Basic Authentication and X-Auth-Token Authentication are some of the common schemes.
Authorization Table 1. Authentication and authorization requirements Actions Authentication required Authorization required Read operation on any instrumentation data Y Y Modify instrumentation data Y Y Invoke actions Y Y View service root N N View metadata document N N View OData service document N N View message registry Y N View Redfish version URI N N View JSONSchemaFile resource URI N/A N/A View JSON schemas URI N/A N/A OME Table 2.
Resource addressing Each managed resource must be uniquely addressable using a distinct URI. The URI syntax must be intuitive and should indicate the relationships with a parent resource. There are several ways to address specific resources either as instances of specific resource classes or within an associated parent context.
Data filtering The console software provides filtering options on certain URIs that return a collection of entities. Using this feature, the clients can extract a selected set of records using comparison operators on attributes of the model entity behind the collection. The relevant URI sections contain the information about the attributes and the operators that support filtering.
Get first four devices from the Device collection /api/DeviceService/Devices?$top=4 NOTE: For more information about $skip and $top, see OData Version 4.0 Part 1: Protocol at docs.oasis-open.org. Request headers The request header represents headers in the client HTTPS request that are used to communicate client-preferences to the service end point. The service provides the supported preference in the response header. The following table lists a few examples of request headers: Table 4.
Table 5. HTTP response codes (continued) Request Response code Service unavailable 503 - Service unavailable For more information about response codes, see Status Code Definitions on the W3.org website. Response headers The following table lists a few examples of response headers: Table 6. Examples of response headers Response Header Description Example Connection Control options for the current connection and list of hop-by-hop request fields.
4 Settings Topics: • • /api/PowerService/Settings /api/PowerService/Actions/PowerService.UpdateSettings /api/PowerService/Settings This URI represents the list of power settings. Supported versions of Power Manager: ● 1.1 ● 1.0 GET method for Power Service Settings To get power and temperature monitoring units, metric gathering interval, date range configuration for Top Energy Consumers widgets and Report settings. Description This method returns the list of settings that are configured.
}, { }, { }, { }, { } } "Name": "BUILT_IN_REPORT_TIME_INTERVAL", "DefaultValue": 90, "Value": 90 "@odata.type": "#PowerService.Settings", "Id": 6, "Name": "BUILT_IN_REPORT_TIME_GRANULARITY", "DefaultValue": 2, "Value": 2 "@odata.type": "#PowerService.Settings", "Id": 7, "Name": "TOP_ENERGY_CONSUMERS_DURATION","DefaultValue": 8, "Value": 8 "@odata.type": "#PowerService.Settings", "Id": 8, "Name": "DELETE_METRIC_DATA", "DefaultValue": 2, "Value": 2 "@odata.type": "#PowerService.
HTTP response codes Example 200 Input: { "Settings":[ { "Id": 1, "Value": 1 }, { "Id": 2, "Value": 1 }, { "Id": 3, "Value": 15 }, { "Id": 5, "Value": 90 }, { "Id": 6, "Value": 2 }, { "Id": 7, "Value": 8 }, { "Id": 8, "Value": 1 }, { "Id": 9, "Value": 2 } ] } Output: { "Status": true } Table 8.
Table 10. Power Display Unit Enumeration Enumeration Value Description 1 Watt 2 BTU/Hr Table 11. Metric Gathering Interval Enumeration Enumeration Value Description 15 15 Minutes 30 30 Minutes 60 60 Minutes Table 12. Built-in Report Time Interval Enumeration Enumeration Value Description 1 1 Day 7 7 Days 15 15 Days 30 30 Days 90 90 Days 180 180 Days 365 365 Days Table 13. Built In Report Time Granularity Enumeration Enumeration Value Description 1 1 Hour 2 1 Day Table 14.
Table 16.
5 Monitored Devices Topics: • • • /api/PowerService/Actions/PowerService.AddDevices /api/PowerService/Actions/PowerService.RemoveDevices /api/PowerService/MonitoredDevices /api/PowerService/Actions/ PowerService.AddDevices This URI is to add the device(s) to Power Manager. Supported versions of Power Manager: ● 1.1 ● 1.0 POST method to add Devices This method adds device(s) to Power Manager. Description Adds device(s) to Power Manager.
POST method to remove Monitored Devices This method removes device(s) from Power Manager. Description Removes device(s) from Power Manager. Privilege DEVICE_CONFIGURATION HTTP response codes 200 Example Input: { "Ids": [10128,10127] } Output: { "Status": "SUCCESS" } Table 18. Attributes Attribute Name Description Id Device Id(s) to be removed from the Power Manager NOTE: To remove all devices from Power Manager, provide value as -1.
{ EPRStatus" "@odata.type": "#PowerService.MonitoredDevice", "@odata.id": "/api/PowerService/MonitoredDevices(10079)", "Id": 10079, "DeviceName": "100.96.27.67", "ServiceTag": "DSFYSF2", "Type": 1000, "Model": "PowerEdge M630", "PowerState": 17, "ConnectionState": true, "HealthStatus": 1000, "ManagedState": 3000, "AddedOn": "2019-06-25 12:55:34.
License enumerations are defined in following table. Table 21. License Status Enumeration Enumeration Value Description 1 Active 2 Expired 3 Not Applicable Table 22.
Table 23.
6 Monitored Groups Topics: • • • • • • • /api/PowerService/Actions/PowerService.AddGroups /api/PowerService/Actions/PowerService.RemoveGroups /api/PowerService/CapableGroups /api/PowerService/CapableGroups()/Devices /api/PowerService/Groups()/Devices /api/PowerService/MonitoredGroups /api/PowerService/MonitoredGroups()/Devices /api/PowerService/Actions/PowerService.AddGroups This URI adds the group(s) to Power Manager. Supported versions of Power Manager: ● 1.1 ● 1.
● 1.0 POST method to remove Monitored Groups This method removes group(s) from Power Manager. Description Removes Group(s) from Power Manager Privilege GROUP_MANAGEMENT HTTP response codes 200 Example Input: { "Ids": [10131,10132] } Output: { "Status": "SUCCESS" } Table 25. Attributes Attribute Name Description Ids Device Id(s) to be removed. NOTE: To remove all groups from the Power Manager, provide the value as -1.
"@odata.context":"/api/$metadata#Collection(PowerService.CapableGroups)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.CapableGroups", "@odata.id": /api/PowerService/CapableGroups(10690)", "Id": 10690, "ParentId": 10689, "Name": "Aisle - A", "Description": "Aisle - A", "DeviceCount": 7, "PmPluginDeviceCount": 7, "Devices@odata.navigationLink":"/api/PowerService/CapableGroups (10690)/Devices" } ] } Table 27.
{ "@odata.context": "/api/$metadata#Collection(PowerService.Device)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.Device", "Id": 10069, "DeviceName": "SKCLUSN1.tejd.bdcsv.lab", "ServiceTag": "4xBzewP", "Type": 1000, "PowerState": 17, "ManagedState": 3000, "ConnectionState": true, "HealthStatus": 4000, "Model": "PowerEdge R940", "InWorkingSet": true, "IsPolicyCapable": true "IsAddedIndividually": true } ] } Table 29.
Privilege VIEW HTTP response codes 200 Example Input: None Output: { "@odata.context": "/api/$metadata#Collection(PowerService.Device)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.Device", "Id": 10069, "DeviceName": "SKCLUSN1.tejd.bdcsv.lab", "ServiceTag": "4xBzewP", "Type": 1000, "PowerState": 17, "ManagedState": 3000, "ConnectionState": true, "HealthStatus": 4000, "Model": "PowerEdge R940", "InWorkingSet": true, "IsPolicyCapable": true, "IsAddedIndividually": true } ] } Table 30.
Table 31. Filter (continued) Field Operator PowerState eq ManagedState eq ConnectionState eq HealthStatus eq IsAddedIndividually eq List of all the sort options that this method supports: ● ● ● ● ● ● ● ● ● ● Id DeviceName ServiceTag Model Type PowerState ManagedState ConnectionState HealthStatus IsAddedIndividually /api/PowerService/MonitoredGroups This URI represents groups which are monitored by the Power Manager. Table 32.
"ParentId": 10689, "Name": "Aisle - A", "Description": "", "AddedOn": "2019-06-10 19:05:42.413941", "DevicesInWorkingSet": 7, "TemperatureTriggeredPolicyExist: false" "Devices@odata.navigationLink": "/api/PowerService/ MonitoredGroups(10690)/Devices", "EPRStatus": { "@odata.id": "/api/PowerService/MonitoredGroups(10690)/ EPRStatus" }, "Policies@odata.navigationLink": "/api/PowerService/ MonitoredGroups(10690)/Policies" } ] } Table 33.
GET method for Representing All Devices from a MonitoredGroup This method represents all the device of a monitored group. Description Returns all the devices belongs to a Monitored group. Privilege VIEW HTTP response codes 200 Example Input: None Output: { "@odata.context": "/api/$metadata#Collection(PowerService.Device)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.Device", "Id": 10069, "DeviceName": "SKCLUSN1.tejd.bdcsv.
7 Power Policy Topics: • • • • • • • • • • • api/PowerService/PowerBounds /api/PowerService/Policies /api/PowerService/Policies() /api/PowerService/Policies()/PolicyDetails /api/PowerService/MonitoredDevices()/Policies /api/PowerService/MonitoredGroups()/Policies /api/PowerService/Actions/PowerService.CreatePolicy /api/PowerService/Actions/PowerService. EditPolicy /api/PowerService/Actions/PowerService.EnablePolicies /api/PowerService/Actions/PowerService.
NOTE: Only single entity ID is supported and pass only device ids. /api/PowerService/Policies This URI represents the power policies that are created Table 38. Filters Filter Name Description Top Required number of records Skip Number of records to skip. Default value is zero. Supported versions of Power Manager: ● 1.1 ● 1.0 GET method for retrieving Policies This method returns all the power policies. Description Returns all the power policies.
PolicyDetails" } } ] } "@odata.id": "/api/PowerService/Policies(30)/ Table 39. Attributes Attribute Name Description PolicyId ID of policy Name Name associated with the policy. Type Type of policy. Description Description associated with the policy Enabled Indicates if the policy is enabled or disabled AssignedTo Entity on which the policy is assigned to. CreatedTime Time at which the policy is created. ExecutionState State associated with the policy.
● ● ● ● AssignedTo CreatedTime Type IsAssociatedToGroup /api/PowerService/Policies() This URI represents a specific policy. Supported versions of Power Manager: ● 1.1 GET method for Policies() This method returns a specific policy. Description Returns details of a specific policy. Privilege VIEW HTTP response codes 200 Example Input: None Output: { "@odata.context": "/api/ $metadata#Collection(PowerService.PowerPolicy)", "@odata.count": 1, "value": [ { "@odata.
Table 43. Attributes (continued) Attribute Name Description Enabled Indicates if the policy is enabled or disabled. AssignedTo Entity on which the policy is assigned to. CreatedTime Time at which the policy is created. ExecutionState State associated with the policy. PolicyDetails Link to the detailed view of the policy. IsAssociatedToGroup The policy is associated to group or not. Table 44.
{ } "Id": 10070, "DeviceName": "100.96.25.126", "Type": 2000, "ServiceTag": "D89RG52", "PowerCapValue": 16670, "Ip": null } ], "Group": { "Id": 10132, "PowerCapValue": 16670, "TemperatureThreshold": 45, "Name": "DeviceGroup", "Description": "" } Table 45. Attributes Attribute name Description PolicyId ID of power policy. Name Name associated with the policy. Type Type of policy. Description Description associated with the policy. Enabled Indicates if the policy is enabled or disabled.
NOTE: The output Group object will have data only when the policy is created for group. /api/PowerService/MonitoredDevices()/ Policies This method returns policies that are created on the specific device. Supported versions of Power Manager: ● 1.1 ● 1.0 GET method for policies created on specified devices This URI returns the power policies that are created on the specified device. Description Returns all the power policies.
/api/PowerService/MonitoredGroups()/ Policies This URI returns the power policies that are created on the specified group. Supported versions of Power Manager: ● 1.1 ● 1.0 GET method for policies created on specified groups Description Returns all the power policies. Privilege VIEW HTTP response codes 200 Example Input: None Output: { "@odata.context": "/api/$metadata#Collection(PowerService.Policy)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.
/api/PowerService/Actions/ PowerService.CreatePolicy This method creates a policy. Supported versions of Power Manager: ● 1.1 ● 1.0 POST method for creating Policy This method creates a power policy.
Table 49. Attributes Attribute name Description Name Name associated with the policy. Description Description associated with the policy Enabled Indicates if the policy is enabled or disabled Schedule Indicates when the policy will be enabled StartTime Time at which the policy interval starts. EndTime Time at which the policy interval ends. StartDate Date from which the policy is active. EndDate Date until which the policy is active.
"Description": "Updated policy on group", "Enabled": true, "Schedule": { "StartTime": "", "EndTime": "", "StartDate": "2019-06-1", "EndDate": "2019-07-28", "DaysOfTheWeek": ["MON", "TUE", "WED", "FRI", "THU", "SAT", "SUN"] }, "Targets": [ { "Id": 10132, "PowerCapValue": 16663 }, { "Id": 10070, "PowerCapValue": 16663 } ] } Input to edit temperature-triggered policy: { "Id": 3, "Name": "Edited Temp Policy", "Description": "Edited Description", "Enabled": false, "Targets": [ { "Id": 10189, "TemperatureThreshol
Table 52. Output Attributes Attribute name Description Id ID of the power policy NOTE: All targets and corresponding power cap must be passed in the payload. NOTE: If you are creating power policy on a group, the Targets field must be an array containing the group Id and group power cap as first value, followed by device id and power cap value of each member device. NOTE: StartTime and EndTime must be left empty for policy which is active entire day.
/api/PowerService/Actions/ PowerService.DisablePolicies This method disables a policy. Supported versions of Power Manager: ● 1.1 ● 1.0 POST method for Disabling Policy This method disables power policies. Description Disables power policies. Privilege DEVICE_CONFIGURATION HTTP response codes 200 Example Input: { "Ids": [30, 32] } Output: { "Ids": [ 30, 32 ] } Table 54.
POST method for Deleting Policy This method deletes power policies. Description Deletes power policies. Privilege DEVICE_CONFIGURATION HTTP response codes 200 Example Input: { "Ids": [30,32] } Output: { "Ids": [ 30, 32 ] } Table 55. Attributes Attribute name Description Ids List of IDs of power policies NOTE: To delete all power policies, provide value for Ids as -1.
8 Emergency Power Reduction Topics: • • • • • /api/PowerService/MonitoredDevices()/EPRStatus /api/PowerService/MonitoredGroups()/EPRStatus /api/PowerService/EPR /api/PowerService/Actions/PowerService.EnableEPR /api/PowerService/Actions/PowerService.DisableEPR /api/PowerService/MonitoredDevices()/ EPRStatus This URI represents the EPR status of the Power Manager monitored devices Supported versions of Power Manager: ● 1.1 ● 1.
Table 57. EPR Type Enumeration Enumeration Value Description 1 Power Throttle Down (0 power cap value). 2 Power Off. Table 58. EPR Source Enumeration Enumeration Value Description 1 Manual 2 Temperature-triggered /api/PowerService/MonitoredGroups()/ EPRStatus This URI represents the EPR status of the Power Manager monitored groups Supported versions of Power Manager: ● 1.1 ● 1.
Table 60. EPR Type Enumeration (continued) Enumeration Value Description 2 Power Off. Table 61. EPR Source Enumeration Enumeration Value Description 1 Manual 2 Temperature-triggered /api/PowerService/EPR This URI represents the list of Emergency Power Reduction applied on the targets. Supported versions of Power Manager: ● 1.1 ● 1.
Table 62. Attributes Attribute Description PolicyId Id of the EPR created. Name Name of the EPR. Description Description of the EPR. Enabled Status of the EPR. AssignedTo Target on which EPR is applied. CreatedTime Time at which EPR is created. IsEprPowerDown True, if EPR type is Power Down. IsAssociatedToGroup True, if EPR is associated to a group. ExecutionState State of the EPR execution. Table 63.
/api/PowerService/Actions/PowerService.EnableEPR This URI enables you to enable EPR on the target. Supported versions of Power Manager: ● 1.1 ● 1.0 POST method to Enable EPR This method enables EPR on the specified target. Description Enables EPR on the specified target Privilege DEVICE_CONFIGURATION HTTP response codes 200 Example Input: { "Target": 10149, "Action": "POWER_THROTTLE" } Output: { "Id": 7 } Table 66.
HTTP response codes Example 200 Input: { "Ids": [6,7] } Output: { "Ids": [6,7] } Table 67. Attributes Attribute Name Description Id EPR Ids to be disabled. NOTE: To disable all the EPRs, provide value for Ids as -1.
9 Report Service Topics: • /api/ReportService/ReportDefs /api/ReportService/ReportDefs This method creates a custom report. Supported versions of Power Manager: ● 1.1 ● 1.0 Post method for creating a custom Power Manager Report > Description Creates a custom report.
"FieldId":63 }, { "FieldId":99 }, { "FieldId":102 } ], "SortFields":[], "ReportSettings": [{ "SettingId": 1, "OperatorId": 1, "Value": "90" }, { "SettingId": 2, "OperatorId": 1, "Value": "2" }] } } Table 68. SettingId Enumeration Enumeration Value Description 1 Report duration 2 Aggregation period 3 Metric type Table 69. Report duration Enumeration Enumeration Value Description 1 1 Day 7 7 Days 15 15 Days 30 1 Month 90 3 Months 180 6 Months 365 1 Year Table 70.
