zscaler-sdk-python 1.2.2__py3-none-any.whl → 1.2.3__py3-none-any.whl

zscaler/__init__.py

@@ -29,7 +29,7 @@ __license__ = "MIT"
 __contributors__ = [
     "William Guilherme",
 ]
-__version__ = "1.2.2"
+__version__ = "1.2.3"
 
 
 from zscaler.oneapi_client import Client as ZscalerClient  # noqa

zscaler/helpers.py

@@ -73,6 +73,7 @@ def to_snake_case(string):
         "computeDeviceGroupsForZAD": "compute_device_groups_for_zad",
         "computeDeviceGroupsForZAD": "compute_device_groups_for_zad",
         "deleteDHCPOption121RoutesVisibility": "delete_dhcp_option121_routes_visibility",
+        "deleteDHCPOption121Routes": "delete_dhcp_option121_routes",
         "enableOneIDAdminMigrationChanges": "enable_one_id_admin_migration_changes",
         "purgeKerberosPreferredDCCacheVisibility": "purge_kerberos_preferred_dc_cache_visibility",
         "slowRolloutZCC": "slow_rollout_zcc",
@@ -105,6 +106,18 @@ def to_snake_case(string):
         "defaultProtocolForZPA": "default_protocol_for_zpa",
         "tunnelTwoForiOSDevices": "tunnel_two_fori_os_devices",
         "prioritizeIPv4OverIpv6": "prioritize_ipv4_over_ipv6",
+        "disableParallelIpv4AndIPv6": "disable_parallel_ipv4_and_ipv6",
+        "computeDeviceGroupsForZDX ": "compute_device_groups_for_zdx",
+        "logoutZCCForZDXService": "logout_zcc_for_zdx_service",
+        "enableZpaDR": "enable_zpa_dr",
+        "ziaRSAPubKeyName": "zia_rsa_pub_key_name",
+        "ziaRSAPubKey": "zia_rsa_pub_key",
+        "zpaRSAPubKeyName": "zpa_rsa_pub_key_name",
+        "zpaRSAPubKey": "zpa_rsa_pub_key",
+        "truncate_large_udpdns_response": "truncateLargeUDPDNSResponse",
+        "enableZCCRevert": "enable_zcc_revert",
+        "enableZiaDR": "enable_zia_dr",
+        "purge_kerberos_preferred_dc_cache": "purgeKerberosPreferredDCCache"
     }
 
     if string in FIELD_EXCEPTIONS:
@@ -217,7 +230,19 @@ def to_lower_camel_case(string):
         "default_protocol_for_zpa": "defaultProtocolForZPA",
         "tunnelTwoForiOSDevices": "tunnel_two_fori_os_devices",
         "prioritize_ipv4_over_ipv6": "prioritizeIPv4OverIpv6",
-        
+        "disable_parallel_ipv4_and_ipv6": "disableParallelIpv4AndIPv6",
+        "compute_device_groups_for_zdx": "computeDeviceGroupsForZDX",
+        "logout_zcc_for_zdx_service ": "logoutZCCForZDXService",
+        "enable_zpa_dr": "enableZpaDR",
+        "zia_rsa_pub_key_name": "ziaRSAPubKeyName",
+        "zia_rsa_pub_key": "ziaRSAPubKey",
+        "zpa_rsa_pub_key_name": "zpaRSAPubKeyName",
+        "zpa_rsa_pub_key": "zpaRSAPubKey",
+        "truncateLargeUDPDNSResponse": "truncate_large_udpdns_response",
+        "enable_zcc_revert": "enableZCCRevert",
+        "delete_dhcp_option121_routes": "deleteDHCPOption121Routes",
+        "enableZiaDR": "enable_zia_dr",
+        "purgeKerberosPreferredDCCache": "purge_kerberos_preferred_dc_cache"
     }
 
     if string in FIELD_EXCEPTIONS:

zscaler/utils.py

@@ -790,8 +790,8 @@ def zcc_param_mapper(func):
         mapped_params = {}
 
         # Normalize and map os_types
-        if "os_types" in query_params:
-            os_raw = query_params["os_types"]
+        if "os_type" in query_params:
+            os_raw = query_params["os_type"]
             if isinstance(os_raw, str):
                 os_raw = [os_raw]  # ✅ support single string value
 
@@ -801,8 +801,23 @@ def zcc_param_mapper(func):
                 if zcc_param_map["os"].get(os_type.lower())
             ]
             if not mapped:
-                raise ValueError("Invalid `os_types` provided.")
-            mapped_params["osTypes"] = ",".join(mapped)
+                raise ValueError("Invalid `os_type` provided.")
+            mapped_params["osType"] = ",".join(mapped)
+
+        # Normalize and map os_types
+        if "device_type" in query_params:
+            os_raw = query_params["device_type"]
+            if isinstance(os_raw, str):
+                os_raw = [os_raw]  # ✅ support single string value
+
+            mapped = [
+                str(zcc_param_map["os"].get(os_type.lower()))
+                for os_type in os_raw
+                if zcc_param_map["os"].get(os_type.lower())
+            ]
+            if not mapped:
+                raise ValueError("Invalid `device_type` provided.")
+            mapped_params["deviceType"] = ",".join(mapped)
 
         # Normalize and map registration_types
         if "registration_types" in query_params:

zscaler/zcc/admin_user.py

@@ -139,9 +139,13 @@ class AdminUserAPI(APIClient):
         Examples:
             Prints all admin roles in the Client Connector Portal to the console:
 
-            >>> for role in zcc.admin_user.list_admin_roles():
-            ...    print(role)
-
+            >>> role_list, _, err = client.zcc.admin_user.list_admin_roles()
+            >>>     if err:
+            ...         print(f"Error listing admin roles: {err}")
+            ...         return
+            ...     print(f"Total admin roles found: {len(role_list)}")
+            ...     for role in role_list:
+            ...         print(role.as_dict())
         """
         http_method = "get".upper()
         api_url = format_url(

zscaler/zcc/company.py

@@ -69,8 +69,9 @@ class CompanyInfoAPI(APIClient):
             return (None, response, error)
 
         try:
-            result = response.get_results()
+            result = []
+            for item in response.get_results():
+                result.append(GetCompanyInfo(self.form_response_body(item)))
         except Exception as error:
-            return None, response, error
-
-        return result, response, None
+            return (None, response, error)
+        return (result, response, None)

zscaler/zcc/devices.py

@@ -17,6 +17,7 @@ OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 from zscaler.api_client import APIClient
 from zscaler.request_executor import RequestExecutor
 from zscaler.utils import format_url, zcc_param_map, zcc_param_mapper
+from zscaler.helpers import convert_keys_to_camel_case
 from zscaler.zcc.models.devices import Device
 from zscaler.zcc.models.devices import ForceRemoveDevices
 from zscaler.zcc.models.devices import SetDeviceCleanupInfo
@@ -32,58 +33,188 @@ class DevicesAPI(APIClient):
         self._request_executor: RequestExecutor = request_executor
         self._zcc_base_endpoint = "/zcc/papi/public/v1"
 
-    def download_devices(
-        self,
-        filename: str = None,
-        os_types: list = None,
-        registration_types: list = None,
-    ):
+    def download_devices(self, query_params=None, filename: str = None):
         """
         Downloads the list of devices as a CSV file from the ZCC portal.
+
+        Args:
+            query_params (dict, optional): A dictionary containing supported filters:
+                ``[query_params.os_types]`` {str}: Filter by device operating system type. Valid options are:
+                    - ios
+                    - android
+                    - windows
+                    - macos
+                    - linux
+                ``[query_params.registration_types]`` {str}: Filter by device operating system type. Valid options are:
+                    - all
+                    - registered
+                    - unregistered
+                    - removal_pending
+                    - removed
+                    - quarantined
+
+            filename (str, optional): Custom filename for the CSV file. Defaults to timestamped name.
+
+        Returns:
+            str: Path to the downloaded CSV file.
+
+        Examples:
+            Download list of devices as a CSV:
+
+            >>> try:
+            ...     filename = client.zcc.devices.download_devices(
+            ...         query_params={
+            ...             "os_types": ["windows"],
+            ...             "registration_types": ["unregistered"]
+            ...         },
+            ...         filename="unregistered_devices.csv"
+            ...     )
+            ...     print(f"Devices downloaded successfully: {filename}")
+            ... except Exception as e:
+            ...     print(f"Error during download: {e}")
         """
+
+        query_params = query_params or {}
+
         if not filename:
             filename = f"zcc-devices-{datetime.now().strftime('%Y%m%d-%H_%M_%S')}.csv"
 
+        # Translate os_types
         params = {}
-
-        # Handle OS types
+        os_types = query_params.get("os_types")
         if os_types:
             os_types_resolved = [str(zcc_param_map["os"].get(item)) for item in os_types if zcc_param_map["os"].get(item)]
             if not os_types_resolved:
                 raise ValueError("Invalid os_type specified.")
             params["osTypes"] = ",".join(os_types_resolved)
 
-        # Handle Registration types
+        # Translate registration_types
+        registration_types = query_params.get("registration_types")
         if registration_types:
             reg_types_resolved = [
-                str(zcc_param_map["reg_type"].get(item)) for item in registration_types if zcc_param_map["reg_type"].get(item)
+                str(zcc_param_map["reg_type"].get(item))
+                for item in registration_types
+                if zcc_param_map["reg_type"].get(item)
             ]
             if not reg_types_resolved:
                 raise ValueError("Invalid registration_type specified.")
             params["registrationTypes"] = ",".join(reg_types_resolved)
 
-        # Correct the API URL
         http_method = "get".upper()
         api_url = format_url(f"{self._zcc_base_endpoint}/downloadDevices")
 
-        # Create the request properly
-        request, error = self._request_executor.create_request(http_method, api_url, params=params)
+        request, error = self._request_executor.create_request(
+            http_method,
+            api_url,
+            params=params,
+            headers={"Accept": "*/*"}
+        )
+
         if error:
             raise Exception("Error creating request for downloading devices.")
 
-        # Execute request and download file
         response, error = self._request_executor.execute(request, return_raw_response=True)
         if error or response is None:
             raise Exception("Error executing request for downloading devices.")
 
-        # Validate the response content
         content_type = response.headers.get("Content-Type", "").lower()
+        if not content_type.startswith("application/octet-stream") and not response.text.startswith('"User","Device type"'):
+            raise Exception("Invalid response content type or unexpected response format.")
+
+        with open(filename, "wb") as f:
+            f.write(response.content)
+
+        return filename
+
+    def download_service_status(self, query_params=None, filename: str = None):
+        """
+        Downloads service status for all devices from the ZCC portal.
+
+        Args:
+            query_params (dict, optional): A dictionary containing supported filters:
+        Args:
+            query_params (dict, optional): A dictionary containing supported filters:
+                ``[query_params.os_types]`` {str}: Filter by device operating system type. Valid options are:
+                    - ios
+                    - android
+                    - windows
+                    - macos
+                    - linux
+                ``[query_params.registration_types]`` {str}: Filter by device operating system type. Valid options are:
+                    - all
+                    - registered
+                    - unregistered
+                    - removal_pending
+                    - removed
+                    - quarantined
+
+                filename (str, optional): Custom filename for the CSV file. Defaults to timestamped name.
+
+        Returns:
+            str: Path to the downloaded CSV file.
 
-        # Check for valid CSV-like content
+        Examples:
+            Download list of devices as a CSV:
+
+            >>> try:
+            ...     filename = client.zcc.devices.download_service_status(
+            ...         query_params={
+            ...             "os_types": ["windows"],
+            ...             "registration_types": ["unregistered"]
+            ...         },
+            ...         filename="unregistered_devices.csv"
+            ...     )
+            ...     print(f"Device Service Status downloaded successfully: {filename}")
+            ... except Exception as e:
+            ...     print(f"Error during download: {e}")
+        """
+        from datetime import datetime
+
+        query_params = query_params or {}
+
+        if not filename:
+            filename = f"zcc-service-status-{datetime.now().strftime('%Y%m%d-%H_%M_%S')}.csv"
+
+        params = {}
+        os_types = query_params.get("os_types")
+        if os_types:
+            os_types_resolved = [str(zcc_param_map["os"].get(item)) for item in os_types if zcc_param_map["os"].get(item)]
+            if not os_types_resolved:
+                raise ValueError("Invalid os_type specified.")
+            params["osTypes"] = ",".join(os_types_resolved)
+
+        registration_types = query_params.get("registration_types")
+        if registration_types:
+            reg_types_resolved = [
+                str(zcc_param_map["reg_type"].get(item))
+                for item in registration_types
+                if zcc_param_map["reg_type"].get(item)
+            ]
+            if not reg_types_resolved:
+                raise ValueError("Invalid registration_type specified.")
+            params["registrationTypes"] = ",".join(reg_types_resolved)
+
+        http_method = "get".upper()
+        api_url = format_url(f"{self._zcc_base_endpoint}/downloadServiceStatus")
+
+        request, error = self._request_executor.create_request(
+            http_method,
+            api_url,
+            params=params,
+            headers={"Accept": "*/*"}
+        )
+
+        if error:
+            raise Exception("Error creating request for downloading service status.")
+
+        response, error = self._request_executor.execute(request, return_raw_response=True)
+        if error or response is None:
+            raise Exception("Error executing request for downloading service status.")
+
+        content_type = response.headers.get("Content-Type", "").lower()
         if not content_type.startswith("application/octet-stream") and not response.text.startswith('"User","Device type"'):
             raise Exception("Invalid response content type or unexpected response format.")
 
-        # Save file to disk
         with open(filename, "wb") as f:
             f.write(response.content)
 
@@ -147,7 +278,7 @@ class DevicesAPI(APIClient):
             return (None, response, error)
 
         try:
-            result = response.get_results() 
+            result = response.get_results()
         except Exception as error:
             return None, response, error
 
@@ -166,9 +297,12 @@ class DevicesAPI(APIClient):
         Examples:
             Prints all devices in the Client Connector Portal to the console:
 
-            >>> for device in zcc.devices.get_device_cleanup_info():
-            ...    print(device)
-
+            >>> devices, _, err = client.zcc.devices.get_device_cleanup_info()
+            >>>     if err:
+            ...         print(f"Error fetching device clean up: {err}")
+            ...         return
+            ...     print("Device clean up fetched successfully.")
+            ...     print(devices)
         """
         http_method = "get".upper()
         api_url = format_url(
@@ -191,7 +325,7 @@ class DevicesAPI(APIClient):
             return (None, response, error)
 
         try:
-            result = response.get_results() 
+            result = response.get_results()
         except Exception as error:
             return None, response, error
 
@@ -206,6 +340,20 @@ class DevicesAPI(APIClient):
 
         Returns:
             tuple: A tuple containing the updated Device Cleaup Information, response, and error.
+
+        Examples:
+            Updated Device Cleaup Information:
+
+            >>> device, _, err = client.zcc.devices.update_device_cleanup_info(
+            ...     active=1,
+            ...     force_remove_type=1,
+            ...     device_exceed_limit=16
+            ... )
+            >>> if err:
+            ...     print(f"Error fetching device cleanup info: {err}")
+            ...     return
+            ... print("Current device cleanup info fetched successfully.")
+            ... print(device)
         """
         http_method = "put".upper()
         api_url = format_url(
@@ -218,12 +366,10 @@ class DevicesAPI(APIClient):
 
         body.update(kwargs)
 
-        # Create the request
         request, error = self._request_executor.create_request(http_method, api_url, body, {}, {})
         if error:
             return (None, None, error)
 
-        # Execute the request
         response, error = self._request_executor.execute(request, SetDeviceCleanupInfo)
         if error:
             return (None, response, error)
@@ -254,7 +400,7 @@ class DevicesAPI(APIClient):
             ...     return
             ...  for device in details:
             ...     print(device.as_dict())
-            
+
             Prints all devices in the Client Connector Portal to the console:
 
             >>> details, _, err = client.zcc.devices.get_device_details(
@@ -293,80 +439,32 @@ class DevicesAPI(APIClient):
             return (None, response, error)
         return (result, response, None)
 
-    def download_service_status(
-        self,
-        filename: str = None,
-        os_types: list = None,
-        registration_types: list = None,
-    ):
-        """
-        Downloads service status for all devices from the ZCC portal.
-        """
-        if not filename:
-            filename = f"zcc-devices-{datetime.now().strftime('%Y%m%d-%H_%M_%S')}.csv"
-
-        params = {}
-
-        # Handle OS types
-        if os_types:
-            os_types_resolved = [str(zcc_param_map["os"].get(item)) for item in os_types if zcc_param_map["os"].get(item)]
-            if not os_types_resolved:
-                raise ValueError("Invalid os_type specified.")
-            params["osTypes"] = ",".join(os_types_resolved)
-
-        # Handle Registration types
-        if registration_types:
-            reg_types_resolved = [
-                str(zcc_param_map["reg_type"].get(item)) for item in registration_types if zcc_param_map["reg_type"].get(item)
-            ]
-            if not reg_types_resolved:
-                raise ValueError("Invalid registration_type specified.")
-            params["registrationTypes"] = ",".join(reg_types_resolved)
-
-        # Correct the API URL
-        http_method = "get".upper()
-        api_url = format_url(f"{self._zcc_base_endpoint}/downloadServiceStatus")
-
-        # Create the request properly
-        request, error = self._request_executor.create_request(http_method, api_url, params=params)
-        if error:
-            raise Exception("Error creating request for downloading devices.")
-
-        # Execute request and download file
-        response, error = self._request_executor.execute(request, return_raw_response=True)
-        if error or response is None:
-            raise Exception("Error executing request for downloading devices.")
-
-        # Validate the response content
-        content_type = response.headers.get("Content-Type", "").lower()
-
-        # Check for valid CSV-like content
-        if not content_type.startswith("application/octet-stream") and not response.text.startswith('"User","Device type"'):
-            raise Exception("Invalid response content type or unexpected response format.")
-
-        # Save file to disk
-        with open(filename, "wb") as f:
-            f.write(response.content)
-
-        return filename
-
-    def remove_devices(self, query_params=None) -> tuple:
+    def remove_devices(self, query_params=None, **kwargs) -> tuple:
         """
         Remove of the devices from the Client Connector Portal.
 
         Args:
             query_params {dict}: Map of query parameters for the request.
-                ``[query_params.page_size]`` {int}: Specifies the page size.
+                ``[query_params.page_size]`` {int}: Specifies the page size.  If not provided, the default page size is 30.
+                    The max page size is 5000.
 
         Returns:
             :obj:`list`: Remove devices from the Client Connector Portal.
 
         Examples:
-            Prints all removed devices in the Client Connector Portal to the console:
-
-            >>> for device in zcc.devices.remove_devices():
-            ...    print(device)
-
+            Removes devices in the Client Connector Portal to the console:
+
+            >>> remove_devices, _, error = client.zcc.devices.remove_devices(
+            ...     client_connector_version=['3.0.0.57'],
+            ...     os_type='3',
+            ...     udids='VMware-42-02-38-a5-5f-9c-86-39-ff-5a-d0-60-5c-35-68-90:D630C3617830C5C0B2DDE986EA7D994324C4EC1D',
+            ...     username='jdoe@acme.com'
+            ... )
+            >>> if error:
+            ...     print(f"Error removing device: {error}")
+            ...     return
+            ... for device in remove_devices:
+            ...     print(f"Removed device: {device.as_dict()}")
         """
         http_method = "post".upper()
         api_url = format_url(
@@ -378,16 +476,19 @@ class DevicesAPI(APIClient):
 
         query_params = query_params or {}
 
-        # Prepare request body and headers
-        body = {}
-        headers = {}
+        body = kwargs
 
-        request, error = self._request_executor.create_request(http_method, api_url, body, headers, params=query_params)
+        request, error = self._request_executor.create_request(
+            method=http_method,
+            endpoint=api_url,
+            body=body,
+            params=query_params
+        )
 
         if error:
             return (None, None, error)
 
-        response, error = self._request_executor.execute(request)
+        response, error = self._request_executor.execute(request, ForceRemoveDevices)
         if error:
             return (None, response, error)
 
@@ -399,23 +500,32 @@ class DevicesAPI(APIClient):
             return (None, response, error)
         return (result, response, None)
 
-    def force_remove_devices(self, query_params=None) -> tuple:
+    def force_remove_devices(self, query_params=None, **kwargs) -> tuple:
         """
         Force remove of the devices from the Client Connector Portal.
 
         Args:
             query_params {dict}: Map of query parameters for the request.
-                ``[query_params.page_size]`` {int}: Specifies the page size.
+                ``[query_params.page_size]`` {int}: Specifies the page size. If not provided, the default page size is 30.
+                    The max page size is 5000.
 
         Returns:
-            :obj:`list`:Remove devices from the Client Connector Portal.
+            :obj:`list`: Forces the removal of devices from the Client Connector Portal.
 
         Examples:
-            Prints all admin roles in the Client Connector Portal to the console:
-
-            >>> for role in zcc.devices.force_remove_devices():
-            ...    print(role)
-
+            Removes devices in the Client Connector Portal to the console:
+
+            >>> remove_devices, _, error = client.zcc.devices.force_remove_devices(
+            ...     client_connector_version=['3.0.0.57'],
+            ...     os_type='3',
+            ...     udids='VMware-42-02-38-a5-5f-9c-86-39-ff-5a-d0-60-5c-35-68-90:D630C3617830C5C0B2DDE986EA7D994324C4EC1D',
+            ...     username='jdoe@acme.com'
+            ... )
+            >>> if error:
+            ...     print(f"Error removing device: {error}")
+            ...     return
+            ... for device in remove_devices:
+            ...     print(f"Removed device: {device.as_dict()}")
         """
         http_method = "post".upper()
         api_url = format_url(
@@ -427,16 +537,19 @@ class DevicesAPI(APIClient):
 
         query_params = query_params or {}
 
-        # Prepare request body and headers
-        body = {}
-        headers = {}
+        body = kwargs
 
-        request, error = self._request_executor.create_request(http_method, api_url, body, headers, params=query_params)
+        request, error = self._request_executor.create_request(
+            method=http_method,
+            endpoint=api_url,
+            body=body,
+            params=query_params
+        )
 
         if error:
             return (None, None, error)
 
-        response, error = self._request_executor.execute(request)
+        response, error = self._request_executor.execute(request, ForceRemoveDevices)
         if error:
             return (None, response, error)
 
@@ -448,10 +561,15 @@ class DevicesAPI(APIClient):
             return (None, response, error)
         return (result, response, None)
 
-    def remove_machine_tunnel(self) -> tuple:
+    def remove_machine_tunnel(self, query_params=None, **kwargs) -> tuple:
         """
         Remove machine tunnel devices from the Client Connector Portal.
 
+        Args:
+            query_params {dict}: Map of query parameters for the request.
+                ``[query_params.hostname]`` {int}: Comma-separated list of hostnames for the device.
+                ``[query_params.machine_token]`` {int}: Comma-separated list of hostnames for the device.
+
         Keyword Args:
             hostnames (str): The hostname of the machine tunnel to be removed.
             machine_token (str): The machine tunnel token to be removed.
@@ -460,11 +578,15 @@ class DevicesAPI(APIClient):
             :obj:`list`: Remove machine tunnel devices from the Client Connector Portal.
 
         Examples:
-            Prints all removed machine tunnel devices in the Client Connector Portal to the console:
-
-            >>> for tunnel in zcc.devices.remove_machine_tunnel():
-            ...    print(tunnel)
+            Removes machine tunnels in the Client Connector Portal to the console:
 
+            >>> remove_tunnels, _, error = client.zcc.devices.remove_machine_tunnel(
+            ...     host_names=['FXJ14JLFQW'],
+            ... )
+            >>> if error:
+            ...     print(f"Error removing machine tunnel: {error}")
+            ...     return
+            ... print("Removed machine tunnel:", remove_tunnels)
         """
         http_method = "post".upper()
         api_url = format_url(
@@ -474,22 +596,28 @@ class DevicesAPI(APIClient):
         """
         )
 
-        body = {}
+        query_params = convert_keys_to_camel_case(query_params or {})
+        body = convert_keys_to_camel_case(kwargs or {})
         headers = {}
 
-        request, error = self._request_executor.create_request(http_method, api_url, body, headers, {})
+        request, error = self._request_executor.create_request(
+            http_method,
+            api_url,
+            body=body,
+            headers=headers,
+            params=query_params,
+        )
 
         if error:
-            return (None, None, error)
+            return None, None, error
 
         response, error = self._request_executor.execute(request)
         if error:
-            return (None, response, error)
+            return None, response, error
 
         try:
-            result = []
-            for item in response.get_results():
-                result.append((self.form_response_body(item)))
+            result = self.form_response_body(response.get_body())
         except Exception as error:
-            return (None, response, error)
-        return (result, response, None)
+            return None, response, error
+
+        return result, response, None