devices

The following methods allow for interaction with the ZCC Devices API endpoints.

Methods are accessible via zcc.devices

class DevicesAPI

download_devices(filename=None, os_types=None, registration_types=None)

Downloads the list of devices in the Client Connector Portal as a CSV file.

By default, this method will create a file named zcc-devices-YYmmDD-HH_MM_SS.csv. This can be overridden by specifying the filename argument.

Notes

This API endpoint is heavily rate-limited by Zscaler and as of NOV 2022 only 3 calls per-day are allowed.

Parameters:

• filename (str) – The name of the file that you want to save to disk.

• os_types (list) –

  A list of OS Types to filter the device list. Omitting this argument will result in all OS types being matched. Valid options are:

  • ios

  • android

  • windows

  • macos

  • linux

• registration_types (list) –

  A list of device registration states to filter the device list. Valid options are:

  • all (provides all states except for ‘removed’)

  • registered

  • removal_pending

  • unregistered

  • removed

  • quarantined

Returns:

The local filename for the CSV file that was downloaded.

Return type:

str

Examples

Create a CSV with all OS types and all registration types:

>>> zcc.devices.download_devices(registration_types=["all", "removed"])

Create a CSV for Windows and macOS devices that are in the registered state:

>>> zcc.devices.download_devices(os_types=["windows", "macos"],
...     registration_types=["registered"])

Create a CSV with filename unregistered.csv for devices in the unregistered state:

>>> zcc.devices.download_devices(filename="unregistered.csv",
...     registration_types=["unregistered"])

list_devices(**kwargs)

Returns the list of devices enrolled in the Client Connector Portal.

Keyword Arguments:

• os_type (str) –

  Filter by device operating system. Valid options are:

  • ios

  • android

  • windows

  • macos

  • linux

• page (int) – Return a specific page number.

• page_size (int) – Specify the number of devices per page, defaults to 30.

• user_name (str) – Filter by the enrolled user for the device.

Returns:

A list containing devices using ZCC enrolled in the Client Connector Portal.

Return type:

BoxList

Examples

Prints all devices in the Client Connector Portal to the console:

>>> for device in zcc.devices.list_devices():
...    print(device)

remove_devices(force=False, **kwargs)

Removes the specified devices from the Zscaler Client Connector Portal.

Notes

You must be using API credentials with the Write role. You must specify at least one criterion from Keyword Args to remove devices.

Parameters:

• force (bool) – Setting force to True removes the enrolled device from the portal. You can only remove devices that are in the registered or device removal pending state.

• **kwargs – Optional keyword args.

Keyword Arguments:

• client_connector_version (list) – A list of client connector versions that will be removed. You must supply the exact version number, i.e. if the Client Connector version is 3.2.0.18 you must specify 3.2.0.18 and not 3.2.

• os_type (str) –

  The OS Type for the devices to be removed. Valid options are:

  • ios

  • android

  • windows

  • macos

  • linux

• udids (list) – A list of Unique Device IDs.

• user_name (str) – The username of the user whose devices will be removed.

Returns:

Server response containing the total number of devices removed.

Return type:

Box

Examples

Soft-remove devices using ZCC version 3.7.1.44 from the Client Connector Portal:

>>> zcc.devices.remove_devices(client_connector_version=["3.7.1.44"])

Soft-remove Android devices from the Client Connector Portal:

>>> zcc.devices.remove_devices(os_type="android")

Hard-remove devices from the Client Connector Portal by UDID:

>>> zcc.devices.remove_devices(force=True, udids=["99999", "88888", "77777"])

Hard-remove Android devices for johnno@widgets.co from the Client Connector Portal:

>>> zcc.devices.remove_devices(force=True, os_type="android",
...     user_name="johnno@widgets.co")