devices¶

The following methods allow for interaction with the ZTB Devices API endpoints. Includes active device lists, device tags, operating systems, device details, DHCP history, filter values, and group-by aggregations.

Methods are accessible via ztb.devices

Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.

THE SOFTWARE IS PROVIDED “AS IS” AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

class DevicesAPI¶

Bases: APIClient

Client for the ZTB Devices resource.

Provides operations for listing active devices, device tags, operating systems, device details, DHCP history, filter values, and group-by aggregations in the Zero Trust Branch API.

get_device_details_v2(device_id, minutes)¶

Get device details with audit logs (V2 endpoint).

Parameters:

device_id (str) – Device ID.
minutes (str) – Time window in minutes for audit data.

Returns:

(result dict with audit_logs, traffic_data, etc., Response, error).

Return type:

tuple

Examples

>>> data, _, err = client.ztb.devices.get_device_details_v2(
...     "505d6556-92bd-4909-a774-d958606579fa", "60"
... )

get_device_details_v3(device_id)¶

Get device details (V3 endpoint).

Parameters:: device_id (str) – Device ID.
Returns:: (result dict with device info, Response, error).
Return type:: tuple

Examples

>>> details, _, err = client.ztb.devices.get_device_details_v3(
...     "505d6556-92bd-4909-a774-d958606579fa"
... )

get_device_tags()¶

Get list of device tags.

Returns:: (DeviceTags instance, Response, error).
Return type:: tuple

Examples

>>> tags, _, err = client.ztb.devices.get_device_tags()
>>> if not err and tags:
...     print(tags.tags)

get_dhcp_history(device_id, minutes)¶

Get DHCP history for a device (V2 endpoint).

Parameters:

device_id (str) – Device ID.
minutes (str) – Time window in minutes.

Returns:

(result dict with audit_logs, traffic_data, etc., Response, error).

Return type:

tuple

Examples

>>> data, _, err = client.ztb.devices.get_dhcp_history(
...     "505d6556-92bd-4909-a774-d958606579fa", "60"
... )

get_filter_values(field, query_params=None)¶

Get filter values by field name.

Parameters:

field (str) – Field name (e.g. type, category).
query_params (dict, optional) – Map of query parameters. [query_params.page] (int): Page number. [query_params.limit] (int): Page size.

Returns:

(DeviceFilterValues instance, Response, error).

Return type:

tuple

Examples

>>> fv, _, err = client.ztb.devices.get_filter_values("type")

get_group_by_list()¶

Get list of group names for graphs (e.g. categories, types).

Returns:: (list of group name strings, Response, error).
Return type:: tuple

Examples

>>> groups, _, err = client.ztb.devices.get_group_by_list()

list_active_devices(query_params=None)¶

List active devices with pagination and search.

Parameters:: query_params (dict, optional) – Map of query parameters. [query_params.search] (str): Search filter. [query_params.tags] (str): Tags filter. [query_params.page] (int): Page number. [query_params.limit] (int): Page size. [query_params.sort] (str): Sort field. [query_params.sortdir] (str): Sort direction (asc/desc). [query_params.siteId] (str): Site ID filter.
Returns:: (list of ActiveDevice instances, Response, error).
Return type:: tuple

Examples

>>> devices, _, err = client.ztb.devices.list_active_devices()
>>> devices, _, err = client.ztb.devices.list_active_devices(
...     query_params={"search": "DESKTOP", "page": 1, "limit": 25}
... )

Client-side filtering with JMESPath:

The response object supports client-side filtering and projection via resp.search(expression). See the JMESPath documentation for expression syntax.

list_devices_by_category(query_params=None)¶

Get devices by category or type (V3 endpoint).

Parameters:: query_params (dict, optional) – Map of query parameters. [query_params.search] (str): Search filter. [query_params.page] (int): Page number. [query_params.limit] (int): Page size. [query_params.sort] (str): Sort field. [query_params.sortdir] (str): Sort direction. [query_params.type] (str): Device type filter. [query_params.category] (str): Category filter. [query_params.filters] (str): Filters. [query_params.osname] (str): OS name filter. [query_params.osversion] (str): OS version filter. [query_params.full] (bool): Full response.
Returns:: (response body as dict, Response, error).
Return type:: tuple

Examples

>>> body, _, err = client.ztb.devices.list_devices_by_category(
...     query_params={"type": "Computer", "page": 1}
... )

Client-side filtering with JMESPath:

The response object supports client-side filtering and projection via resp.search(expression). See the JMESPath documentation for expression syntax.

list_devices_group_by(group, query_params=None)¶

Get devices grouped by category or type with counts.

Parameters:

group (str) – Group name (e.g. type, category).
query_params (dict, optional) – Map of query parameters. [query_params.search] (str): Search filter. [query_params.page] (int): Page number. [query_params.limit] (int): Page size. [query_params.sort] (str): Sort field. [query_params.sortdir] (str): Sort direction.

Returns:

(list of GroupByRow instances, Response, error).

Return type:

tuple

Examples

>>> rows, _, err = client.ztb.devices.list_devices_group_by(
...     "type", query_params={"page": 1}
... )

Client-side filtering with JMESPath:

The response object supports client-side filtering and projection via resp.search(expression). See the JMESPath documentation for expression syntax.

list_operating_systems(query_params=None)¶

Get list of operating systems with device counts grouped by OS name and version.

Parameters:: query_params (dict, optional) – Map of query parameters. [query_params.search] (str): Search filter. [query_params.page] (int): Page number. [query_params.limit] (int): Page size. [query_params.sort] (str): Sort field (e.g. os_name, count, version). [query_params.sortdir] (str): Sort direction.
Returns:: (list of OperatingSystemRow instances, Response, error).
Return type:: tuple

Examples

>>> os_list, _, err = client.ztb.devices.list_operating_systems(
...     query_params={"page": 1, "limit": 50}
... )

Client-side filtering with JMESPath:

The response object supports client-side filtering and projection via resp.search(expression). See the JMESPath documentation for expression syntax.