Retrieval of shared disks (v2)

Edit online

9.2.12 Available from 9.2.12.

You use the GET operation on the api/sam/v2/shared_disks element to request information about shared disks that are used in your infrastructure.

Note: This REST API can be used to retrieve information about computers on which the BigFix® client is installed. It cannot be used to retrieve information about computers on which the disconnected scanner is installed because the scanner does not gather information about shared disks.

Prerequisites

Before you can retrieve information about shared disks by using the REST API, discover the shared disks in your infrastructure. For more information, see: Step 1: Discovering remote shared disks (BigFix scenario).

Permissions

User You must have the View Shared Disks permissions to use this API.

Resource URL

https://hostname:port/api/sam/v2/shared_disks

Resource information

Table 1. Resource information
Operation details Description
HTTP method GET
Request headers
Accept-Language (optional)
  • Use: Used to negotiate the language of the response. If this header is not specified, the content is returned in the server language.
  • Values: en-US (only English is supported)
Token
  • Use: Used to authenticate REST API requests. The header is required when you set the value of the api_token_in_url_enabled parameter to false. Otherwise, you can specify the token in the request header or in the URL. For more information, see: Authenticating REST API requests.
  • Values: an alphanumeric string that is generated in License Metric Tool
Request format application/json
Response headers
Content-Type
  • Use: Specifies the content type of the response.
  • Values: application/json
Content-Language
  • Use: Specifies the language of the response content. If this header is not specified, the content is returned in the server language.
  • Values: en-US, …
Response payload Shared Disks element
Response format application/json
Response codes

200 – OK

403 – “Forbidden” if the user is not authorized to perform the action

500 – “Bad Request” if a query parameter contains errors or is missing

Schema description

To retrieve the list of all columns that are returned by this REST API together with their descriptions, use the following request.
GET https://hostname:port/api/sam/v2/schemas/shared_disk.json

Available columns

Table 2. Available columns
Column Description Displayed by default Type
id Identifier of the shared disk instance. ✓ Integer
status Indicates the status of the computer that is designated to scan the shared disk instance. Possible values are:
  • 0 - Shared disk detected
  • 1 - Child shared disk
  • 2 - Designating a computer
  • 3 - Waiting for software scan
  • 4 - OK
  • 5 - Designating new top-level directory
  • 6 - Designating a new computer
  • 7 - Waiting for software scan on the newly designated computer
 ✓ Integer
parent_id Identifier of the parent of the shared disk instance. ✓ Integer
top_level Indicates whether the shared disk is a top-level directory in the shared disk structure. Possible values are:
  • 0 - The directory is not top-level
  • 1 - The directory is top-level
   Boolean
exported_directory Exported directory of the shared disk. ✓ String
type Type of the shared disk. Possible values are:
  • 0 - Network File System
  • 1- Samba File System
 ✓ Integer
computers_count Number of computers on which the shared disk is mounted. ✓ Integer

Applicable associations

You can additionally retrieve data from the following associations:

Query parameters

Table 3. Query parameters
Parameter Description Required Value
columns[] Specify which columns to retrieve. If you do not specify this parameter, only default columns are retrieved.
Example: Retrieve product name and release
URL?columns[]=product_name&columns[]=product_release
   String
order Specify how to sort the returned data. The default direction for sorting columns is ascending. If you want to specify a descending sort, append desc to the column name.
Example: Order by computer ID descending
URL?order[]=computer_id desc
   Alphanumeric
limit Specify the number of rows to retrieve. If you omit this parameter, all rows are retrieved.
Example: Retrieve 100 records 
URL?limit=100
   Numeric
offset Specify the number of rows to skip for retrieving results. You can use it together with the limit parameter to paginate results.
Example: Retrieve 50 records starting after record 150
URL?limit=50&offset=150
   Numeric
criteria Retrieve records which match specific conditions. The parameter should have the following structure, written in one line: 
<criteria> ::= <left-brace> <boolean-operator> <colon> <left-bracket> 
<criterion> [{ <comma> <criterion> }...] <right-bracket> <right-brace>
<boolean-operator> ::= "and" | "or"
<criterion> ::= <criteria> | <left-bracket> <column> <comma> <operator> <comma> <value> <right-bracket>
<column> ::= <json-string>
<operator> ::= <json-string>
<value> ::= <json-array> | <json-string> | <json-number> | <json-null>

For more information about operators, see: Common connectors and operators.

Example: Retrieve software instances whose product name contains "BigFix" OR the discovery start is within a specific date range 
URL?criteria={ "or": [ ["product_name", "contains", "BigFix"], 
{ "and": [ ["discovery_start", ">", "1970-01-01T00:00:00+00:00Z"], 
["discovery_start", "<", "1970-01-02T00:00:00+00:00Z"] ] } ] }

For columns that use the date and time values, you can retrieve data also for a period instead of a specific date. To do so, use last or next as <operator>, and then specify the time value in the following convention: PxD/PxW/PxM/PxY, where x is a number in the 1-999 range, and D, W, M, or Y is a designator that represents days, weeks, months, or years respectively.

Example: Retrieve software instances that were first reported within the last 7 days
URL?criteria={"and":[["discovery_start","last","P7D"]]}
   String

Example conversation - default columns

Request
GET https://hostname:port/api/sam/v2/shared_disks
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"id":"5",
"status":"0"'
"type":"0"
"designated_computer_id":"29"
"parent_id":"3"
"computers_count":"10"
"exported_directory":"<ip_address>:/file_server/tlcm/ISO/RHEL"

Example conversation - all columns

Request
GET https://hostname:port/api/sam/v2/shared_disks
?columns[]=id&columns[]=status&columns[]=parent_id&columns[]=top_level
&columns[]=exported_directory&columns[]=type&columns[]=computers_count&columns[]=designated_copmuter_id
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"id":"1",
"status":"0",
"parent_id":"5",
"top_level":"0",
"exported_directory":"<ip_address>:/file_server/tlcm/HOME"
"type":"0",
"computers_count":"10",
"designated_computer_id":"29"

Example conversation - association

Request
GET https://hostname:port/api/sam/v2/shared_disks
?columns[]=exported_directory&columns[]=computers_count&columns[]=shared_disk_members.computer_id
&columns[]=shared_disk_members.mount_point
Request header
Accept: application/json 
Accept-Language: en-US
Token: <token>
Response body
[{
"exported_directory":"<ip_address>:/file_server/tlcm/HOME",
"computers_count":"1",
"members":
    {
    "computer_id":"5",
    "mount_point":"/mnt/fs"
    }
}]