You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: alsdkdefs/apis/remediations/assets_query.v1.yaml
+132Lines changed: 132 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -156,6 +156,136 @@ info:
156
156
There is a fake asset type called `any`. The `any` asset type can be used in the `asset_types`
157
157
parameter to allow any type. When combined with filters, a relationship to a set of asset types
158
158
can be matched. Check out the [General Query examples](#operation/query_assets) for a demo.
159
+
160
+
#### Using the `related_properties` option
161
+
162
+
Sometimes there is a need to represent the properties of related assets within a top-level asset, particularly in the case where some attribute(s) from an asset related to a particular asset type in the [`asset_types`](#api-_-typed-queries) string are needed, but it is undesirable or impossible to include the related asset in `asset_types`, either because the primary asset type is in the middle of a list of assets (e.g., needing to include the image name for a host from the related `image` asset, but `asset_types` is already `subnet,host,agent`, preventing adding `image` into the query without removing `agent`), or because there is a need to render a compact response (e.g, a single column is required).
163
+
164
+
In this case, the `related_properties` attribute may be used. This has the general form:
Where `alias` (if given) or `type` are present in the `asset_types` and `return_types` (if given) parameters, and `related_type_property_1,...related_type_property_n` is a CSV of attribute(s) from the `related_type` asset that should be included in the properties of the asset matched as `type` during the query. If provided, the `type` assets in the query will include an additional property, `related_properties`, like this:
177
+
178
+
```json
179
+
{
180
+
"type": "type",
181
+
"key": "key",
182
+
"related_properties": {
183
+
"related_type": [
184
+
{
185
+
"related_type_property_1": "related_value_1",
186
+
"related_type_property_n": "related_value_n"
187
+
}
188
+
]
189
+
}
190
+
}
191
+
```
192
+
193
+
For example, suppose the query `?asset_types=h:host&related_properties=h,image:name` were passed. In this case, the response format would look like this:
194
+
195
+
```json
196
+
{
197
+
"type": "host",
198
+
"key": "/host/my-host-key",
199
+
"related_properties": {
200
+
"image": [
201
+
{
202
+
"name": "image_name"
203
+
}
204
+
]
205
+
}
206
+
}
207
+
```
208
+
209
+
Note that the other primary asset (host) properties have been excluded from the example for brevity, but that **only** the specified attributes from the related asset (`image`) are normally included. It is required to enumerate the specific ones to include inside `related_properties`.
210
+
211
+
Finally, for common use cases, there is support for `named` related properties, which allows for assets to pre-define specific names that expand to particular mapping(s) to allow succinct client reference in queries. These `named` `related_properties` queries have the form:
212
+
213
+
```
214
+
type:related_properties_name
215
+
```
216
+
217
+
or
218
+
219
+
```
220
+
alias:related_properties_name
221
+
```
222
+
223
+
Where `alias` (if given) or `type` are present in the `asset_types` and `return_types` (if given) parameters, and `related_properties_name` is a valid name from the table below, which lists the supported named related properties
224
+
225
+
| Related Properties Name | Expansion (`related_type:related_type_property_1,...related_type_property_n`) |
For example, `?asset_types=h:host&related_properties=h:collector_summary` would expand to `?asset_types=h:host&related_properties=h,agent:statusstatus_updated,statistics.bytes_log.last_day,statistics.bytes_log.last_hour,statistics.bytes_ids.last_day,statistics.bytes_ids.last_hour,statistics.messages_log.last_day,statistics.messages_log.last_hour,statistics.packets_ids.last_day,statistics.packets_ids.last_hour&related_properties=h,appliance:status,status_updated,statistics.bytes_log.last_day,statistics.bytes_log.last_hour,statistics.bytes_ids.last_day,statistics.bytes_ids.last_hour,statistics.messages_log.last_day,statistics.messages_log.last_hour,statistics.packets_ids.last_day,statistics.packets_ids.last_hour`. This would result in a response like this:
230
+
231
+
```json
232
+
{
233
+
"type": "host",
234
+
"key": "/host/my-host-key",
235
+
"related_properties": {
236
+
"agent": [
237
+
{
238
+
"status": "ok",
239
+
"status_updated": 1654647608,
240
+
"statistics": {
241
+
"bytes_ids": {
242
+
"last_day": 7393418434,
243
+
"last_hour": 92345892
244
+
},
245
+
"bytes_log": {
246
+
"last_day": 9421572257,
247
+
"last_hour": 78623476
248
+
},
249
+
"messages_log": {
250
+
"last_day": 34528922,
251
+
"last_hour": 456928
252
+
},
253
+
"packets_ids": {
254
+
"last_day": 98076121,
255
+
"last_hour": 781234
256
+
}
257
+
}
258
+
}
259
+
],
260
+
"appliance": [
261
+
{
262
+
"status": "ok",
263
+
"status_updated": 1654647767,
264
+
"statistics": {
265
+
"bytes_ids": {
266
+
"last_day": 6132920624,
267
+
"last_hour": 79267433
268
+
},
269
+
"bytes_log": {
270
+
"last_day": 4921736435,
271
+
"last_hour": 92345786
272
+
},
273
+
"messages_log": {
274
+
"last_day": 89232785,
275
+
"last_hour": 456928
276
+
},
277
+
"packets_ids": {
278
+
"last_day": 18452912,
279
+
"last_hour": 872342
280
+
}
281
+
}
282
+
}
283
+
]
284
+
}
285
+
}
286
+
```
287
+
288
+
Note that queries can include as many distinct `related_properties` options as desired; each one will be applied additively. For example, `?asset_types=h:host&related_properties=h,image:name&related_properties=h,image:image_id` would apply the same as `?asset_types=h:host&related_properties=h,image:name,image_id`.
0 commit comments