Edge client - BlueCat Python Library - 22.4.1

BlueCat Python Library Guide

Locale
English (United States)
Product name
BlueCat Python Library
Version
22.4.1

Module for the client to work with BlueCat Edge’s API.

class bluecat_libraries.edge.api.client.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.

Parameters 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.

Parameters 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.

Parameters 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_v1_api_namespaces(namespace_id:str)

Delete the namespace specified by the namespace ID.

Parameters Description
namespace_id(str, required) The ID of the namespace to delete.

Example:

from bluecat_libraries.edge.api import EdgeClient

namespace_id = <namespace_id>

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

New in version 20.12.1.

delete_v2_domainlists(domain_list_id:str)

Delete the domain list specified by the domain list ID.

Parameters 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.

Parameters 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.

delete_v5_api_policies(policy_id:str)

Delete the policy specified by the policy ID.

Parameters Description
policy_id(str, required) The ID of the policy to delete.

Example:

from bluecat_libraries.edge.api import EdgeClient

policy_id = "<policy_id>"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.delete_v5_api_policies(policy_id)

New in version 20.12.1.

get_v1_api_apikeys()

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:Optional[str]=None, limit:Optional[int]=None, start_time:Optional[str]=None, end_time:Optional[str]=None, user_name:Optional[str]=None)

Return the audit log records of API requests and responses.

Parameters 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_authentication_token_describe()

Return information about the user whose credentials were used to obtain the authorization token.

Example:

from bluecat_libraries.edge.api import EdgeClient

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

print(current_user)

New in version 20.12.1.

get_v1_api_customer_dnsquerystats_count(start:int, downsample:int, end:Optional[int]=None)

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.

Parameters 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_topdomains(start:int, count:int, end:Optional[int]=None)

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

Parameters 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 most frequently queried domains info: domainName, 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:Optional[int]=None)

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.

Parameters 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()

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:Optional[str]=None, desired_result_count:Optional[int]=None)

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

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

Returns: A list of 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()

Return a list of domain lists.

Returns: A list of domain lists

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_list_dns()

for r in result:
    print(r)

New in version 20.12.1.

get_v1_api_list_dns_by_id(domain_list_id:str)

Return a list of domain lists.

Parameters 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_list_dns_search(name_contains:str, desired_result_count:int)

Return a list of domain lists with names containing the search fragment, stopping when the desired result count reaches.

Parameters Description
name_contains(str, required) Filter based on the name.
desired_result_count(int, required) The maximum number of returned results.

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_list_dns_search(<name_contains>, 10)

New in version 20.12.1.

get_v1_api_list_system(list_name:str)

Return the specified system-maintained domain lists, including all of the domains in the list, and the last time each listed domain incurred DNS traffic identifying it as suspected tunneling.

Parameters Description
list_name(str, required) The name of the list

Returns: The list of all the domains and the last time each listed domain incurred DNS traffic.

Return type: list

Example:

from bluecat_libraries.edge.api import EdgeClient

query_id = <query_id>

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

print(result)

New in version 20.12.1.

get_v1_api_list_system_content(list_name:str)

Return the contents of the specified system-maintained domain lists in JSON or CSV format. Leave out the Accept parameter to retrieve a CSV list instead of JSON. For each domain, the last time the domain incurred DNS traffic identifying it as a suspect for tunneling, and the time when that domain clears from the list according to the system-level set TTL, are returned.

Parameters Description
list_name(str, required) The name of the list

Returns: The contents of the specified system-maintained domain lists.

Return type: list

Example:

from bluecat_libraries.edge.api import EdgeClient

query_id = <query_id>

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

print(result)

New in version 20.12.1.

get_v1_api_list_system_information(list_name:str)

Return the meta information for the specified system-maintained domain list.

Parameters Description
list_name(str, required) The name of the list

Returns: The system-maintained domain list meta information.

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient

query_id = <query_id>

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

print(result)

New in version 20.12.1.

get_v1_api_namespaces(site_id:str='')

Return a list of namespaces, or namespaces associated with the site specified by site ID, if specified.

Parameters Description
site_id(str, optional) The ID of the site.

Returns: The namespaces (all or those associated with the given site).

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_namespaces()

for ns in result:
    print(ns)

New in version 20.12.1.

get_v1_api_namespaces_by_id(namespace_id:str)

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

Parameters Description
namespace_id(str, required) The ID of the namespace.

Returns: Information of the namespace including: id, name, description, forwarders, matchLists, exceptionLists, isDefault, associatedSiteSettings, ttl, umbrellaIntegrationId, latency

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient

namespace_id = <namespace_id>

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

print(result)

New in version 20.12.1.

get_v1_api_servicepoints()

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_settings()

Retrieve the automatic service point update settings.

Example:

from bluecat_libraries.edge.api import EdgeClient

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

New in version 20.12.1.

get_v1_api_spversions()

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_v1_api_tos()

Return the name, user email address, and timestamp when the current user accepted their Terms of Service.

Example:

from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.get_v1_api_tos()

New in version 20.12.1.

get_v1_api_users()

Return the list of users.

Returns: A list of all users.

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_users()

for user in result:
    print(user)

New in version 20.12.1.

get_v2_api_customer_dnsquerylog_count(site_name:str)

Returns the total count of logged DNS queries within 30 days for the specified site name.

Parameters Description
site_name(str, required) Site name to search for the count of DNS query logs

Returns: Count of logged DNS queries within 30 days for the specified site name.

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient

site_name = <site_name>

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

New in version 20.12.1.

get_v2_api_spimage_config(site_id:str)

Download the base64 encoded service point configuration information, including:

  • the endpoint to connect to for registration

  • the certificate that the service point uses to authenticate to its endpoint

  • the service point manager endpoint

Parameters Description
site_id(str, required) The id of the site

Returns: The base64 encoded service point configuration information.

Return type: str

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>)
    result = client.get_v2_api_spimage_config(site_id=site_id)

print(result)

New in version 20.12.1.

get_v2_api_spimage_status(site_id:str)

Retrieve the status of the image generation.

Parameters Description
site_id(str, required) The id of the site

Returns: The status of the image generation along with other information.

Return type: dict

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>)
    result = client.get_v2_api_spimage_status(site_id=site_id)

print(result)

New in version 20.12.1.

get_v2_domainlists(name_contains:Optional[str]=None)

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

Parameters 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)

Return a specific domain list.

Parameters 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_dnsquerylogs(filters:Optional[dict]=None)

Return a list of all (or optionally filtered) logged DNS queries.

Parameters Description
filters(dict, optional) The filters to narrow down the search result. The following filters (optional) can be used:
  • site_id (string or list) - The ID of the site to query for logs.

  • batch_size (integer) - The maximum number of records to return. Default size is 400. The maximum configurable size is 10000.

  • key (string) - The record ID of the DNS query log record to receive older or newer records.

  • order (string) - Specify whether to retrieve results in descending (default) or ascending order.

  • start_time (string) - Filter results for a specific time period, include the start time, in milliseconds since the Unix Epoch.

  • end_time (string) - Filter results for a specific time period, include the end time, in milliseconds since the Unix Epoch.

  • has_matched_policy (bool) - If true, only the DNS queries matching policies will display.

  • source_ip (string) - Filter results for the specified source IP address.

  • query_type (string) - The query record type to search for.

  • query_name (string) - The domain name to search for queries.

  • policy_action (string) - If one or more policy actions are provided, then only the policies matching the actions are returned. Valid actions are allow, block, redirect, and monitor.

  • policy_name (string) - If a policy name is provided, then only the policies matching the name are returned.

  • policy_id (string): If a policy ID is provided, then only the policies matching the ID are returned.

  • threat_type (string) - Return queries that match the specified threat type. Valid threat types are DGA and DNS_TUNNELING.

  • threat_indicator (string) - Return queries that match the specified threat indicator. Valid threat indicators are ENTROPY, UNIQUE_CHARACTER, EXCEEDING_LENGTH, UNCOMMON_QUERY_TYPE, VOLUMETRIC_TUNNELING, SUSPECT_DNS, and SUSPECT_TLD.

  • response_code (string) - The response code of the DNS query.

  • protocol (string) - The protocol of the DNS query (usually UDP or TCP).

  • namespace_id (string) - The ID of namespaces a DNS query was queried against.

Returns: The DNS queries (all or filtered).

Return type: list[dict]

Example:

from bluecat_libraries.edge.api import EdgeClient

filters = {
    "site_id": [<site_id_1>, <site_id_2>],
    "source_ip": "172.17.149.40"
}

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

for q in result:
    print(q)

New in version 20.12.1.

get_v3_api_dnsquerylogs_by_id(query_id:str)

Return the details for a specific query.

Parameters Description
query_id(str, required) The ID of the query.

Returns: Information of the DNS query including: time, source, siteId, query, queryType, response, id, actionTaken, matchedPolicies, authority, queryProtocol, threats, queriedNamespaces, latency

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient

query_id = <query_id>

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

New in version 20.12.1.

get_v3_api_sites(name:Optional[str]=None, name_contains:Optional[str]=None, fields:Optional[str]=None, desired_result_count:Optional[int]=None, namespace_id:Optional[str]=None, overrides_forwarders:Optional[bool]=None)

Return information about all the sites.

Parameters 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)

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

Parameters 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.

get_v5_api_policies(site_id:Optional[str]=None, site_group_id:Optional[str]=None, domain_list_id:Optional[str]=None)

Get a list of all policies, or policies associated with a specified site, site group, or domain list.

Parameters Description
site_id(str, optional) Specify a site by site ID to search for policies associated with a site.
site_group_id(str, optional) Specify a site group by site group ID to search for policies associated with a site group.
domain_list_id(str, optional) Specify a domain list by domain list ID to search for policies associated with a domain list.

Returns: A list of policies

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_v5_api_policies()

for r in result:
    print(r)

New in version 20.12.1.

get_v5_api_policies_by_id(policy_id:str)

Search for a policy by policy ID.

Parameters Description
policy_id(str, required) Specify a policy by ID to return.

Returns: Policy for the given policy ID.

Return type: 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_v5_api_policies_by_id(<policy_id>)

New in version 20.12.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_v1_api_namespaces(namespaces:list)

Set (up to three) namespaces as defaults.

Parameters Description
namespaces(list[dict], required) List of namespace names and flags.

Example:

from bluecat_libraries.edge.api import EdgeClient

namespaces = [
    {
        "id": "<id of the namespace>",
        "isDefault": "true" or "false"
    },
    {
        "id": "<id of the other namespace>",
        "isDefault": "true" or "false"
    }
]

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

New in version 20.12.1.

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

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

Parameters 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.

patch_v3_api_sites(payload:list)

Update the service point version of specified sites.

Note: You must disable the automatic service point updates to use this API.
Parameters Description
payload(list[dict]) A list of the sites whose service points should be updated. It is possible to exclude certain service points from the operation. Each item in the list represents a site and options for it.

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = [
    {
        "id": "33709b0b-d429-45f1-8c82-51b2942a9133",
        "version": "3.0.5",
        "blockedServicePointIds": [
            "feac4ad6-adb6-4c8d-924e-d314d29ec96d",
            "91cbda2f-ac60-4a32-bc9f-02161e532b2d"]
    },
    {
        "id": "aaa0830d-4639-4210-9158-0ac6395e2396",
        "version": "3.0.6"
    }
]

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

New in version 20.12.1.

post_v1_api_apikeys()

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_v1_api_customer_sitegroups_create(payload:dict)

Create a new site group with the sites specified by site ID.

Parameters Description
payload(dict, required) Payload used to create a site group.

Returns: The details of the site group created.

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient
payload = {
    "name":"name",
    "description":"description",
    "siteIds":["id1","id2"]
}

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

New in version 20.12.1.

post_v1_api_customer_sitegroups_delete(site_group_id:int)

Delete the site group specified by site group ID.

Parameters Description
site_group_id(int, required) The ID of the site group.

Example:

from bluecat_libraries.edge.api import EdgeClient

site_group_id = 2

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

New in version 20.12.1.

post_v1_api_customer_sitegroups_update(site_group_id:int, payload:dict)

Update the site group specified by site group ID with the new name, description, or sites.

Parameters Description
site_group_id(int, required) The ID of the site group.
payload(dict, required) Payload used to update the site group.

Example:

from bluecat_libraries.edge.api import EdgeClient

site_group_id = 2
payload = {
    "name":"name",
    "description":"description",
    "siteIds":["id1","id2"]
}

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

New in version 20.12.1.

post_v1_api_list_dns(payload:dict)

Create a domain list.

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

Returns: The created domain list.

Return type: dict

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_v1_api_list_dns(payload=payload)

print(result)

New in version 20.12.1.

post_v1_api_list_dns_attachfile(domain_list_id:str, file_handle)

Upload a CSV file containing a list of domain names to an existing DNS list.

Parameters Description
domain_list_id(str, required) The ID of the domain list.
file_handle(file, required) File handle that contains the domains.

Returns: A dictionary containing a number of registered domains.

Return type: dict

Example:

from bluecat_libraries.edge.api import EdgeClient

with EdgeClient(<edge_ci_url>) as client:
    with open('file.csv', 'r') as f:
        client.authenticate(<client_id>, <client_secret>)
        result = client.post_v1_api_list_dns_attachfile(<domain_list_id>, f)

New in version 20.12.1.

post_v1_api_list_dns_delete(domain_list_id:str)

Delete the domain list specified by the domain list ID.

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

Example:

from bluecat_libraries.edge.api import EdgeClient

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

New in version 20.12.1.

post_v1_api_list_dns_sourceconfiguration(domain_list_id:str, payload:dict)

Create a domain list sourced and dynamically updated from a local feed.

Parameters Description
domain_list_id(str, required) The ID of the domain list.
payload(dict, required) Source configuration payload.

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = {
            "hostName":"source.host.name.org",
            "privateKey":"privateKey",
            "filePath":"/location/location",
            "port":22,
            "transferType":"rsyncSSH",
            "user":"userName",
            "publicHostKey":"publicKey",
            "syncRate":5
        }
with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    result = client.post_v1_api_list_dns_sourceconfiguration(<domain_list_id>, payload)

New in version 20.12.1.

post_v1_api_list_dns_update(domain_list_id:str, payload:dict)

Update a domain list name, description, or source type.

Parameters Description
domain_list_id(str, required) The ID of the domain list to update.
payload(dict, required) Payload used to update the domain list.

Example:

from bluecat_libraries.edge.api import EdgeClient

domain_list_id = "<domain_list_id>"
payload = {
   "name": "new domain list name",
   "description": "new domain list description",
   "sourceType": "dynamic"
}

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.post_v1_api_list_dns_update(domain_list_id, payload)

New in version 20.12.1.

post_v1_api_namespaces(payload:dict)

Create a namespace.

Parameters Description
payload(dict, required) Payload used to create a namespace.

Returns: The ID of the created namespace.

Return type: str

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = {
   "name": "namespace",
   "description": "this is a namespace",
   "forwarders": ["8.8.8.8", "2.2.2.2"],
   "matchLists": ["domainListId1", "domainListId2"],
   "exceptionLists": ["domainListId1", "domainListId2"],
   "umbrellaIntegrationId": "<id of umbrella integration>",
   "ttl": 60
}

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

print(result)

New in version 20.12.1.

post_v1_api_users(payload:dict)

Create a new user. An email is sent to the user with a temporary password and instructions on how to log in and set a new password.

Parameters Description
payload(dict, required) Values for the user fields.

Returns: The ID of the created user.

Return type: str

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = {
    "email": "email address",
    "name": "first and last name",
    "role": "SYSADMIN | ADMIN | ANALYST",
    "status": "active | inactive"
}

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

print(result)

New in version 20.12.1.

post_v2_api_spimage_generate(payload:dict)

Retrieve an OVA image of the specified site.

Parameters Description
payload(dict, required) Payload (that contains site id) used to generate the OVA image.

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = {
    "siteId": <site_id>
}

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

print(result)

New in version 20.12.1.

post_v2_domainlists(payload:dict)

Create a domain list.

Parameters 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)

Create a new site.

Parameters 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.

Parameters 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.

post_v5_api_policies(payload:dict)

Create a new policy.

Parameters Description
payload(dict, required) Payload used to create a policy.

Returns: The ID of the created policy

Return type: str

Example:

from bluecat_libraries.edge.api import EdgeClient

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

New in version 20.12.1.

put_v1_api_namespaces(namespace_id:str, payload:dict)

Update the namespace specified by the namespace ID. Note that all the fields are updated with this action, whether you specify values or not. If you leave a field out, its value will be overwritten with no data.

Parameters Description
namespace_id(str, required) The ID of the namespace to update.
payload(dict, required) Payload used to update a namespace.

Example:

from bluecat_libraries.edge.api import EdgeClient

namespace_id = <namespace_id>
payload = {
   "name": "namespace",
   "description": "this is a namespace",
   "forwarders": ["8.8.8.8", "2.2.2.2"],
   "matchLists": ["domainListId1", "domainListId2"],
   "exceptionLists": ["domainListId1", "domainListId2"],
   "umbrellaIntegrationId": "<id of umbrella integration>",
   "ttl": 60
}

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

New in version 20.12.1.

put_v1_api_settings(payload:dict)

Update the automatic service point update settings.

Parameters Description
payload(dict) API parameters and their values

Example:

from bluecat_libraries.edge.api import EdgeClient

payload = {
    "spAutomaticUpdatesEnabled": "true" or "false"
}

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

New in version 20.12.1.

put_v1_api_users(user_id:str, payload:dict)

Update the email address, name, role, and status of the user specified by the user ID.

Parameters Description
user_id(str) ID of the user to update.
payload(dict) Values for the user fields.

Returns: The updated user.

Return type: dict

Note: You can’t update the email address of other users. You can only update your email address.

Example:

from bluecat_libraries.edge.api import EdgeClient

user_id = <user_id>
payload = {
    "email":"new email address",
    "name":"new name",
    "role":"ADMIN | ANALYST",
    "status":"active | inactive"
}

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

New in version 20.12.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.

Parameters 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.

Parameters 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"
     }
}

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.

put_v5_api_policies(policy_id:str, payload:dict)

Update the policy specified by the policy ID. Note that all the fields are updated with this action, whether you specify any values or not. If you leave a field out, it’s value will be overwritten with no data.

Parameters Description
policy_id(str, required) The ID of the policy to update.
payload(dict, required) Payload used to update the policy.

Example:

from bluecat_libraries.edge.api import EdgeClient

policy_id = "<policy_id>"

with EdgeClient(<edge_ci_url>) as client:
    client.authenticate(<client_id>, <client_secret>)
    client.put_v5_api_policies(policy_id, <payload>)

New in version 20.12.1.