The Component Inventory API allows you to create and download reports to get insights into what components are used in your Java application(s).
Component Inventory reports can be grouped by tag to break down areas of ownership and logically combine differentiated services, build versions, regions, or other information.
Reports are generated asynchronously. By using the schedule endpoint, a task to generate a report is created. In response, you get a unique report identifier. With this identifier, you can retrieve the report.
Request Report Generation
You can request the generation of a report with a POST
call to https://YOUR_ENDPOINT.azul.com/public/component/report/schedule
and a set of parameters.
Request Parameters
Argument |
Default |
Description |
filter |
array[string] |
SQL-based filters applied to data collected from virtual machines. The fields used to filter the data are presented in the data items of the response.
Supported operations:
-
field = literal
-
field = null
-
field != literal
-
field != null
-
field < literal
-
field <= literal
-
field > literal
-
field >= literal
-
field LIKE regexp
-
field CONTAINS literalSubstring
-
field IN (literal1, literal2,…literalN)
-
field RANGE (literalLow, literalHigh)
|
groupBy |
array[string] |
List of fields by which the components (name + version) are grouped. The order of the fields directly affects the result of the grouping. The values of the groupBy fields are presented in the data items of the response. In addition, the count field corresponding to the number of VMs included in each group is returned.
Format: <field_name> .
Note
|
The count field can be used to sort data, for example, using count=ASC .
|
Note
|
To group by time period, use the keywords year , month , week , or day . When using week , the week number of the year is used (Calendar.WEEK_OF_YEAR ).
|
|
sortBy |
array[string] |
A set of fields and the desired sort order for their values.
Format: <field_name>=<sort_order> .
Sort order values:
-
ASC - ascending
-
DESC - descending
|
startTime |
string |
Relative or absolute time to get components detected by AVD based on VMs that are still running after (or equal to) the provided startTime.
Relative time is calculated from the current time on the server (now) and can be set as:
-
Xd where X is an integer number of days in the past from now: 0d = today, 1d = yesterday.
-
Xm where X is an integer number of months in the past from now: 1m = 1 month ago from today, 12m = 1 year ago from today.
Absolute time must be in ISO 8601 format (`yyyy-MM-dd’T’HH:mm:ss.SSS) or epoch time in milliseconds.
Examples:
Default value: 3m . |
endTime |
string |
Relative or absolute time to get components detected by AVD based on VMs that are not started after the provided endTime.
Similar to startTime . |
details |
boolean |
Whether to include in the report a set of virtual machine IDs containing a particular detected component (name + version).
Default value: false . |
Example Request
curl -X 'POST' \
'https://YOUR_ENDPOINT.azul.com/public/component/report/schedule' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-d '{
"filter": [
"tags.owner CONTAINS '\''admin'\''",
"state != '\''OFFLINE'\''"
],
"groupBy": [
"state",
"agentVersion"
],
"sortBy": [
"componentName=ASC",
"tags.owner=DESC"
],
"startTime": "2022-05-01T12:43:50.999",
"endTime": "1d",
"details": false
}'
Example Response
In response, you get a reportId that can be used with the GET
endpoint to retrieve the report.
{
"reportId": "f12ba5df-0673-4917-92ce-4f6c84a3ace8",
"userId": "...",
"parameters": {
"filter": [
"tags.owner CONTAINS 'admin'",
"state != 'OFFLINE'"
],
...
"details": false
},
"state": "PROCESSING",
"requestTime": 1682510562745
}
Retrieve the Report
You can retrieve a report with a GET
call to https://YOUR_ENDPOINT.azul.com/public/component/report/YOUR_REPORT_ID
.
The response must be checked to define if the data is available, based on the following possible return data:
-
state
: State of the request, one of the following options:
-
PROCESSING
-
SUCCEEDED
-
FAILED
-
PARTIALLY_FAILED
-
TIMED_OUT
-
summary
: More info related to the state
.
-
errors
: Errors while creating the report (if applicable).
Large reports are split into pages (up to 5.5MB per page). You can find the total number of pages in the response and use this value to retrieve all the report pages.
Note
|
Regardless of whether a report is generated successfully or not, when the generation is finished, at least one page of the report is available for retrieval.
|
Example Request
curl -X 'GET' \
'https://YOUR_ENDPOINT.azul.com/public/component/report/YOUR_REPORT_ID' \
-H 'accept: application/json' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json'
Example Response
{
"reportId": "f12ba5df-0673-4917-92ce-4f6c84a3ace8",
"userId": "...",
"parameters": {
"filter": [
"tags.owner CONTAINS 'shep'",
"state != 'OFFLINE'"
],
...
"details": false
},
"state": "SUCCEEDED",
"requestTime": 1682510562745,
"startTime": 1682510570860,
"finishTime": 1316,
"data": [
{
"state": "TERMINATED",
"data": [
{
"agentVersion": "1.0.0-271",
"data": [
{
"componentName": "commons-io",
"tags.owner": "ashepotko",
"componentVersion": "2.11.0",
"count": 26
},
{
"componentName": "crs-tests-jar-with-dependencies.jar",
"tags.owner": "ashepotko",
"componentVersion": "UNKNOWN",
"count": 26
},
...
]
},
{
"agentVersion": "1.0.11-568",
"data": [
{
"componentName": "aether-connector-basic",
"tags.owner": "ashepotko",
"componentVersion": "1.1.0",
"count": 11
},
...
]
},
...
]
}
],
"totalCount": 44
}
Count values used in the response: