Merge pull request #39 from sbarbett/health-checks

New Endpoints and Utilities - Issues# 31, 32, 33, 34, 35, 36, 37, 38 - v2.3.0

Author: sbarbett

.plugin-version

@@ -1 +1 @@
-v2.2.5
+v2.3.0

README.md

@@ -269,6 +269,10 @@ export USERNAME='your_username'
 export PASSWORD='your_password'
 ```
 
+### Background Tasks
+
+Utilities for handling long running tasks that process in the background, such as reports or exports, are available and documented [here](./src/ultra_rest_client/utils/README.md)
+
 ## Functionality
 
 The sample code does not attempt to implement a client for all available UltraDNS REST API functionality.  It provides access to basic functionality. Adding additional functionality should be relatively straightforward, and any contributions from the UltraDNS community would be greatly appreciated. See [sample.py](sample.py) for an example of how to use this library in your own code.

examples/report_handler_example.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python
+"""
+Example script demonstrating the use of the ReportHandler utility class.
+
+This script shows how to use the ReportHandler to handle report generation API responses
+from the UltraDNS API.
+"""
+
+from ultra_rest_client import RestApiClient, ReportHandler
+
+# Initialize the client
+client = RestApiClient('your_username', 'your_password')
+
+# Example 1: Creating an advanced NXDOMAIN report
+# --------------------------------------------
+# The endpoint returns a requestId that needs to be polled until the report is complete
+print("Example 1: Creating an advanced NXDOMAIN report")
+response = client.create_advanced_nxdomain_report(
+    startDate='2023-01-01',
+    endDate='2023-01-31',
+    zoneNames=['example.com']
+)
+print("Initial response:", response)
+
+# The ReportHandler will automatically poll until the report is complete
+report_result = ReportHandler(response, client)
+print("Final result after polling:")
+print(report_result)  # This will print the final result
+
+# Example 2: Creating a projected query volume report
+# --------------------------------------------
+print("\nExample 2: Creating a projected query volume report")
+response = client.create_projected_query_volume_report('your_account_name')
+print("Initial response:", response)
+
+# You can set a maximum number of retries to avoid indefinite polling
+report_result = ReportHandler(response, client, max_retries=30)
+print("Final result after polling (or max retries):")
+print(report_result)

sample.py examples/sample.pysample.py renamed to examples/sample.py

@@ -86,7 +86,7 @@
 print('get first 5 primary zones with j: %s' % client.get_zones(offset=0, limit=5, sort="NAME", reverse=False, q={"name":"j", "zone_type":"PRIMARY"}))
 
 #creating a zone with upload
-result = client.create_primary_zone_by_upload(account_name, 'sample.client.me.', './zone.txt')
+result = client.create_primary_zone_by_upload(account_name, 'sample.client.me.', '../zone.txt')
 print('create zone via upload: %s' % result)
 
 # check the task status

examples/task_handler_example.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python
+"""
+Example script demonstrating the use of the TaskHandler utility class.
+
+This script shows how to use the TaskHandler to handle asynchronous task responses
+from the UltraDNS API.
+"""
+
+from ultra_rest_client import RestApiClient, TaskHandler
+
+# Initialize the client
+client = RestApiClient('your_username', 'your_password')
+
+# Example 1: Handling a response with a task_id
+# --------------------------------------------
+# Some API endpoints return a task_id indicating a background task
+print("Example 1: Creating a snapshot (returns a task_id)")
+response = client.create_snapshot('example.com')
+print("Initial response:", response)
+
+# The TaskHandler will automatically poll the task endpoint until completion
+task_result = TaskHandler(response, client)
+print("Final result after polling:")
+print(task_result)  # This will print the final result
+
+# Example 2: Handling a response with a location
+# --------------------------------------------
+# Some API endpoints return a location that needs to be polled until completion
+print("\nExample 2: Creating a health check (returns a location)")
+response = client.create_health_check('example.com')
+print("Initial response:", response)
+
+# The TaskHandler will automatically poll the location until completion
+location_result = TaskHandler(response, client, poll_interval=2)  # Poll every 2 seconds
+print("Final result after polling:")
+print(location_result) 
+
+# Example 3: Handling a regular response (no task_id or location)
+# --------------------------------------------
+# If no task_id or location is present, the TaskHandler will return the original response
+print("\nExample 3: Getting zone information (returns a regular response)")
+response = client.get_zone('example.com')
+print("Initial response:", response)
+
+regular_result = TaskHandler(response, client)
+print("Result from TaskHandler:")
+print(regular_result)  # This will print the original response

src/ultra_rest_client/__init__.py

@@ -1,2 +1,4 @@
 from .ultra_rest_client import RestApiClient
-from .connection import RestApiConnection
+from .connection import RestApiConnection
+from .utils.tasks import TaskHandler
+from .utils.reports import ReportHandler

src/ultra_rest_client/ultra_rest_client.py

@@ -954,6 +954,231 @@ def export_zone(self, zone_name):
         self.clear_task(task_id)
         return result
 
+    # Health Checks
+    def create_health_check(self, zone_name):
+        """Initiates a health check for a zone.
+
+        Arguments:
+        zone_name -- The name of the zone to perform a health check on.
+
+        Returns:
+        A dictionary containing the location header from the response, which includes
+        the timestamp identifier needed to retrieve the health check results.
+        """
+        return self.rest_api_connection.post(f"/v1/zones/{zone_name}/healthchecks", json.dumps({}))
+
+    def get_health_check(self, zone_name, timestamp):
+        """Retrieves the results of a previously initiated health check.
+
+        Arguments:
+        zone_name -- The name of the zone that was checked.
+        timestamp -- The timestamp identifier returned from create_health_check.
+
+        Returns:
+        A dictionary containing detailed health check results, including version,
+        state, and a list of check results with nested validation details.
+        """
+        return self.rest_api_connection.get(f"/v1/zones/{zone_name}/healthchecks/{timestamp}")
+
+    def create_dangling_cname_check(self, zone_name):
+        """Initiates a dangling CNAME (DCNAME) check for a zone.
+
+        Arguments:
+        zone_name -- The name of the zone to perform a dangling CNAME check on.
+
+        Returns:
+        A dictionary containing the response from the API. Note that while a location
+        header is returned, it is not used for retrieving results as only one set of
+        DCNAME results is kept per zone.
+        """
+        return self.rest_api_connection.post(f"/v1/zones/{zone_name}/healthchecks/dangling", json.dumps({}))
+
+    def get_dangling_cname_check(self, zone_name):
+        """Retrieves the results of a dangling CNAME check.
+
+        Arguments:
+        zone_name -- The name of the zone to retrieve dangling CNAME check results for.
+
+        Returns:
+        A dictionary containing detailed dangling CNAME check results, including version,
+        zone, status, resultInfo, and a list of dangling records.
+        """
+        return self.rest_api_connection.get(f"/v1/zones/{zone_name}/healthchecks/dangling")
+
+    def create_advanced_nxdomain_report(self, start_date, end_date, zone_names, limit=100):
+        """Initiates the creation of an Advanced NX Domain report.
+
+        This method sends a POST request to generate a report that identifies NX domain queries
+        (DNS queries for non-existent domains) for the specified zones within the given date range.
+
+        Arguments:
+        start_date -- Start date of the report in 'yyyy-MM-dd' format. Must not be more than 30 days prior to end_date.
+        end_date -- End date of the report in 'yyyy-MM-dd' format.
+        zone_names -- A single zone name (string) or a list of zone names to include in the report.
+        limit -- Optional. Number of records to return (default: 100, maximum: 100000).
+
+        Returns:
+        A dictionary containing the response from the API, including the requestId which can be used
+        with get_report_results() to retrieve the report data once processing is complete.
+        
+        Example response:
+        {
+            "requestId": "HQV_NXD-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxx"
+        }
+        """
+        # Ensure zone_names is a list
+        if isinstance(zone_names, str):
+            zone_names = [zone_names]
+        
+        payload = {
+            "hostQueryVolume": {
+                "startDate": start_date,
+                "endDate": end_date,
+                "zoneNames": zone_names
+            },
+            "sortFields": {
+                "nxdomainCount": "DESC"
+            }
+        }
+        
+        endpoint = f"/v1/reports/dns_resolution/query_volume/host?advance=true&reportType=ADVANCED_NXDOMAINS&limit={limit}"
+        return self.rest_api_connection.post(endpoint, json.dumps(payload))
+
+    def get_report_results(self, report_id):
+        """Retrieves the results of any report using the report ID.
+
+        This method sends a GET request to fetch the results of a previously initiated report.
+        The report may still be processing, in which case the response will indicate this status.
+
+        Arguments:
+        report_id -- The report ID returned from a report creation method (e.g., create_advanced_nxdomain_report).
+
+        Returns:
+        A dictionary or list containing the report results if the report is complete, or an error
+        message indicating the report is still processing.
+        """
+        return self.rest_api_connection.get(f"/v1/requests/{report_id}")
+
+    def create_projected_query_volume_report(self, accountName, sortFields=None):
+        """Initiates the creation of a Projected Query Volume Report.
+
+        This method sends a POST request to generate a report that provides projected query volume
+        data for the specified account.
+
+        Arguments:
+        accountName -- The name of the account for which the report is being run.
+        sortFields -- Optional. A dictionary defining sortable columns and their sort directions.
+                      Valid sortable columns include: 'month', 'currentDay', 'rspMtd', 'rspMtd7dAvg',
+                      'rspMtd30dAvg', 'ttlAvg', and 'rspDaily' (each with values 'ASC' or 'DESC').
+                      If not provided, a default sort will be applied (rspMtd: DESC).
+
+        Returns:
+        A dictionary containing the response from the API, including the requestId which can be used
+        with get_report_results() to retrieve the report data once processing is complete.
+        """
+        payload = {
+            "projectedQueryVolume": {
+                "accountName": accountName
+            }
+        }
+        
+        if sortFields:
+            payload["sortFields"] = sortFields
+        else:
+            payload["sortFields"] = {
+                "rspMtd": "DESC"
+            }
+        
+        return self.rest_api_connection.post("/v1/reports/dns_resolution/projected_query_volume", json.dumps(payload))
+
+    def create_zone_query_volume_report(self, startDate, endDate, zoneQueryVolume=None, sortFields=None, offset=0, limit=1000):
+        """Initiates the creation of a Zone Query Volume Report.
+
+        This method sends a POST request to generate a report that aggregates query volumes for multiple zones
+        over a specified period (up to 13 months).
+
+        Arguments:
+        startDate -- Start date of the report in 'YYYY-MM-DD' format.
+        endDate -- End date of the report in 'YYYY-MM-DD' format.
+        zoneQueryVolume -- Optional. A dictionary with additional fields (e.g., 'zoneName', 'accountName', 'ultra2').
+        sortFields -- Optional. A dictionary mapping sortable column names to sort directions ('ASC' or 'DESC').
+                      Valid sortable columns include: 'zoneName', 'startDate', 'endDate', 'rspTotal', etc.
+                      If not provided, default sort criteria will be applied.
+        offset -- Optional. Pagination offset (default: 0).
+        limit -- Optional. Pagination limit (default: 1000).
+
+        Returns:
+        A dictionary containing the response from the API, including the requestId which can be used
+        with get_report_results() to retrieve the report data once processing is complete.
+        """
+        if zoneQueryVolume is None:
+            zoneQueryVolume = {}
+        
+        zoneQueryVolume["startDate"] = startDate
+        zoneQueryVolume["endDate"] = endDate
+        
+        payload = {
+            "zoneQueryVolume": zoneQueryVolume
+        }
+        
+        if sortFields:
+            payload["sortFields"] = sortFields
+        else:
+            payload["sortFields"] = {
+                "zoneName": "ASC",
+                "endDate": "ASC"
+            }
+        
+        endpoint = f"/v1/reports/dns_resolution/query_volume/zone?offset={offset}&limit={limit}"
+        return self.rest_api_connection.post(endpoint, json.dumps(payload))
+
+    # Zone Snapshots
+    def create_snapshot(self, zone_name):
+        """Creates a snapshot of a zone.
+
+        This method sends a POST request to create a snapshot of the specified zone,
+        capturing its current state. A zone can only have one snapshot at a time.
+
+        Arguments:
+        zone_name -- The name of the zone to create a snapshot for.
+
+        Returns:
+        A dictionary containing the response from the API, including a task_id
+        that identifies the snapshot creation task.
+        """
+        return self.rest_api_connection.post(f"/v1/zones/{zone_name}/snapshot", json.dumps({}))
+
+    def get_snapshot(self, zone_name):
+        """Retrieves the current snapshot for a zone.
+
+        This method sends a GET request to fetch the current snapshot for the specified zone,
+        returning all details of the snapshot in a structured JSON object.
+
+        Arguments:
+        zone_name -- The name of the zone to retrieve the snapshot for.
+
+        Returns:
+        A dictionary containing detailed snapshot information, including the zone name
+        and a list of resource record sets (rrSets) with their properties.
+        """
+        return self.rest_api_connection.get(f"/v1/zones/{zone_name}/snapshot")
+
+    def restore_snapshot(self, zone_name):
+        """Restores a zone to its snapshot.
+
+        This method sends a POST request to restore the specified zone to the state
+        captured in its snapshot. This operation should be used with caution as it
+        will revert all changes made since the snapshot was created.
+
+        Arguments:
+        zone_name -- The name of the zone to restore from its snapshot.
+
+        Returns:
+        A dictionary containing the response from the API, including a task_id
+        that identifies the restore operation task.
+        """
+        return self.rest_api_connection.post(f"/v1/zones/{zone_name}/restore", json.dumps({}))
+
 def build_params(q, args):
     params = args.copy()
     if q: