Usage of Excerpt Query parameter | Redfish Specification Forum

puwen
Minnow

Posts: 44

Usage of Excerpt Query parameter Oct 23, 2024 8:15:33 GMT

Quote

Post by puwen on Oct 23, 2024 8:15:33 GMT

Hi,

Since the specification does not provide any examples of excerpt, here is the expected behavior I have in mind.

Please help review whether my usage is correct.

My resources:
URL: /redfish/v1/Chassis/Fan_Board/Sensors


{
    "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors",
    "@odata.type": "#SensorCollection.SensorCollection",
    "Description": "Collection of Sensors for this Chassis",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A"
        }
    ],
    "Members@odata.count": 1,
    "Name": "Sensors"
}

URL: /redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A


{
    "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A",
    "@odata.type": "#Sensor.v1_2_0.Sensor",
    "Id": "Fan_1A",
    "Name": "Fan 1A",
    "Reading": 8402.0,
    "ReadingRangeMax": 25000.0,
    "ReadingRangeMin": 0.0,
    "ReadingType": "Rotational",
    "ReadingUnits": "RPM",
    "Status": {
        "Health": "OK",
        "State": "Enabled"
    },
    "Thresholds": {
        "LowerCaution": {
            "Reading": 1000.0
        },
        "LowerCritical": {
            "Reading": 600.0
        },
        "UpperCaution": {
            "Reading": null
        },
        "UpperCritical": {
            "Reading": null
        }
    }
}

Usage 1: /redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A?excerpt


{
    "Reading": 8402.0
}

Usage 2: /redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A?excerpt=Sensor


{
    "Reading": 8402.0
}

Usage 3: /redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A?excerpt=SensorPower

{
}

Usage 4: /redfish/v1/Chassis/Fan_Board/Sensors?$expand=*&excerpt


{
    "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors",
    "@odata.type": "#SensorCollection.SensorCollection",
    "Description": "Collection of Sensors for this Chassis",
    "Members": [
        {
            "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors/Fan_1A",
            "@odata.type": "#Sensor.v1_2_0.Sensor",
            "Id": "Fan_1A",
            "Name": "Fan 1A",
            "Reading": 8402.0,
            "ReadingRangeMax": 25000.0,
            "ReadingRangeMin": 0.0,
            "ReadingType": "Rotational",
            "ReadingUnits": "RPM",
            "Status": {
                "Health": "OK",
                "State": "Enabled"
            },
            "Thresholds": {
                "LowerCaution": {
                    "Reading": 1000.0
                },
                "LowerCritical": {
                    "Reading": 600.0
                },
                "UpperCaution": {
                    "Reading": null
                },
                "UpperCritical": {
                    "Reading": null
                }
            }
        }
    ],
    "Members@odata.count": 1,
    "Name": "Sensors"
}

Thanks.

BR,
Puwen

mraineri
Administrator

Posts: 1,132

Usage of Excerpt Query parameter Oct 23, 2024 13:13:33 GMT

Quote

Post by mraineri on Oct 23, 2024 13:13:33 GMT

Usage 2 and 3 are not valid. As a query parameter, it's simply "?exerpt". The strings we use in schema are specific for how excerpts are used elsewhere in the data model and not relevant to a client building a request.

Usage 4 is interesting and I'd like others to weigh in on it. I haven't seen others attempting to combine other query parameters with "excerpt".

puwen
Minnow

Posts: 44

Usage of Excerpt Query parameter Oct 23, 2024 15:33:56 GMT

Quote

Post by puwen on Oct 23, 2024 15:33:56 GMT

Hi Mike,

Thank you for your response.
I understand that excerpt does not support any parameters now. However, I’m not quite sure how to interpret:

"excerpt": "SensorCurrent,SensorVoltage"

Could you provide an example, or is there any documentation I can refer to for learning?

I noticed Usage 4 in DSP2060, and it also mentioned that

$expand and excerpt can be used together as a way to expand resources, but only return important data to the
client. For example, the query parameters $expand=.&excerpt= can be applies to a sensor collection to return all
Sensor resources in the collection, but only properties marked as "excerpt", such as Reading

Would the output look something like this?


{
    "@odata.id": "/redfish/v1/Chassis/Fan_Board/Sensors",
    "@odata.type": "#SensorCollection.SensorCollection",
    "Description": "Collection of Sensors for this Chassis",
    "Members": [
        {
            "Reading": 8402.0
        }
    ],
    "Members@odata.count": 1,
    "Name": "Sensors"
}

However, this seems a bit strange because members only show the Reading property, and I can't identify which sensor the Reading belongs to.

Last Edit: Oct 23, 2024 15:38:02 GMT by puwen

mraineri
Administrator

Posts: 1,132

Usage of Excerpt Query parameter Oct 23, 2024 18:02:39 GMT

Quote

Post by mraineri on Oct 23, 2024 18:02:39 GMT

> Could you provide an example, or is there any documentation I can refer to for learning?

I don't think we have a great set of documentation about how this is used in schema. However, this is primarily to express when one schema leverages an excerpt definition from another, it knows which properties to pull over to populate in the resource. One example of this is in the ThermalMetrics resource. If you look at the TemperatureReadingsCelsius property, it's defined like this in CSDL:

        <NavigationProperty Name="TemperatureReadingsCelsius" Type="Collection(Sensor.Sensor)">
          <Annotation Term="Redfish.ExcerptCopy" String="Array"/>
          <Annotation Term="OData.Description" String="The temperatures (in degree Celsius units) from all related sensors for this device."/>
          <Annotation Term="OData.LongDescription" String="This property shall contain the temperatures, in degree Celsius units, for this subsystem.  The value of the `DataSourceUri` property, if present, shall reference a resource of type `Sensor` with the `ReadingType` property containing the value `Temperature`."/>
        </NavigationProperty>

Instead of creating a unique sensor structure for this array of temperature readings, it's leveraging the excerpt definition of Sensor. In particular, it's is "Array" flavor, so in addition to "Reading" and "DataSourceUri", it will also include "PhysicalContext" and "PhysicalSubContext".

> Would the output look something like this?

Yes, it would look something like that. I'd like to get an example formalized, but off the top of my head that's what I'd expect.