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.........................................................................................
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.
HTTPS communication The Hypertext Transfer Protocol or HTTP is an application protocol for distributed, collaborative, hypermedia information systems. HTTP forms the foundation of data communication for the World Wide Web. Secure HTTP (HTTPS) is a secure version of HTTP where it operates within a network connection encrypted by TLS or SSL. By enforcing HTTPS, the security of console management is significantly enhanced.
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.
Table 1. Authentication and authorization requirements (continued) Actions Authentication required Authorization required 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.
Following is the format of a resource URI: // Following is an example of a resource URI, where 1234 is the unique identifier for the device: /DeviceService/Devices(1234) Resource operations Standard HTTP methods are used for creating, retrieving, updating, and deleting resources. The mapping of the HTTP methods to operational semantics is described in the following table: Table 3.
Filter devices by system ID /api/DeviceService/Devices?$filter=SystemId eq 123 Filter devices by model using equal operator /api/DeviceService/Devices?$filter=Model eq 'PowerEdge MX740c' Filter devices by model using contains operator /api/PowerService/MonitoredDevices?$filter=contains(Model,'PowerEdge') Filter devices by device type /api/DeviceService/Devices?$filter=Type eq 3000 or Type eq 5000 Adding combinations of filters /api/PowerService/MonitoredDevices?$filter=contains(Model,'PowerEdge') a
Table 4. Examples of request headers Request Header Description Example x-auth-token Authentication token taken from the return header of the SessionService/ Sessions POST operation to create a session. x-auth-token: d6399a19-38c8-467ba1ec-75ffa03efb7c Accept-Language Choice of language that the client can request—Optional. Accept-Language: en Response codes For synchronous operations, the server returns HTTP response codes 200 or 204.
Table 6. Examples of response headers (continued) Response Header Description Content-Type Specifies the format of the content that the Content-Type: application/json; server returns. If there are multiple formats odata.metadata=minimal that can be accepted in the client request (using the Accept header), the server chooses the appropriate supported format.
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.
}, { }, { }, { }, { } } "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.
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.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.
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 29.
GET method for Representing All Power Manager capable devices from a Group This method represents all the Power Manager supported devices (All Licensed, Power Monitor Capable and Supported Model) Description Returns all the Power Manager devices belonging 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.
Table 31. Filter Field Operator Id eq DeviceName Contains ServiceTag Contains Model Contains Type eq 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.
{ "@odata.context": "/api/$metadata#Collection(PowerService.MonitoredGroup)", "@odata.count": 1, "value": [ { "@odata.type": "#PowerService.MonitoredGroup", "@odata.id": "/api/PowerService/MonitoredGroups(10690)", "Id": 10690, "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.
/api/PowerService/MonitoredGroups()/Devices This URI represents all the devices of a monitored group Table 35. 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 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.
Table 36. Attributes (continued) Attribute name Description Type Device Type PowerState Power State of device. ManagedState Managed State of the device ConnectionState Connection state of the device HealthStatus Health status of the device Model Device Model InWorkingSet Available in monitored list IsPolicyCapable Capable to apply Power cap policy or not. IsAddedIndividually Added as individual device for monitoring or not.
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.
} ] 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. PolicyDetails Link to the detailed view of the policy.
• 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.type": "#PowerService.PowerPolicy", "@odata.
Table 43. Attributes (continued) Attribute Name Description PolicyDetails Link to the detailed view of the policy. IsAssociatedToGroup The policy is associated to group or not. Table 44. Policy Execution State Enumeration Enumeration Value Description 1 NOSTATE (Policy execution state is not yet determined). 2 EXECUTING (Policy execution is in progress or pending). 3 SUCCESS (Policy execution is successful). 5 FAILED (Policy execution failed).
} } "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. Schedule Indicates when the policy will be active. StartTime Time at which the policy interval starts.
/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. Privilege VIEW HTTP response codes 200 Example Input: None Output: { "@odata.context": "/api/$metadata#Collection(PowerService.Policy)", "@odata.
/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.
} "Id": 30, "Name": "Group Policy", "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": [
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 200 Example 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":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.
