szsz
Minnow
Posts: 3
|
Post by szsz on Sept 24, 2021 20:42:51 GMT
I am new to redfish and having trouble creating a new Oem within the UpdateService that does an action. What I am creating is an another way to update. I have followed the directions from www.dmtf.org/sites/default/files/standards/documents/DSP2055_1.0.0.pdf, created a .xml file with just the action block (type OemAction) within the schema for the oem I want to create, and created a complimenting .json file. I think it is important to note that I am a little confused if I am just supposed to create a definition for the Oem I wanted to create, or create a definition for either Actions or UpdateService along with it in the .json file. Meaning is it supposed to be: 1) { "$id":..... "$schema":..... "$copyright":..... "definitions": { "NewUpdate": { <New update oem definition> } } } 2) { "$id":..... "$schema":..... "$copyright":..... "definitions": { "UpdateService": {
<def info>,
"properties":
"#OemUpdate.NewUpdate": {
"$ref": "#definitions/NewUpdate"
} }, "NewUpdate": { <New update oem definition> } } } 3) { "$id":..... "$schema":..... "$copyright":..... "definitions": { "Actions": { <def info>, "properties": "#OemUpdate.NewUpdate": { "$ref": "#definitions/NewUpdate" } }, "NewUpdate": { <New update oem definition> } } } Also, for the actual resource. Does @odata.type matter? Or can I omit that. I've been trying to piece together a soltuion by looking at the original UpdateService schema and Oem schema examples, but I can't seem to see where I am going wrong. Thanks in advance! |
|
|
|
Post by mraineri on Sept 27, 2021 16:42:12 GMT
As a general starting point, one thing to keep in mind with OEM extensions is essentially any time you step into an "Oem" property, the contents of the property need to resolve back to some schema definition. For the document you referenced (DSP2055), that's for cases when you need to create entirely new resource definitions as OEM extensions rather than extending a standard resource in the "Oem" object. Your case appears to be the latter, so there's not as much for you to define in schema.
For everything other than OEM extensions to actions, this is done via the "@odata.type" property; the value found in "@odata.type" can be dissected such that it will point to a schema file and an object definition. For example, let's say "@odata.type" contains "#ContosoComputerSystem.v1_0_0.ComputerSystem". This would indicate to a JSON Schema client that it would need to look at the file "ContosoComputerSystem.v1_0_0.json" and search for the "ComputerSystem" definition.
However, actions are a bit different due to the modeling pattern inherited from OData. The action property inside of "Actions" contains the schema reference; "@odata.type" is not used here. So, taking a standard action as an example, "#ComputerSystem.Reset" is a standard action name, indicating to the client to inspect the "ComputerSystem" schema file and search for the "Reset" definition. The same pattern applies to OEM actions; inside of "Oem" within "Actions", you could find an action such as "#ContosoComputerSystem.Ping", which would indicate the definition can be found in the "ContosoComputerSystem" schema file under the definition "Ping".
When creating your schema definition for your OEM action, you need to consider the above pattern in terms of how to name your schema files and actions. Once you have that sorted, you need to create your schema file, and the only thing you need to populate in the "definitions" section is the OEM action representation. So, if your OEM action is called "#ContosoUpdateService.NewUpdate", then you would follow the outline you started with example #1, where the "definitions" section contains a term called "NewUpdate" (and its contents give the action schema definition). The GET response to your UpdateService would look something like this:
{
"@odata.id": "/redfish/v1/UpdateService",
"@odata.type": "#UpdateService.v1_X_X.UpdateService",
"Id": "UpdateService",
"Name": "Update Service",
"Actions": {
"#UpdateService.SimpleUpdate": { ... },
"Oem": {
"#ContosoUpdateService.NewUpdate": {
"target": "/redfish/v1/UpdateService/Actions/Oem/ContosoUpdateService.NewUpdate"
}
}
},
<Other properties>
}
|
|
szsz
Minnow
Posts: 3
|
Post by szsz on Sept 28, 2021 4:11:43 GMT
Thank you! That definitely clears things up.
One last thing. Because the resource contains a direct schema reference, am I correct in assuming that an .xml is unnecessary? Or does an .xml always have to be created for every .json file? And if the .xml is necessary, the binding parameter type for oem extensions to actions are UpdateService_v1_0_0.OemActions rather than UpdateService_v1_0_0.Actions correct?
|
|
|
|
Post by mraineri on Sept 28, 2021 12:57:38 GMT
That's entirely up to you and the types of clients you need to support. We publish standard schemas in three formats: OData CSDL (XML), JSON Schema, and OpenAPI YAML. We perform all of our work in XML files, and use tools to convert the schemas to the other formats. All three formats have the same functional coverage (they should at least; please let us know about any gaps you may notice). Ultimately we do this to satisfy as many types as clients as possible. A client that aligns with OData CSDL will take the payloads and inspect XML files for their definitions in a similar manner to how I described earlier with the JSON Schema examples.
In terms of that binding parameter you see in the XML files, that is purely an OData construct that serves no purpose to non-OData users. But if you do need to draft an XML version of your OEM extension, then you're correct in that the binding parameter would reference "UpdateService.v1_0_0.OemActions".
|
|
|
|
Post by jautor on Oct 5, 2021 0:51:04 GMT
Can you explain to us what your new Action is doing that is not covered by the standard update service? We'd like the standard operations to cover as much as possible - so if there's something that could occur in other industry-facing implementations, and not something very specific to your product/implementation, it's something we should consider adding to the standard.
Jeff
|
|
szsz
Minnow
Posts: 3
|
Post by szsz on Oct 7, 2021 20:19:25 GMT
Sure thing. I wanted it to be possible for two things to update simultaneously, so I decided to create an update oem that does the same thing as the standard update but also updates another part of my project.
|
|
|
|
Post by mraineri on Oct 8, 2021 19:13:34 GMT
When performing a SimpleUpdate, you can certainly update multiple things at once. The image transferred to the service is an opaque binary, and there could be many images in there and many devices updated as part of the single request. It's entirely up to you (the implementer) to decide what makes the most sense from a policy perspective.
|
|
