EdgeClient - Platform - BlueCat Gateway - 20.6.1

Gateway Administration Guide

prodname
BlueCat Gateway
version_custom
20.6.1

This class facilitates calling the Edge CI API endpoints.

class bluecat_libraries.edge.api.EdgeClient(url)

Bases: bluecat_libraries.http_client.client.Client

Client uses the requests library to communicate with the REST endpoints of DNS Edge.

authenticate(client_id: str, client_secret: str, refresh_token: bool=False)

Log in to the DNS Edge CI using the access key set to retrieve a token and bearer type to populate the authorization header.

Parameter Description
client_id (str, required) Edge client ID
client_secret (str, required) Edge secret access key
refresh_token (bool, optional) Retrieve a new token even if logged in
Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
New in version 20.6.1

clear_token()

Clear token from client and session header

delete_v1_api_apikey(email_address)

Delete all the API access key sets for the specified email address.

Parameter Description
email_address (str, required)

Delete all the API access key sets associated with this email address

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.delete_v1_api_apikey(<email_address>)
New in version 20.6.1

delete_v1_api_apikey_by_id(client_id)

Delete the API access key set with the specified client ID for the current user.

Parameter Description
client_id (str, required)

The client ID that needs to be deleted

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.delete_v1_api_apikey_by_id(<client_id>)
New in version 20.6.1

delete_v2_domainlists(domain_list_id: str)

Delete the domain list specified by the domain list ID.

Parameter Description
domain_list_id (str, required)

Payload used to create a domain list

Example:
from bluecat_libraries.edge.api import EdgeClient

domain_list_id = "<domain_list_id>"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.delete_v2_domainlists(domain_list_id=domain_list_id)
New in version 20.6.1

delete_v3_api_sites(site_id: str)

Delete the site specified by the site ID.

Parameter Description
site_id (str, required)

The ID of the site to delete

Example:
from bluecat_libraries.edge.api import EdgeClient

site_id = "<site_id>"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.delete_v3_api_sites(site_id=site_id)
New in version 20.6.1

get_v1_api_apikeys() -> list

Return the API access key sets for the current user.

Returns: API access key sets for the current user.

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    results = client.get_v1_api_apikeys()

for result in results:
    print(result)
New in version 20.6.1

get_v1_api_audit_logs(offset: str = None, limit: int = None, start_time: str = None, end_time: str = None, user_name: str = None) -> list

Return the audit log records of API requests and responses.

Parameter Description
offset (str, optional) The number of records to skip, from the beginning of the log
limit (int, optional) The maximum number of records to retrieve
start_time (str, optional) The start time of the period to return logs for, in ISO_8601 format
end_time (str, optional) The end time of the period to return logs for, in ISO_8601 format
user_name (str, optional) To filter log records for a particular user, specify a user name

Returns: Audit log records of API requests and responses.

Return type: list

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_audit_logs()

for log in result:
    print(log)
New in version 20.6.1

get_v1_api_customer_dnsquerystats_count(start: int, downsample: int, end: int = None) -> list

Return the total count of logged DNS queries per policy action type in a Customer Instance for any time interval within the last 24 hours.

Parameter Description
start (int, required) The start of the time range, in milliseconds since the Unix Epoch
downsample (int, required) The sample period in the returned dataset, in minutes
end (int, optional) The end of the time range, in milliseconds since the Unix Epoch

Returns: DNS query count results including columns: time, totalQueries, totalAllowed, totalMonitored, totalRedirected, totalNonMatched.

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

start = 0         # Start of time range
downsample = 10   # Sample period of returned dataset

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    stats = client.get_v1_api_customer_dnsquerystats_count(start=start, downsample=downsample)

for stat in stats:
    print(stat)
New in version 20.6.1

get_v1_api_customer_dnsquerystats_topdomain(start: int, count: int, end: int = None) -> list

Return the specified number of domains most frequently queried per Customer Instance for any time interval within the last 24 hours.

Parameter Description
start (int, required) The start of the time range, in milliseconds since the Unix Epoch
count (int, required) The number of domains to return
end (int, optional) The end of the time range, in milliseconds since the Unix Epoch

Returns: The information of the most frequently queried domains: domain, hitCount

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

start = 0         # Start of time range
count = 10        # Number of results to return

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_customer_dnsquerystats_topdomains(start=start, count=count)

for domain in result:
    print(domain)
New in version 20.6.1

get_v1_api_customer_dnsquerystats_uniqueip(start: int, end: int = None) -> dict

Return the total number of unique client IPs that issued DNS queries in a Customer Instance for any time interval within the last 24 hours.

Parameter Description
start (int, required) The start of the time range, in milliseconds since the Unix Epoch
end (int, optional) The end of the time range, in milliseconds since the Unix Epoch. Defaults to None

Returns: Total number of unique client IPs that issued DNS queries in a Customer Instance with key “count”.

Return type: dict

Example:
from bluecat_libraries.edge.api import EdgeClient

start = 0         # Start of time range

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    stats = client.get_v1_api_customer_dnsquerystats_uniqueip(start=start)

print(stats["count"])
New in version 20.6.1

get_v1_api_customer_sitegroups() -> list

Gets a list of the site groups.

Returns: A list of all site groups.

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_customer_sitegroups()

for sp in result:
    print(sp)
New in version 20.6.1

get_v1_api_customer_sitesandsitegroups_search(name_contains: str, desired_result_count: int) -> list

Return a list of the sites that match the specified search string.

Parameter Description
name (str, required) Search for site and site group names which contain the specified string
desired_result_count (int, required) The maximum number of records to return

Returns: A list of all the sites that match the specified search string.

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

name_contains = "test"         # search key word
desired_result_count = 10      # max number of records to return

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_customer_sitesandsitegroups_search(name_contains=
                name_contains, desired_result_count=desired_result_count)

for s in result:
    print(s)
New in version 20.6.1

get_v1_api_list_dns_by_id(domain_list_id: str) -> list

Return a list of domain lists.

Parameter Description
domain_list_id (str, required) The ID of the domain list

Returns: Domain names of the given domain list.

Return type: List

Example:
from bluecat_libraries.edge.api import EdgeClient

domain_list_id = '3f76fe19-900d-47ff-b00c-c3cab6f40903'         # domain list ID

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.v1_api_list_dns_by_id(domain_list_id=domain_list_id)

for r in result:
    print(r)
New in version 20.6.1

get_v1_api_servicepoints() -> list

Return information about all currently registered service points.

Returns: Currently registered service points information including: id, name, siteId, lastSync, connectionState, connectionStateLastChanged, ipAddresses, loopbackIps, version, updateInitiatedTimestamp, updateStatus.

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_servicepoints()

for sp in result:
    print(sp)
New in version 20.6.1

get_v1_api_spversions() -> list

Return a list of available service point versions, listed from the most recently released version to the oldest supported version.

Returns: A list of available service point versions.

Return type: List[str]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v1_api_spversions()

for ver in result:
    print(ver)
New in version 20.6.1

get_v2_domainlists(name_contains: str = None) -> list

Return a list of domain lists (that match the specified search string).

Parameter Description
name_contains (str, optional) Search for domains which contain the specified string

Returns: A list of domain lists (that match the specified search string).

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v2_domainlists()

for r in result:
    print(r)
New in version 20.6.1

get_v2_domainlists_by_id(domain_list_id: str) -> dict

Return a specific domain list.

Parameter Description
domain_list_id (str, required) The ID of the domain list to return

Returns: Information of the domain list (that matches the given id) including: id, name, description, sourceType, domainCount, etc.

Return type: dict

Example:
from bluecat_libraries.edge.api import EdgeClient

domain_list_id = "<domain_list_id>"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v2_domainlists_by_id(domain_list_id=domain_list_id)

print(result)
New in version 20.6.1

get_v3_api_sites(name: str = None, name_contains: str = None, fields: str = None, desired_result_count: int = None, namespace_id: str = None, overrides_forwarders: bool = None) -> dict

Return information about all the sites.

Parameter Description
name (str, optional) Filter by the exact name of a site
name_contains (str, optional) Filter sites by part of a site name. The name and name_contains parameters are mutually exclusive and shouldn’t be used at the same time
fields (str, optional) Fields to include in the response. Example: ?fields=id,name will return a response that contains only the sites’ IDs and names
desired_result_count (int, optional) The number of sites to include in the response
namespace_id (str, optional) Filter sites by a specific namespace ID
overrides_forwarders(bool, optional)

Determine whether to include sites that have overriding forwarders for the specified namespace. Default is false. This parameter is only effective when used with the namespaceId parameter

Returns: Sites information including: id, name, location, settings, registeredServicePointCount, version, updateInitiatedTimestamp, updateStatus, blockedServicePointIds

Return type: list[dict]

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v3_api_sites()

for sp in result:
    print(sp)
New in version 20.6.1

get_v3_api_sites_by_id(site_id: str) -> dict

Return information of the site that matches the specified site ID.

Parameter Description
site_id (str, required) The ID of the site

Returns: Information of the site including: id, name, location, settings, registeredServicePointCount, updateStatus, updateInitiatedTime, version, blockedServicePointIds

Return type: Dict

Example:
from bluecat_libraries.edge.api import EdgeClient

site_id = '3f76fe19-900d-47ff-b00c-c3cab6f40903'         # Site ID

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.get_v3_api_sites_by_id(site_id=site_id)

print(result)
New in version 20.6.1

handle_error_response(response: requests.models.Response)

Handle a response that’s considered to be an error. If the response matches an Edge error, an EdgeErrorResponse is raised. Otherwise, the handling is delegated to the base class’ implementation.

patch_v2_domainlists(domain_list_id: str, domain_names_add: list = None, domain_names_remove: list = None)

Update the content of an existing domain list by adding or deleting domain names.

Parameter Description
domain_list_id (str, required) The ID of the domain list to update
domain_names_add (list, optional) The names of domains to add to the domain list
domain_names_remove (list, optional) The names of domains to remove from the domain list
Example:
from bluecat_libraries.edge.api import EdgeClient

domain_list_id = "<domain_list_id>"
domain_names_add = ["name-001", "name-002"]
domain_names_remove = ["name-003", "name-004"]

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.patch_v2_domainlists(domain_list_id=domain_list_id, domain_names_add=domain_names_add,
     domain_names_remove=domain_names_remove)
New in version 20.6.1

post_v1_api_apikeys() -> dict

Create an API access key set for the current user.

Returns: Dictionary containing clientId and clientSecret that is created.

Return type: Dict

Example:
from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    api_key = client.post_v1_api_apikeys()

print(api_key)
New in version 20.6.1

post_v2_domainlists(payload: dict) -> str

Create a domain list.

Parameter Description
payload (dict, required) Payload used to create a domain list

Returns: The ID of a new domain list.

Return type: str

Example:
from bluecat_libraries.edge.api import EdgeClient

payload = {
    "name": "<domain-list-name>",
    "description": "<domain-list-description>",
    "sourceType": "user"
}

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.post_v2_domainlists(payload=payload)

print(result)
New in version 20.6.1

post_v3_api_sites(payload: dict) -> str

Create a new site.

Parameter Description
payload (dict, required) Payload used to create a site

Returns: The ID of the created site.

Return type: str

Example:
from bluecat_libraries.edge.api import EdgeClient

payload = {
    "name": "<site-name>",
    "location": {
    "address": "<address>"
    }
}

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.post_v3_api_sites(payload=payload)

print(result)
New in version 20.6.1

post_v3_api_sites_clearcache(site_id: str)

Clear the cache of a site.

Parameter Description
site_id (str) The ID of the site
Example:
from bluecat_libraries.edge.api import EdgeClient

site_id = "28c1b312-55e0-4dc4-8253-de7ae37db25d"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.post_v3_api_sites_clearcache(site_id)
New in version 20.6.1

put_v2_domainlists(domain_list_id: str, domain_names: list)

Replace all domains within a domain list by supplying a list of domain names.

Parameter Description
domain_list_id (str, required) The ID of the domain list to update
domain_names (list, required) The names of domains to replace existing with
Example:
from bluecat_libraries.edge.api import EdgeClient

domain_list_id = "<domain_list_id>"
domain_names = ["name-001", "name-002"]

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.put_v2_domainlists(domain_list_id=domain_list_id, domain_names=domain_names)
New in version 20.6.1

put_v3_api_sites(site_id: str, payload: dict)

Update an existing site. Note that all the parameters are updated with this action, whether you specify the values or not. If you leave a parameter out, its value will be overwritten with no data.

Parameter Description
site_id (str) The ID of the site
payload (dict) Site parameters and their new values
Example:
from bluecat_libraries.edge.api import EdgeClient

site_id = "28c1b312-55e0-4dc4-8253-de7ae37db25d"
payload = {
    "name": "the new site name",
    "location": {
         "address": "123 Main St., Toronto",
         "lng": "-79.3756671",
         "lat": "43.6421529"
     },
     "settings": {
         "timeZone": "Australia/Sydney",
         "associatedNamespaces": [
              {
                  "id": "a27a38ab-c377-4706-b4a0-cbf99b2ffd8a",
                  "overridingFowarders": []
              }
          ]
      }
}

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.put_v3_api_sites(site_id, payload)
New in version 20.6.1