OData query options

NOTE

OData query options are not implemented in iLO 4. Refer to the Adapting from iLO 4 section for OData query options examples related to iLO 5.

Non implemented OData query options are silently discarded by Redfish services.

Redfish is an OData-derived protocol with resources linking to other resources using @odata.id:

{"@odata.id": "/redfish/v1/link_to_some_other_resource"}

The iLO Redfish implementation offers several OData services aiming at facilitating the consumption of data by Redfish clients.

As an example, the OData $expand query option causes the OData service to automatically replace a link with the results of an internal GET of the indicated URI. This is essential to allow the API to scale for clients. An example use case is to expand an event log to return the log entries inline with the collection and reduce the number of GETs required by the client.

Examples of client requests to expand (in the general OData case) looks like:

GET /redfish/v1/some_resource?$expand=*($levels=1) - Expand any references 1 level. Levels is assumed to be 1 by default so this is the same as GET /redfish/v1/some_resource?$expand=*
GET /redfish/v1/some_resource?$expand=*($levels=3) - Expand any references 3 levels deep. This case could require loop detection (For example, system expanding a link to chassis expanding a link back to system).
GET /redfish/v1/some_resource?$expand=. - Expand any references EXCEPT those found under the Links section.
GET /redfish/v1/some_resource?$expand=./Oem/Hpe - Expand any references found in the Oem/Hpe section of the resource.

OData query options supported by iLO are presented below along with use case examples.

iLO $expand

Using the rules above, iLO supports $expand in this way:

$expand is applicable to HTTP GET only.

$expand=., $expand=* and $expand=($levels=n) result in the same behavior:

Expands all links in both root and Oem/Hpe sections not inside the Links sections.
Levels is always interpreted as 1, regardless of n. This is to avoid the potential for expanding recursively for interlinked resources.
The Links section is never expanded. This is to avoid expanding the Chassis and Manager related links on GET operations to System.

NOTE

The root resource at /redfish/v1/ is available without authentication and has navigational links that can be expanded. An $expand request does not result in expansion unless valid authentication credentials are supplied.

Warning

There might be other links that do not support $expand.

iLO $expand examples

NOTE

iLO responds to all HTTP requests using Chunked Transfer Coding. This enables features like $expand that require very large responses.

The following example retrieves the ChassisCollection without the $expand query option:

GET a collection without $expand queryResponse body

Copy

Copied

GET /redfish/v1/Chassis/

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#ChassisCollection.ChassisCollection",
    "@odata.etag": "W/\"AA6D42B0\"",
    "@odata.id": "/redfish/v1/Chassis",
    "@odata.type": "#ChassisCollection.ChassisCollection",
    "Description": "Computer System Chassis View",
    "Name": "Computer System Chassis",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Chassis/1"
        }
    ],
    "Members@odata.count": 1
}

The next example retrieves the same ChassisCollection with the $expand=. query option:

GET a collection with $expand queryResponse body (abbreviated)

Copy

Copied

GET /redfish/v1/Chassis/?$expand=.

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#ChassisCollection.ChassisCollection",
    "@odata.etag": "W/\"5DDB6CFA\"",
    "@odata.id": "/redfish/v1/Chassis/",
    "@odata.type": "#ChassisCollection.ChassisCollection",
    "Description": "Computer System Chassis View",
    "Name": "Computer System Chassis",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#Chassis.Chassis",
            "@odata.id": "/redfish/v1/Chassis/1/",
            "@odata.type": "#Chassis.v1_19_0.Chassis",
            "Id": "1",
            "AssetTag": "",
            "ChassisType": "RackMount",
            "EnvironmentalClass": "A2",
            "Links": {
                "ManagedBy": [
                    {
                        "@odata.id": "/redfish/v1/Managers/1/"
                    }
                ],
                "ComputerSystems": [
                    {
                        "@odata.id": "/redfish/v1/Systems/1/"
                    }
                ],
                "Drives": [
                    {
                        "@odata.id": "/redfish/v1/Systems/1/Storage/DA000006/Drives/DA000006/"
                    },
                    ............
                ]
                    }
        },
    ]
    "Members@odata.count": 1
}

iLO "only" query option

iLO supports the only query parameter documented in the Redfish API specification. This query parameter is ignored except on collections with only one member. Examples include the ComputerSystemCollection, ChassisCollection and ManagerCollection.

iLO "only" example

The following example retrieves the chassis collection without the only query option.

GET chassis CollectionResponse body

Copy

Copied

GET /redfish/v1/Chassis/

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#ChassisCollection.ChassisCollection",
    "@odata.etag": "W/\"AA6D42B0\"",
    "@odata.id": "/redfish/v1/Chassis/",
    "@odata.type": "#ChassisCollection.ChassisCollection",
    "Description": "Computer System Chassis View",
    "Name": "Computer System Chassis",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Chassis/1/"
        }
    ],
    "Members@odata.count": 1
}

The following example retrieves the a chassis collection of a system with only one chassis, using the only query option.

GET the only chassis memberResponse body (abreviated)

Copy

Copied

GET /redfish/v1/Chassis/?only

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#Chassis.Chassis",
    "@odata.etag": "W/\"E623AF83\"",
    "@odata.id": "/redfish/v1/Chassis/1/",
    "@odata.type": "#Chassis.v1_19_0.Chassis",
    "Id": "1",
    "AssetTag": "",
    "ChassisType": "RackMount",
    "EnvironmentalClass": "A2",
    "Links": {
        "ManagedBy": [
            {
                "@odata.id": "/redfish/v1/Managers/1/"
            }
        ],
            }
    .....

    "PCIeDevices": {
        "@odata.id": "/redfish/v1/Chassis/1/PCIeDevices/"
    },
    "PCIeSlots": {
        "@odata.id": "/redfish/v1/Chassis/1/PCIeSlots/"
    },
    "Power": {
        "@odata.id": "/redfish/v1/Chassis/1/Power/"
    },
    "PowerState": "On",
    "SKU": "P54199-B21",
    "SerialNumber": "TWA22525A1",
    "Status": {
        "Health": "OK",
        "State": "Enabled"
    },
    "Thermal": {
        "@odata.id": "/redfish/v1/Chassis/1/Thermal/"
    }
}

The following example uses the only query option to retrieve the chassis collection of a system containing a Pensando Data Processor Unit (DPU).

GET Chassis collection with ?only query optionResponse body

Copy

Copied

GET /redfish/v1/Chassis/?only

Copy

Copied

{
  "@odata.context": "/redfish/v1/$metadata#ChassisCollection.ChassisCollection",
  "@odata.etag": "W/\"570254F2\"",
  "@odata.id": "/redfish/v1/Chassis",
  "@odata.type": "#ChassisCollection.ChassisCollection",
  "Description": "Computer System Chassis View",
  "Name": "Computer System Chassis",
  "Members": [
    {
      "@odata.id": "/redfish/v1/Chassis/1"
    },
    {
      "@odata.id": "/redfish/v1/Chassis/2"
    }
  ],
  "Members@odata.count": 2
}

iLO $filter query option

The odata.org official site defines the $filter query as the following:

"The $filter system query option allows clients to filter a collection of resources that are addressed by a request URL. The expression specified with $filter is evaluated for each resource in the collection, and only items where the expression evaluates to true are included in the response.".

Six logical operators (Equals, Not Equals, Greater Than...) can be applied to the $filter query. They are defined in the OData specifications.

iLO $filter examples

The following example retrieves the "iLO Dedicated Network Interface" properties (output abbreviated).

GET request with $filter queryResponse body (abbreviated)

Copy

Copied

GET /redfish/v1/Managers/1/EthernetInterfaces/?$filter=Name eq
'Manager Dedicated Network Interface'

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#EthernetInterfaceCollection.EthernetInterfaceCollection",
    "@odata.etag": "W/\"3E2CCBB8\"",
    "@odata.id": "/redfish/v1/Managers/1/EthernetInterfaces/",
    "@odata.type": "#EthernetInterfaceCollection.EthernetInterfaceCollection",
    "Description": "Configuration of Manager Network Interfaces",
    "Name": "Manager Network Interfaces",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#EthernetInterface.EthernetInterface",
            "@odata.id": "/redfish/v1/Managers/1/EthernetInterfaces/1/",
            "@odata.type": "#EthernetInterface.v1_4_1.EthernetInterface",
            "Id": "1",
            "AutoNeg": true,
            "Name": "Manager Dedicated Network Interface",
            "NameServers": [],
            "DHCPv4": {
                "DHCPEnabled": false,
                "UseDNSServers": false,
                "UseDomainName": false,
                "UseGateway": false,
                "UseNTPServers": false,
                "UseStaticRoutes": false
            },
            "DHCPv6": {
                "OperatingMode": "Stateful",
                "UseDNSServers": false,
                "UseDomainName": false,
                "UseNTPServers": false,
                "UseRapidCommit": false
            },
            "Description": "Configuration of this Manager Network Interface",
            "FQDN": null,
            "FullDuplex": true,
            "HostName": "ILOTWA22525A1",

            .......
            
            "Status": {
                "Health": "OK",
                "State": "Enabled"
            },
            "VLAN": {
                "VLANEnable": false,
                "VLANId": null
            }
        }
    ],
    "Members@odata.count": 1
}

The next example retrieves only Integrated Management Log (IML) entries with severity Repaired.

GET specific IML entriesResponse body (abbreviated)

Copy

Copied

GET /redfish/v1/Systems/1/LogServices/IML/Entries/?$filter=Oem.Hpe.Severity
eq 'Repaired'

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
    "@odata.etag": "W/\"CA3EE996\"",
    "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries",
    "@odata.type": "#LogEntryCollection.LogEntryCollection",
    "Description": "Integrated Management Logs view",
    "Name": "Integrated Management Logs view",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/39",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "39",
            "Created": "2022-09-25T04:39:05Z",
            "EntryType": "Oem",
            "Message": "System Overheating (Temperature Sensor 1, Location Ambient, Temperature 43)",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Cooling"
                    ],
                    "Class": 2,
                    "ClassDescription": "Environment",
                    "Code": 19,
                    "Count": 1,
                    "EventNumber": 56,
                    "LearnMoreLink": "http://www.hpe.com/support/class0x0002code0x0013-gen11",
                    "RecommendedAction": "Check fans, processor heat sink and air baffles installation.",
                    "Repaired": true,
                    "Severity": "Repaired",
                    "Updated": "2022-09-25T04:39:10Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        },

        .....

    
        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/92",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "92",
            "Created": "2022-09-25T06:19:17Z",
            "EntryType": "Oem",
            "Message": "Automatic Operating System Shutdown Initiated Due to Overheat Condition",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Other"
                    ],
                    "Class": 14,
                    "ClassDescription": "OS",
                    "Code": 2,
                    "Count": 1,
                    "EventNumber": 109,
                    "LearnMoreLink": "http://www.hpe.com/support/class0x000ecode0x0002-gen11",
                    "RecommendedAction": "Check simultaneously logged messages for cause of shutdown and address those issues accordingly.",
                    "Repaired": true,
                    "Severity": "Repaired",
                    "Updated": "2022-09-25T06:19:22Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        }
    ],
    "Members@odata.count": 16
}

The following example retrieves IML entries created after a specific date.

GET IML entries filtered by dateResponse body

Copy

Copied

GET /redfish/v1/Systems/1/LogServices/IML/Entries/?$filter=Created
gt '2022-10-04T06:19:22Z'`

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
    "@odata.etag": "W/\"EC19D60B\"",
    "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries",
    "@odata.type": "#LogEntryCollection.LogEntryCollection",
    "Description": "Integrated Management Logs view",
    "Name": "Integrated Management Logs view",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/102",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "102",
            "Created": "2022-10-04T16:11:32Z",
            "EntryType": "Oem",
            "Message": "Maintenance note: Starting F10 GUI",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Maintenance"
                    ],
                    "Class": 33,
                    "ClassDescription": "Maintenance",
                    "Code": 2,
                    "Count": 1,
                    "EventNumber": 119,
                    "Severity": "Informational",
                    "Updated": "2022-10-04T16:11:32Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        },

        .......

        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/105",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "105",
            "Created": "2022-10-04T16:25:34Z",
            "EntryType": "Oem",
            "Message": "Firmware flashed (Broadcom NetXtreme-E BCM5741x adapters 222.1.68.0)",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Administration"
                    ],
                    "Class": 32,
                    "ClassDescription": "System Revision",
                    "Code": 2,
                    "Count": 1,
                    "EventNumber": 122,
                    "Severity": "Informational",
                    "Updated": "2022-10-04T16:25:34Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        }
    ],
    "Members@odata.count": 4
}

iLO $count query option

The $count system query option allows Redfish clients to request a count of the matching resources included with the resources in the response.

iLO $count example

GET the number of Security log entriesResponse body

Copy

Copied

/redfish/v1/systems/1/logservices/SL/Entries/?$count=true

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
    "@odata.etag": "W/\"75983E8D\"",
    "@odata.type": "#LogEntryCollection.LogEntryCollection",
    "Description": "Security Logs view",
    "Name": "Security Logs",
    "Members": [],
    "Members@odata.count": 31
}

iLO $top and $skip query options

The $top system query option requests the number of items in the queried collection to be included in the result. The $skip query option requests the number of items in the queried collection that are to be skipped and not included in the result.

iLO $top and $skip examples

Retrieve the top (first) ten IML log entries:

GET the top ten IML log entriesResponse body (abbreviated)

Copy

Copied

GET /redfish/v1/Systems/1/LogServices/IML/Entries/?$top=10

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
    "@odata.etag": "W/\"7E02C697\"",
    "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries",
    "@odata.type": "#LogEntryCollection.LogEntryCollection",
    "Description": "Integrated Management Logs view",
    "Name": "Integrated Management Logs view",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/1",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "1",
            "Created": "2001-01-01T00:26:39Z",
            "EntryType": "Oem",
            "Message": "IML Cleared ( user: System Administrator)",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Maintenance",
                        "Administration"
                    ],
                    "Class": 33,
                    "ClassDescription": "Maintenance",
                    "Code": 1,
                    "Count": 1,
                    "EventNumber": 18,
                    "Severity": "Informational",
                    "Updated": "2001-01-01T00:26:39Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        },

        ... 

        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/10",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "10",
            "Created": "2022-09-15T15:42:14Z",
            "EntryType": "Oem",
            "Message": "Insufficient Fan Solution",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Cooling"
                    ],
                    "Class": 2,
                    "ClassDescription": "Environment",
                    "Code": 52,
                    "Count": 2,
                    "EventNumber": 27,
                    "LearnMoreLink": "http://www.hpe.com/support/class0x0002code0x0034-gen11",
                    "RecommendedAction": "Replace any failed or missing fans in the system.",
                    "Repaired": false,
                    "Severity": "Critical",
                    "Updated": "2022-09-15T15:52:10Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "Critical"
        }
    ],
    "Members@odata.count": 10
}

The request below returns IML entries starting at the 22th record (the Members@odata.count is 31).

Skip entriesResponse body (abbreviated)

Copy

Copied

 GET /redfish/v1/Systems/1/LogServices/IML/Entries/?$skip=21

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
    "@odata.etag": "W/\"2B9C6986\"",
    "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries",
    "@odata.type": "#LogEntryCollection.LogEntryCollection",
    "Description": "Integrated Management Logs view",
    "Name": "Integrated Management Logs view",
    "Members": [
        {
            "@odata.context": "/redfish/v1/$metadata#LogEntry.LogEntry",
            "@odata.id": "/redfish/v1/Systems/1/LogServices/IML/Entries/19",
            "@odata.type": "#LogEntry.v1_11_0.LogEntry",
            "Id": "19",
            "Created": "2022-05-18T14:55:37Z",
            "EntryType": "Oem",
            "Message": "HPE Ethernet 1Gb 4-port 331i Adapter - NIC Connectivity status changed to OK for adapter in slot 0, port 1",
            "Name": "Integrated Management Log",
            "Oem": {
                "Hpe": {
                    "@odata.context": "/redfish/v1/$metadata#HpeLogEntry.HpeLogEntry",
                    "@odata.type": "#HpeLogEntry.v2_4_0.HpeLogEntry",
                    "Categories": [
                        "Hardware"
                    ],
                    ...
                    "Severity": "Repaired",
                    "Updated": "2022-05-18T14:55:37Z"
                }
            },
            "OemRecordFormat": "Hpe-IML",
            "Severity": "OK"
        },
        ...
  ],
    "Members@odata.count": 10
}

iLO $select query option

The $select query option allows Redfish clients to requests a limited set of properties.

iLO $select examples

The following example retrieves the RedfishVersion property of an iLO based server.

GET a single selected propertyResponse body

Copy

Copied

GET /redfish/v1/?$select=RedfishVersion

Copy

Copied

{
    "@odata.context": "/redfish/v1/$metadata#ServiceRoot.ServiceRoot",
    "@odata.etag": "W/\"217FDE58\"",
    "@odata.id": "/redfish/v1",
    "@odata.type": "#ServiceRoot.v1_13_0.ServiceRoot",
    "RedfishVersion": "1.13.0"
}

The following example returns the ChassisType and ServiceLabel properties of a Data Processor Unit card.

GET multiple selected propertiesResponse body

Copy

Copied

GET /redfish/v1/Chassis/2/?$select=ChassisType,Location/PartLocation/ServiceLabel

Copy

Copied

{
  "@odata.context": "/redfish/v1/$metadata#Chassis.Chassis",
  "@odata.etag": "W/\"1B982357\"",
  "@odata.id": "/redfish/v1/Chassis/2/",
  "@odata.type": "#Chassis.v1_11_2.Chassis",
  "ChassisType": "Card",
  "Location": {
    "PartLocation": {
      "ServiceLabel": "PCIe Slot 1"
    }
  }
}