EdgeClient - Platform - BlueCat Gateway - 20.12.1

Gateway Administration Guide

prodname
BlueCat Gateway
version_custom
20.12.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 Edge.

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

Log in to the 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_v1_api_namespaces(namespace_id: str)

Delete the namespace specified by the namespace ID.

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

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

delete_v5_api_policies(policy_id: str)

Delete the policy specified by the policy ID.

Parameter 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() -> 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_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: 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_topdomains(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 = None, desired_result_count: int = None) -> 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() -> list

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) -> 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_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.

Parameter 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) -> list

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.

Parameter 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) -> 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.

Parameter 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) -> dict

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

Parameter 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 = None) -> list

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

Parameter 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) -> dict

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

Parameter 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() -> 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_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() -> 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_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()-> list

Return a 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) -> dict

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

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

Returns: The 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) -> 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
Parameter 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) -> dict

Retrieve the status of the image generation.

Parameter 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: 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_dnsquerylogs(filters: dict = None) -> list

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

Parameter 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) -> dict

Return the details for a specific query.

Parameter 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: 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

get_v5_api_policies(site_id: str = None, site_group_id: str = None, domain_list_id: str = None) -> list

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

Parameter Description
site_id (str, optional) Specify a site by site ID to search for policies associated with one 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) -> dict

Search for a policy by policy ID.

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

Parameter Description
namespaces (list[dict], required) A 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: 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

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.
Parameter Description
payload (list[dict], required) 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() -> 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_v1_api_customer_sitegroups_create(payload: dict) -> dict

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

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

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

Parameter 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) -> dict

Create a domain list.

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

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

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

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

Parameter 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) -> str

Create a namespace.

Parameter 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) -> str

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.

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

Retrieve an OVA image of the specified site.

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

post_v5_api_sites_policies(payload: dict) -> str

Create a new policy.

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

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

Parameter Description
payload(dict, required) 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) -> dict

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

Note: You can't update the email address of other users. You can only update your email address.
Parameter Description
user_id (str, required) The ID of the user to update
payload(dict, required) Values for the user fields

Returns: The updated user.

Return type: dict

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.

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

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.

Parameter 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