Reference: API Gateway examples for Asset

For additional API Gateway example syntax, see Tanium API Gateway User Guide: Reference: Filter syntax and Tanium API Gateway User Guide: Reference: API Gateway examples.

Asset query filter syntax

Filter Asset queries when retrieving Asset products (query.assetProducts) or endpoints (query.assetProductEndpoints).

Asset product queries (assetProducts) support the following filter fields:

  • search
  • states
  • vendors

For more information on syntax, see assetProductsFilter in the Documentation Explorer pane of the query explorer.

Endpoint queries using assetProductEndpoints support the following filter fields:

  • name
  • vendor
  • version
  • usage

For more information on syntax, see assetProductEndpointsFilter in the Documentation Explorer pane of the query explorer.

ClosedAsset products

You can retrieve Asset products and filter based on product metadata. Define a filter object using the syntax:

filter {
  vendors: [
    "vendor-name-1",
    "vendor-name-2",
    "vendor-name-n..."
  ],
  search: "search-string",
  states: [Cataloged | Ignored | Tracked]
}

For example, the following request retrieves only Asset products with a vendor name of Example vendor, an Asset state of Cataloged, and the search string Product in either the vendor name or product name:

Copy
query getAssetProductsFiltered($first: Int, $vendor: String!, $search: String, $states: AssetProductState!) {
  assetProducts(
    first: $first, filter: {
      vendors: [$vendor],
      search: $search,
      states: [$states]
    }
  ) {
    edges {
      node {
        vendor
        name
        installation {
          installedCount
          usedCount
          unusedCount
          pendingUsage
        }
        usage {
          usageNotDetected
          notInstalled 
          baselining
          limited
          normal
          high
        }
        tracking {
          state
          reportingPeriodDays
          normalMinutesUsedPerDay
          highMinutesUsedPerDay
          baselinePeriodDays
        }
        versions {
          version
          installs
        }
      }
    }
  }
}

Include the filter variables in the QUERY VARIABLES panel:

Copy
{
  "first": 2,
  "vendor": "Example vendor",
  "search": "Product",
  "states": "Cataloged"
}

ClosedEndpoints based on Asset products

You can retrieve endpoints and filter the returned endpoints based on Asset product information. Define a filter object using the syntax:

filter {
  vendors: [
    "vendor-name-1",
    "vendor-name-2",
    "vendor-name-n..."
  ],
  name: "name-string",
  version: "version-string"
}

For example, the following request retrieves only endpoints that have installed the Example name product, with a vendor of Example vendor and version of 1.2.3:

Copy
query getEndpointsAssetProduct($first: Int, $vendor: String, $name: String, $version: String) {
  assetProductEndpoints(
    first: $first
    filter: {vendor: $vendor, name: $name, version: $version usage: Normal}
  ) {
    edges {
      node {
        id
        eid
        computerName
        computerId
        serialNumber
        osPlatform
        operatingSystem
        servicePack
        manufacturer
        ipAddress
        userName
        createdAt
        updatedAt
      }
    }
  }
}

Include the filter variables in the QUERY VARIABLES panel:

Copy
{
  "first": 2,
  "vendor": "Example vendor",
  "name": "Example name",
  "version": "1.2.3" 
}

Asset examples

The following requests require Asset and retrieve Asset products or endpoints based on Asset products, update Asset product tracking, or import assets to update existing assets or create new assets.

Asset requests have the following feature-specific dependencies at the specified minimum versions:

  • Asset 1.23.8 or later is required to submit a mutation request to import assets (mutation.assetsImport).

  • Asset 1.24.76 or later is required to submit a request that retrieves Asset products (query.assetProducts) or endpoints based on installed Asset products (query.assetProductEndpoints), or to submit a mutation request that updates Asset product tracking (mutation.assetProducts).

ClosedImport assets (mutation.assetsImport)

Import assets

Before you submit this mutation request, you must configure an Asset custom source. For more information and an example workflow, see Tanium Asset User Guide: Create an Import API source.

The assetsImport mutation requires Asset 1.23.8 and imports assets defined in the request json variable value, using the defined sourceName custom source. To determine whether an existing asset updates, or a new asset is created:

  1. If an imported asset key matches an existing asset key imported using the sourceName custom source, that existing asset updates.

  2. If no existing asset from the configured source matches, but values in the imported asset match an existing asset key imported using a source different from the sourceName custom source, and the other source allows the sourceName custom source to update, the existing asset from the other source updates.

  3. Otherwise, if no existing asset matches the imported asset, the asset is imported as a new asset using the sourceName custom source.

If the request is structurally and syntactically valid, each asset object imports separately. A failed asset import does not prevent other valid asset objects in that request from importing.

Define the json attribute as a JSON object array, with each object corresponding to an asset. Ensure that the Asset custom source passes the JSON object array according to the following guidelines:

  • Use the backslash escape character with each quotation mark (\") in the JSON array.
  • You must define key field values for each object. If you do not define the key field values, the object does not import and the response returns ErrorMissingKey status for that object.
  • You can define source field mappings to destination fields for each object. If you do not define a source field mapping, values from those source fields are imported as null values for that object.
  • Field values are defined per object; you cannot globally define a single field value in the request to apply to every imported asset object.
  • You can define up to 5000 asset objects per array, and by extension, per request.

The following example Asset custom source, named test-name, defines two field mappings for computer_name and serial_number and defines computer_name as a key field.

Copy
{
  "keys": [
    "computer_name"
  ],
  "fieldMaps": [
    {
      "destination": "computer_name",
      "source": "computerName"
    },
    {
      "destination": "serial_number",
      "source": "serialNumber"
    }
  ]
}

The following mutation request imports assets based on the variables definition:

Copy
mutation importAssets($source: String!, $json: String!) {
  assetsImport(input: {sourceName: $source, json: $json}) {
    assets {
      id
      index
      status
    }
  }
}

Include the variables in the QUERY VARIABLES panel or in your variables dictionary.

The following variables manually define the test-name source for importing and two asset objects in the JSON object array. Each object has a value for the key field (computerName) and for the serialNumber field mapping.

Copy
{
  "source": "test-name",
  "json": "[{\"computerName\": \"computer123\", \"serialNumber\": \"testSerial123\"}, {\"computerName\": \"computer234\", \"serialNumber\": \"testSerial234\"}]"
}

As the request is evaluated, each asset object defines a value for the computerName key field, matching the key field defined for the test-name custom source, and both are imported using that source. The example response shows both objects with a status of Created:

Copy
{
  "data": {
    "assetsImport": {
      "assets": [
        {
          "id": 6, 
          "index": 0,
          "status": "Created"
        },
        {
          "id": 7, 
          "index": 1,
          "status": "Created"
        }
      ]
    }
  }
}

To verify the import, create a report based on the custom source definition, and filter the report to search for imported assets. For example, creating a report with Computer Name and Serial Number as columns, then filtering Computer Name for values containing computer and 23 returns the imported assets.

Example Asset import report

For more information, see Tanium Asset User Guide: Create a report.

ClosedGet Asset products (query.assetProducts)

Get Asset product information

The following query requires Asset 1.24.76 or later and retrieves Asset products:

Copy
query getAssetProducts($first: Int) {
  assetProducts(
    first: $first
  ) {
    edges {
      node {
        vendor
        name
        installation {
          installedCount
          usedCount
          unusedCount
          pendingUsage
        }
        usage {
          usageNotDetected
          notInstalled 
          baselining
          limited
          normal
          high
        }
        tracking {
          state
          reportingPeriodDays
          normalMinutesUsedPerDay
          highMinutesUsedPerDay
          baselinePeriodDays
        }
        versions {
          version
          installs
        }
      }
    }
  }
}
                    

Include the cursor variable in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2
}

Example response:

Copy
{
  "data": {
    "assetProducts": {
      "edges": [
        {
          "node": {
            "vendor": "Example vendor",
            "name": "Example product",
            "installation": {
              "installedCount": 8,
              "usedCount": 0,
              "unusedCount": 0,
              "pendingUsage": null
            },
            "usage": {
              "usageNotDetected": 0,
              "notInstalled": 0,
              "baselining": 0,
              "limited": 0,
              "normal": 0,
              "high": 0
            },
            "tracking": {
              "state": "Cataloged",
              "reportingPeriodDays": 90,
              "normalMinutesUsedPerDay": 60,
              "highMinutesUsedPerDay": 240,
              "baselinePeriodDays": 7
            },
            "versions": [
              {
                "version": "1.2.3",
                "installs": 2
              },
              {
                "version": "1.2.4",
                "installs": 2
              }
            ]
          }
        },
        {
          "node": {
            "vendor": "Example vendor 2",
            "name": "Example product 2",
            "installation": {
              "installedCount": 1,
              "usedCount": 0,
              "unusedCount": 0,
              "pendingUsage": null
            },
            "usage": {
              "usageNotDetected": 0,
              "notInstalled": 0,
              "baselining": 0,
              "limited": 0,
              "normal": 0,
              "high": 0
            },
            "tracking": {
              "state": "Cataloged",
              "reportingPeriodDays": 90,
              "normalMinutesUsedPerDay": 60,
              "highMinutesUsedPerDay": 240,
              "baselinePeriodDays": 7
            },
            "versions": [
              {
                "version": "0.1.2",
                "installs": 1
              }
            ]
          }
        }
      ]
    }
  }
}

The following query request filters and retrieves only Asset products with a vendor name of Example vendor, an Asset state of Cataloged, and the search string Product in either the vendor name or product name:

Copy
query getAssetProductsFiltered($first: Int, $vendor: String!, $search: String, $states: AssetProductState!) {
  assetProducts(
    first: $first, filter: {
      vendors: [$vendor],
      search: $search,
      states: [$states]
    }
  ) {
    edges {
      node {
        vendor
        name
        installation {
          installedCount
          usedCount
          unusedCount
          pendingUsage
        }
        usage {
          usageNotDetected
          notInstalled 
          baselining
          limited
          normal
          high
        }
        tracking {
          state
          reportingPeriodDays
          normalMinutesUsedPerDay
          highMinutesUsedPerDay
          baselinePeriodDays
        }
        versions {
          version
          installs
        }
      }
    }
  }
}
                    

Include the cursor and filter variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "first": 2,
  "vendor": "Example vendor",
  "search": "Product",
  "states": "Cataloged"
}

Example response:

Copy
{
  "data": {
    "assetProducts": {
      "edges": [
        {
          "node": {
            "vendor": "Example vendor",
            "name": "Example product",
            "installation": {
              "installedCount": 8,
              "usedCount": 0,
              "unusedCount": 0,
              "pendingUsage": null
            },
            "usage": {
              "usageNotDetected": 0,
              "notInstalled": 0,
              "baselining": 0,
              "limited": 0,
              "normal": 0,
              "high": 0
            },
            "tracking": {
              "state": "Cataloged",
              "reportingPeriodDays": 90,
              "normalMinutesUsedPerDay": 60,
              "highMinutesUsedPerDay": 240,
              "baselinePeriodDays": 7
            },
            "versions": [
              {
                "version": "0.1.2",
                "installs": 2
              },
              {
                "version": "3.4.5",
                "installs": 2
              }
            ]
          }
        },
        {
          "node": {
            "vendor": "Example vendor",
            "name": "Product example",
            "installation": {
              "installedCount": 1,
              "usedCount": 0,
              "unusedCount": 0,
              "pendingUsage": null
            },
            "usage": {
              "usageNotDetected": 0,
              "notInstalled": 0,
              "baselining": 0,
              "limited": 0,
              "normal": 0,
              "high": 0
            },
            "tracking": {
              "state": "Cataloged",
              "reportingPeriodDays": 90,
              "normalMinutesUsedPerDay": 60,
              "highMinutesUsedPerDay": 240,
              "baselinePeriodDays": 7
            },
            "versions": [
              {
                "version": "6.7.8",
                "installs": 1
              }
            ]
          }
        }
      ]
    }
  }
}

ClosedGet endpoints based on Asset products (query.assetProductEndpoints)

Get endpoints filtered based on Asset products

The following query requires Asset 1.24.76 or later and retrieves the first 2 endpoints with the Example name product installed, associated with the Example vendor vendor and version 1.2.3:

Copy
query getEndpointsAssetProduct($first: Int, $vendor: String, $name: String, $version: String) {
  assetProductEndpoints(
    first: $first
    filter: {vendor: $vendor, name: $name, version: $version, usage: Normal}
  ) {
    edges {
      node {
        id
        eid
        computerName
        computerId
        serialNumber
        osPlatform
        operatingSystem
        servicePack
        manufacturer
        ipAddress
        userName
        createdAt
        updatedAt
      }
    }
  }
}
                    

Include the cursor and filtering variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
    "first": 2,
    "vendor": "Example vendor",
    "name": "Example name",
    "version": "1.2.3"
}}

Example response:

Copy
{
  "data": {
    "assetProductEndpoints": {
      "edges": [
        {
          "node": {
            "id": 123,
            "eid": 456789,
            "computerName": "example-host-1",
            "computerId": "123456789",
            "serialNumber": "1234567890abcdef",
            "osPlatform": "Windows",
            "operatingSystem": "Windows 10 Enterprise",
            "servicePack": "No Service Pack found",
            "manufacturer": "VMware, Inc.",
            "ipAddress": "192.0.2.10",
            "userName": "example-user",
            "createdAt": "2022-09-29T07:00:16.000Z",
            "updatedAt": "2022-11-10T23:00:06.000Z"
          }
        },
        {
          "node": {
            "id": 456,
            "eid": 789012,
            "computerName": "example-host-2",
            "computerId": "987654321",
            "serialNumber": "fedcba0987654321",
            "osPlatform": "Windows",
            "operatingSystem": "Windows 10 Enterprise",
            "servicePack": "No Service Pack found",
            "manufacturer": "VMware, Inc.",
            "ipAddress": "192.0.2.20",
            "userName": "example-user",
            "createdAt": "2022-09-29T07:00:16.000Z",
            "updatedAt": "2022-10-31T14:00:05.000Z"
          }
        }
      ]
    }
  }
}

ClosedUpdate Asset products tracking (mutation.assetProducts)

Update Asset product tracking

The following mutation requires Asset 1.24.76 or later and updates the tracking metrics for an Asset product called Example product, published by Example vendor. It requires the product vendor, name, and tracking subfields in the input array.

Copy
mutation updateAssetTracking($vendor: String!, $name: String!, $tracking: AssetProductTrackingInput!) {
  assetProducts(input: {vendor: $vendor, name: $name, tracking: $tracking}) {
    products {
      vendor
      name
      tracking {
        state
        reportingPeriodDays
        normalMinutesUsedPerDay
        highMinutesUsedPerDay
        baselinePeriodDays
      }
      failureReason
    }
  }
}
                    

Include the product tracking variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "vendor": "Example vendor",
  "name": "Example product",
  "tracking": {
    "state": "Cataloged",
    "reportingPeriodDays": 90,
    "normalMinutesUsedPerDay": 120,
    "highMinutesUsedPerDay": 480,
    "baselinePeriodDays": 5
  }
}

Example response:

Copy
{
  "data": {
    "assetProducts": {
      "products": [
        {
          "vendor": "Example vendor",
          "name": "Example product",
          "tracking": {
            "state": "Cataloged",
            "reportingPeriodDays": 120,
            "normalMinutesUsedPerDay": 120,
            "highMinutesUsedPerDay": 480,
            "baselinePeriodDays": 5
          },
          "failureReason": null
        }
      ]
    }
  }
}

You can update multiple Asset product tracking metrics in one mutation request. The following request adds a second object to the input array for the Example vendor product Second example product:

Copy
mutation updateAssetTrackingMultiple($vendor: String!, $name: String!, $name2: String!, $tracking: AssetProductTrackingInput!, $tracking2: AssetProductTrackingInput!) {
  assetProducts(
    input: [{vendor: $vendor, name: $name, tracking: $tracking}, {vendor: $vendor, name: $name2, tracking: $tracking2}]
  ) {
    products {
      vendor
      name
      tracking {
        state
        reportingPeriodDays
        normalMinutesUsedPerDay
        highMinutesUsedPerDay
        baselinePeriodDays
      }
      failureReason
    }
  }
}
                    

Include the product tracking variables in the QUERY VARIABLES panel or in your variables dictionary:

Copy
{
  "vendor": "Example vendor",
  "name": "Example product",
  "name2": "Second example product",
  "tracking": {
    "state": "Cataloged",
    "reportingPeriodDays": 120,
    "normalMinutesUsedPerDay": 120,
    "highMinutesUsedPerDay": 480,
    "baselinePeriodDays": 5
  },
  "tracking2": {
    "state": "Cataloged",
    "reportingPeriodDays": 90,
    "normalMinutesUsedPerDay": 60,
    "highMinutesUsedPerDay": 480,
    "baselinePeriodDays": 7
  }
}

Example response:

Copy
{
  "data": {
    "assetProducts": {
      "products": [
        {
          "vendor": "Example vendor",
          "name": "Example product",
          "tracking": {
            "state": "Cataloged",
            "reportingPeriodDays": 120,
            "normalMinutesUsedPerDay": 120,
            "highMinutesUsedPerDay": 480,
            "baselinePeriodDays": 5
          },
          "failureReason": null
        },
        {
          "vendor": "Example vendor",
          "name": "Second example product",
          "tracking": {
            "state": "Cataloged",
            "reportingPeriodDays": 90,
            "normalMinutesUsedPerDay": 60,
            "highMinutesUsedPerDay": 480,
            "baselinePeriodDays": 7
          },
          "failureReason": null
        }
      ]
    }
  }
}