api module - Platform - BlueCat Gateway - 21.11.2

Gateway Administration Guide

Locale
English
Product name
BlueCat Gateway
Version
21.11.2

This is the main entry point for the API. The most common usage pattern is to create a connection via instantiation, login with the login method, then retrieve a configuration object via get_configuration or get_configurations.

class bluecat.api.API(url, sslverify=False, ca_file=None, ca_path=None, use_rest=True, logger=None)

Bases: object

Create a connection to the BAM API.

Parameters Description
url URL of the BAM API (can be http or https).
sslverify Whether or not to verify the certificate installed on the BAM. Will generally be false for self signed certificates.
ca_file Name of the file listing CA’s for use in verification.
ca_path CA path used for verification.
Note: Changed in version 21.5.1: The SOAP client to BAM’s API is deprecated and will no longer be returned by this method. That obsoletes parameter use_rest, which is now ignored. It will be removed in a future release.

add_default_access_right(recipient_id, value, overrides='', properties='')

Parameters Description
recipient_id The object ID of the user or user group the access right is applied to.
value The value of the access right being added.
overrides A list of type-specific overrides.
properties A string including the following options:
  1. workflowLevel

  2. deploymentAllowed

  3. quickDeploymentAllowed

Returns: Object ID of a created Access Right.

add_group(name, properties='')

Add a user group

Parameters Description
name The name of the user group.
properties Adds object properties, including user-defined fields.

Returns: Returns the object ID for the new BAM user group.

add_tag_group(name, properties=None)

Creates a tag group and return its entity id (not per Configuration).

Parameters Description
name Name of tag group to be created.
properties Optional properties, including user-defined fields.

Returns: Object ID of created tag group.

add_user(username, password, email='e@e', user_access_type='API', properties='')

Add a user to BAM; available options are listed in the options variable.

Parameters Description
username The name of the user.
password The BAM password for the user (must be set even if the authenticator property option is defined).
email The email address for the user (required).
user_access_type API, GUI, or GUI and API (required).
properties String containing UDFs and options listed in the options variable. Multiple values can be separated by a | (pipe) character. You must add a | (pipe) character at the end in the properties string.

Returns: Returns the object ID for the new Address Manager user

add_user_defined_field(obj_type:str, udf:bluecat.udf.UserDefinedField)

Add a user-defined field (UDF) to the given BAM object.

Parameters Description
obj_type(str) BAM object type to which this UDF belongs. e.g. “Zone”
udf(UserDefinedField) The user-defined field assigned to an object of UserDefinedField type.

Returns: BAM response of addUserDefinedField

Return type: str

Example:

from bluecat.constants import EntityType

api = g.user.get_api()     # get api object
udf = UserDefinedField({
    "name": 'name-1',                     # required
    "displayName": 'display name -1',     # required
    "type": 'TEXT',                       # required
    "defaultValue": 'default',
    # comma separated string of key=value
    # valid keys: 'min' 'max' 'minLength' 'maxLength' 'pattern'
    # values cannot contain comma
    "validatorProperties": 'minLength=5,maxLength=10',
    # pipe separated and ended string, values cannot contain pipe
    "predefinedValues": '',
    # pipe separated and ended string of property=value, values cannot contain pipe
    "properties": '',
    "required": False,
    "hideFromSearch": False
})
res = api.add_user_defined_field(EntityType.ZONE, udf)

create_configuration(name)

Creates a configuration in BAM with the given name.

custom_search(filters, entity_type)

Search for an array of entities by specifying object properties. Supported for BAM version 8.1.1 or greater

Parameters Description
filters The list of properties on which the search will be based. List and String formats are supported.
entity_type The object type that you wish to search.

Returns: An iterator to the search results; function will make backend calls for every 1000 returned records.

delete_configuration(name='', entity_id=0)

Delete a configuration using name or id. Does not need both.

Parameters Description
name The name of the BAM configuration.
entity_id The object ID of the configuration in the BAM database.

delete_group(name='', entity_id=0)

Delete a group, accepts either the group’s name or id.

Parameters Description
name The name of the BAM user group.
entity_id The object ID of the user group in the BAM database.

delete_user(name='', entity_id=0)

Delete a user, can use either username or id to specify which user to delete.

Parameters Description
name The name of the BAM user.
entity_id The object ID of the user in the BAM database.

Returns: None, if successful. Raises PortalException on error.

delete_user_defined_field(obj_type:str, name:str)

Delete the user-defined field (UDF) from the given BAM object.

Parameters Description
obj_type(str) The BAM object to which the UDF belongs
name(str) The internal name of the UDF

Returns: BAM response of deleteUserDefinedField

Return type: str

Example:

from bluecat.constants.import EntityType

res = api.delete_user_defined_field(EntityType.ALIAS_RECORD, 'some_field')

New in version 21.5.1.

get_aliases_by_hint(hint, retrieve_fields=True)

Get a list of alias records that matches the hint criteria.

Parameters Description
hint The following wildcards are supported in the hint option:
  • ^-matches the beginning of a string. For example: ^ex matches example but not text.

  • $-matches the end of a string. For example: ple$ matches example but not please.

  • ^ $-matches the exact characters between the two wildcards. For example: ^example$ only matches example.

  • ?-matches any one character. For example: ex?t matches exit.

  • *-matches one or more characters within a string. For example: ex*t matches exit and excellent.

retrieve_fields Boolean input. Will not include UDFs in results if False.

Returns: A List of alias_records.

get_all_used_locations()

Returns an array of all used locations found in BAM (not per configuration).

Returns: Returns an array of all used locations; returns an empty list if no results are found.

get_api_client(url, use_rest, **kwargs)

Generate an API Client based on the communication method set for the Gateway.

Parameters Description
url URL to the WADL file.
use_rest Whether to use REST or SOAP.
kwargs Any keyword arguments for the client.

Returns: The initialized client.

Note: This method does not return the API client used by the instance of the bluecat.api.API class, but creates a new instance of an (underlying) API client.
Note: Changed in version 21.5.1: The SOAP client to BAM’s API is deprecated and will no longer be returned by this method. That obsoletes parameter use_rest, which is now ignored. It will be removed in a future release.

get_audit_logs(interval='5 hours', transaction_id=None, descending=False, version=2)

Gets Audit logs.

Attention: This API method requires the following:
  • BAM v9.0.0 or greater

  • Configuration of the BlueCat Gateway server IP address in the BAM Administration Console. For more information, refer to the section ‘Adding host access to the database’ in the Address Manager Administration Guide.

Parameters Description
interval(str, optional) The time period of the audit logs. The interval string accepts the following format:
  • interval='quantity unit'

where quantity is a number and unit can be millennium, century, decade, year, month, week, day, hour, minute, second, millisecond, or microsecond. It can either be in abbreviation (y, m, d, etc.) or plural form (months, days, etc.).

transaction_id(int, optional) The transaction ID of the audit logs. The default value is None and if specified, only gets logs greater than the given transaction ID.
descending(bool, optional) Orders logs based on the time of creation. The default value is False which orders logs in ascending order.
version(int, optional) Version of API, Current version support: 1, 2
  • version 1: All values are transmitted verbatim, e.g., this may result in string values (I, U, D) for type. Refer to version 2 of the API for a friendlier behavior.

  • version 2: Returns type as a string (Insert, Delete, Update) and comments are parsed to remove the keyword “CLIENT:”

Returns: Returns a generator that yields a dictionary representing a single log entry.

Raises:
  • PortalException – If BAM version is lower than 9.0.0.

  • PortalException – If version is not supported

Example:

api = g.user.get_api()                   # get api object
audit_logs = api.get_audit_logs('1 day')

for log in audit_logs:
    print(log)

get_audit_trail(entity_id, descending=True, start=0, count=10, version=1)

Gets Audit trail of transactions performed on a BAM object

Attention: This API method requires the following:
  • BAM v9.0.0 or greater

  • Configuration of the BlueCat Gateway server IP address in the BAM Administration Console. For more information, refer to the section ‘Adding host access to the database’ in the Address Manager Administration Guide.

Parameters Description
entity_id(int) The ID of the entity for which to retrieve transaction logs.
descending Orders results by the time of creation. Defaults to True.
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of transactions to retrieve about the entity. Defaults to 10.
version(int, optional) The version of the functionality. Allowed values: 1. Defaults to 1.

Type: bool, optional

Returns: Returns a generator that yields a dictionary representing a single log entry.

Raises:
  • PortalException – If BAM version is lower than 9.0.0.

  • PortalException – If limit is not between 1 and 50

  • PortalException – If version is not supported

Example:

api = g.user.get_api()                       # get api object
entity_id = 10081                            # Retrieve audit trail logs for entity_id
start = 0                                    # the index to start on (starts at 0)
count = 10                                   # number of elements to return

audit_trail = api.get_audit_trail(entity_id, True, start, count)

for trail in audit_trail:
    print(trail)

New in version 20.1.1.

get_bam_db_stats(indicators, version=1)

Get BAM database stats including the size of the database and a count for the number of objects of a certain type.

Attention: This API method requires the following:
  • BAM v9.0.0 or greater

  • Configuration of the BlueCat Gateway server IP address in the BAM Administration Console. For more information, refer to the section ‘Adding host access to the database’ in the Address Manager Administration Guide.

Parameters Description
indicators(list) Takes a list of object types to retrieve the database count for, supported types are listed in bluecat.constants.BAMStats.
version(int, optional) API version number

Returns: Returns a dictionary with object type as the key and count as the value.

Raises: PortalException – If BAM version is lower than 9.0.0.

Example:

from bluecat.constants import BAMStats

api = g.user.get_api()     # get api object
stats = api.get_bam_db_stats([BAMStats.IP4Network, BAMStats.MAC_ADDRESS])

New in version 20.1.1.

get_by_object_types(pattern, types)

Warning: This method has been deprecated, use search_by_object_types instead.

Gets objects based on a search pattern and a list of object types.

Parameters Description
pattern Search pattern string (will match any of the various properties of a BAM entity).
types List of BAM entity types (e.g. [entity.View, entity.Configuration])

Returns: An iterator for objects found that match the pattern and types. Only the consistency of the first 1000 results can be guaranteed.

get_configuration(name)

Get a named configuration.

Parameters Description
name Name of the BAM configuration.

Returns: configuration object of the named configuration.

get_configurations()

Get all configurations.

Returns: Iterator of Configuration objects. Only the consistency of the first 1000 results are guaranteed.

get_country_locations()

Returns an iterator for all parent locations (countries) found in BAM (not per configuration).

Returns: An iterator for all country locations. Only the consistency of the first 1000 results are guaranteed.

get_default_access_right(recipient_id)

Get an Access Right API Object.

Parameters Description
recipient_id The object ID of the user or user group the access right is applied to.

Returns: Access Right object.

get_deployment_task_status(deployment_token)

Parameters Description
deployment_token The string token value that is returned from the selective_deploy API method.

Returns: Returns a JSON with the overall deployment status and the deployment status of individual entities. The request section displays a list of the entity IDs that were defined in the creation of the deployment task using the selective_deploy API method. The status section displays the status of the deployment. The deployment status can be QUEUED, STARTED, FINISHED, or TASK_NOT_FOUND. The responses section contains specific information about the entities including the ID of the entity, the fully qualified domain name (FQDN), record type, TTL value, record data, the operation performed on the resource record, and the result of the deployment. The errors section lists out any errors encountered during the deployment. If all entities deployed successfully, the section displays an empty list.

get_entities(parent_id:int, entity_type:str, start:int=0, count:int=100)

List entities (of certain type) that are children of a specified parent.

Parameters Description
parent_id(int) ID of the parent entity. Use the value of 0 to obtain entities without a parent. For example, Configurations.
entity_type(str) Type of the child entities. BlueCat recommends to use the constants defined in EntityType.
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of elements to be returned. Defaults to 100.

Returns: A list of instances of a specific entity type or the generic Entity class.

Return type: list

Example:

from bluecat.constants import EntityType

parent_id = 5           # ID of the parent entity
api = g.user.get_api()  # a user-aware bluecat.api.API instance

entities = api.get_entities(parent_id, EntityType.ZONE, start=0, count=10)

for entity in entities:
    print(entity.get_name())

New in version 20.3.1.

get_entities_by_name(parent_id, name, entity_type, start=0, count=100)

Get a generator yielding entities (of certain type) with a specified name.

Parameters Description
parent_id(int) ID of the parent entity. Note that configurations have 0 as parent_id.
name(str) Name of the requested entities.
entity_type Type of the requested entities.
start(int, optional) Beginning position in a complete list of results. Useful for pagination. Defaults to 0.
count(int, optional) Number of requested elements. Useful for pagination. Defaults to 100.

Returns: A generator over a sequence of instances of the corresponding entity type.

Return type: Iterator[Entity]

Raises: BAMException – There is an error in communicating with BAM or the request cannot be serviced by BAM, e.g., bad input parameters.

Example:

from bluecat.constants import EntityType

parent_id = 5           # ID of the parent entity
name = 'DMZ West'       # name you search by
api = g.user.get_api()  # a user-aware bluecat.api.API instance

entities = api.get_entities_by_name(parent_id, name, EntityType.ZONE, start=0, count=10)

for entity in entities:
    print(entity)
    print(entity.get_name())
    print(entity.get_properties())

New in version 20.1.1.

get_entity_by_id(entity_id)

Get an entity by its ID. The returned object is of the correct class, or if none is defined, is an entity instance.

Parameters Description
entity_id BAM entity ID (note that these are unique across all configurations).

Returns: Returns objects from the database referenced by their database ID and with its properties fields populated.

get_group(group_name)

Get Group

Parameters Description
group_name Group name.

Returns: User Group.

get_host_records_by_hint(hint, retrieve_fields=True)

Get a list of host records that matches the hint criteria.

Parameters Description
hint(str) The partial or full keyword that returns the host records. The following wildcards are supported in the hint option: ^-matches the beginning of a string. For example: ^ex matches example but not text. $-matches the end of a string. For example: ple$ matches example but not please. ^ $-matches the exact characters between the two wildcards. For example: ^example$ only matches example. ?-matches any one character. For example: ex?t matches exit. *-matches one or more characters within a string. For example: ex*t matches exit and excellent.
retrieve_fields(bool) Includes UDFs in the list of host records. The default value is true. If set to false, the UDFs are not included in the list.

Returns: A list of host records.

get_ip4_leases(order_by:Optional[str]=None, descending:bool=False, start:int=0, count:int=10, version:int=1, filters:Optional[Dict]=None)

Get the IPv4 lease information.

Parameters Description
order_by(str, optional) Determines which key value should be used to order the list. All valid parameters are in IP4LeaseFields. Defaults to None.
descending(bool, optional) Returns the list in descending order or not. Defaults to False.
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of elements to be returned. Defaults to 10.
version(int, optional) The version of the functionality. Allowed values: 1. Defaults to 1.
filters(Dict, optional) A dictionary containing a list of column names that filtered the returned results.
Returns: Returns a list that yields a dictionary representing a single ip4 lease. The dictionary yields the following key and values:
  • ip_address_id, int: The ID number of the IP address.

  • ip_address, str: The integer value of the IP address.

  • conf_id, int: The ID of the configuration to which the IP address belongs.

  • mac_address, str: The MAC address of the client to which the IP address was assigned.

  • last_dhcp_status, (int, None): The last DHCP status of the object. The following are status codes for last_dhcp_status:

    • DHCP_ALLOCATED = 513

    • DHCP_FREE = 514

    • LEASED = 522

    • GATEWAY = 766

  • lease_time, (datetime, None): The timestamp of when the lease for the IP address was offered.

  • expire_time, (datetime, None): The timestamp of when the lease of the IP address expires.

  • circuit_id, (str, None): The ID of the circuit from which the request came.

  • remote_id, (str, None): The ID of the relay agent.

  • clienthost_name, (str, None): The hostname of the client to which the IP address was assigned.

  • update_count, int: The number of updates to the lease.

  • last_update_time, datetime: The timestamp of when the lease was last updated.

  • id, int: The unique ID number of the object.

  • dhcp_client_identifier, (str, None): The unique identifier for the client’s lease. The client identifier chosen by a DHCP client must be unique to that client within the subnet to which the client is attached.

  • parameter_request_list, (str, None): The list of parameters that the device requested from the DHCP server.

  • vendor_class_identifier, (str, None): The identifier sent by the DHCP client software running on the device.

Example:

from bluecat.constants import IP4LeaseFields

api = g.user.get_api()
lease_limit = 20 # the limit for the returned elements
start_val = 0 # the index to start on (starts at 0)
order_by = IP4LeaseFields.IP_ADDRESS_ID   # the order the query should be set to
filters = {ip_address: '127.0.0.1', conf_id: 1, mac_address: '00:1A:FF:3A:FF:00'}
ip4_leases = api.get_ip4_leases(order_by=order_by, descending=True, limit=limit, filters=filters)

for lease in ip4_leases:
    print(lease)

get_ip6_leases(order_by:Optional[str]=None, descending:bool=False, start:int=0, count:int=10, version:int=1, filters:Optional[Dict]=None)

Get the IPv6 lease information.

Parameters Description
order_by(str, optional) Determines which key value should be used to order the list. All valid parameters are in IP6LeaseFields. Defaults to None.
descending(bool, optional) Returns the list in descending order or not. Defaults to False.
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of elements to be returned. Defaults to 10.
version(int, optional) The version of the functionality. Allowed values: 1. Defaults to 1.
filters(Dict, optional) A dictionary containing a list of column names that filtered the returned results.
Returns: Returns a list that yields a dictionary representing a single ip6 lease. The dictionary yields the following key and values:
  • ip_address_id, int: The ID number of the IP address.

  • ip6_address_high, (str, None): The integer value of the high-order 64-bits of the IP address.

  • ip6_address_low, (str, None): The integer value of the low-order 64-bits of the IP address.

  • conf_id, int: The ID of the configuration to which the IP address belongs.

  • duid_id, int: The DUID of the client to which the IP address was assigned.

  • last_dhcp_status, (int, None): The last DHCP status of the object. The following are status codes for last_dhcp_status:

    • DHCP_ALLOCATED = 513

    • DHCP_FREE = 514

    • LEASED = 522

    • GATEWAY = 766

  • lease_time, (datetime, None): The timestamp of when the lease for the IP address was given.

  • expire_time, (datetime, None): The timestamp of when the lease of the IP address expires.

  • circuit_id, (str, None): The ID of the circuit from which the request came.

  • remote_id, (str, None): The ID of the relay agent.

  • clienthost_name, (str, None): The hostname of the client to which the IP address was assigned.

  • update_count, int: The number of updates to the lease.

  • last_update_time, datetime: The timestamp of when the lease was last updated.

  • id, int: The unique ID number of the object.

Example:

from bluecat.constants import IP6LeaseFields

api = g.user.get_api()
lease_limit = 20  # the limit for the returned elements
start_val = 0 # the index to start on (starts at 0)
order_by = IP6LeaseFields.IP_ADDRESS_ID   # the order the query should be set to
filters = {ip_address: '0000:0001:0000::8888', conf_id: 1}
ip6_leases = api.get_ip6_leases(order_by=order_by, descending=True, limit=limit, filters=filters)

for lease in ip6_leases:
    print(lease)

get_location_by_code(code)

Use this method to get the location object with the specified hierarchical location code.

Parameters Description
code The hierarchical location code, consisting of a set of 1 to 3 alpha-numeric strings separated by a space. The first two characters indicate a country, followed by next three characters which indicate a city in UN/LOCODE. New custom locations created under a UN/LOCODE city are appended to the end of the hierarchy. For example, CA TOR OF1 indicates:
  • CA for Canada

  • TOR for Toronto

  • OF1 for Office 1

Note: The code is case-sensitive. It must be all UPPER CASE letters. The county code and child location code should be alphanumeric strings.

Returns: The location entity object that corresponds to the location code.

get_parent_chain(entity_list, version=1)

Get the parent chain (configuration, view, and zone) for each of a list of entities.

The operation is applicable to a subset of entity types. The allowed ones are listed in constants.GetParentChainDiscriminatorsTypes.

Parameters Description
entity_list(Iterable[]) A list of entities whose parent chains are to be obtained.
version(int, optional) The version of the functionality. Allowed values: 1. Defaults to 1.
Returns: A list of dictionaries with the requested details. Each one has the following keys and values:
  • id (int) - ID of the entity.

  • type (str) - Entity type of the entity.

  • entity_name (str) - Name of the entity.

  • zone_name (str, may be None) - Name of the zone of the entity.

  • view_name (str) - Name of the view of the entity.

  • configuration_name (str) - Name of the configuration of the entity.

Return type: Iterator[Dict]

Raises:
  • PortalException – If BAM version is lower than 9.0.0.

  • PortalException – If version is not supported

Example:

api = g.user.get_api() # get api object
host_record_id1 = 10234
host_record_id2 = 23232
record1 = api.get_entity_by_id(host_record_id1) # get entity objects
record2 = api.get_entity_by_id(host_record_id2)

bulk_value = api.get_parent_chain([record1, record2])

for value in bulk_value:
    print(value)

New in version 20.1.1.

get_portal_version()

Get the version of BlueCat Gateway’s API.

get_system_info()

Get current system information of the BAM server.

Returns: Returns BAM system information in the form of a name/value pair dictionary.

get_tag_group_by_name(name)

Get a named tag group.

Parameters Description
name Name of the tag group.

Returns: A tag group entity object with given name.

get_tag_groups()

Returns an iterator of tag groups found in BAM (not per Configuration).

Returns: An iterator of all tag.TagGroup objects. Only the consistency of the first 1000 results are guaranteed.

get_url()

Get the URL of the application.

get_user(username)

Get a named user.

Parameters Description
username Username of the BAM user.

Returns: User object for the username.

get_user_sessions(begin_time:Optional[datetime.datetime]=None, end_time:Optional[datetime.datetime]=None, include_system_user:bool=False, descending:bool=False, start:int=0, count:int=10, version:int=1)

Get an iterator yielding user sessions. The request may limit the result by time frame.

Attention: This functionality requires the following:
  • BAM v9.0.0 or greater

  • Configuration of the BlueCat Gateway server IP address in the BAM Administration Console. For more information, refer to the section ‘Adding host access to the database’ in the Address Manager Administration Guide.

Parameters Description
begin_time(datetime, optional) Beginning of the time period for which user sessions are obtained. The value is included in the interval. Defaults to no limit.
end_time(datetime, optional) End of the time period for which user sessions are obtained. The value is included in the interval. Defaults to no limit.
include_system_user(bool, optional) Determines whether the sessions of the system user should be included in the result. Defaults to False.
descending(bool, optional) Whether the returned elements to be in reverse chronological order (of the login time). Defaults to False.
start(int, optional) Indicates where in the list of objects to start returning objects. The list begins at an index of 0. Defaults to 0.
count(int, optional) The maximum number of elements to be returned. Defaults to 10.
version(int, optional) Version of the functionality that is to be used. Allowed values: 1. Defaults to 1.
Returns: An iterator over a sequence of dictionaries, each representing a user session and having the following keys:
  • id (int) - ID of the user session.

  • user_id (int) - ID of the user.

  • username (str) - Username of the user.

  • login_timestamp (datetime) Date and time when the user logged into the system.

  • logout_timestamp (datetime), may be None - Date and time when the user logged out of the system.

  • state (int) - ID of the state of the session. The valid values are defined in UserSessionState.

  • machine_ip (str), may be None - IP address of the device used to log into the system.

  • authenticator_id (int), may be None - ID of the authenticator.

  • authenticator_name (str), may be None - Name of the authenticator.

  • response (str), may be None - Response from the authenticator.

Raises: The following cases cause an exception to be raised:
  • The version of BlueCat Address Manager is prior to 9.0.0.

  • Invalid value for parameter version is provided.

Note: One or both boundaries of a time interval may be specified to filter the obtained sessions. Inclusion is determined by comparison with the login time of each session. Therefore, only sessions that have started during it are returned. If a session has started before the beginning of the interval and is active during it, it will not be included in the result.
Note: The login time of each session, used for filtering, is in the timezone of BlueCat Address Manager. For consistent results, ensure that the passed parameters are in that appropriate timezone.

Example:

from datetime import datetime, timedelta

begin_time = datetime(2019, 10, 13, 6, 0, 0)  # fixed start of the interval
end_time = begin_time + timedelta(hours=6)    # end of the interval 6 hours later
api = g.user.get_api()                        # a user-aware bluecat.api.API instance
start = 0                                     # the index to start on (starts at 0)
count = 10                                    # the number of elements to return

sessions = api.get_user_sessions(begin_time, end_time, include_system_user=False,
                                 start=start, count=count)

for session in sessions:
    print(session)

New in version 20.1.1.

get_version()

Get current system version from the system information as <major>.<minor>.<patch>.

Return value None means this client has never been logged into.

Returns: Version string. eg. ‘8.0.0’

instantiate_entity(e)

Instantiate an appropriate Python class given an entity returned from a BAM API call.

Parameters Description
e BAM API entity.

Returns: A type specific instance object of the API entity or generic entity object. None if there is no type.

login(username, password)

Login to the BAM API using the supplied username and password. The user must be set up with API access via the BAM GUI. All normal permissioning applies.

Parameters Description
username BAM username.
password BAM password.

logout()

Logout from the BAM API.

raw_api

A raw client to the Address Manager v1 API service.

The client and its methods are created dynamically based on the WADL specification of the service of the connected Address Manager. The names of the methods, their parameters, and all input and output types match the Address Manager API.

Note: The use of this API client is discouraged. It is provided as a last resort for accessing BAM endpoints that do not have a corresponding wrapper in the “API specifications Client” (see spec_api).

Example:

from bluecat_libraries.address_manager.constants import ObjectType

api = g.user.get_api() # a user-aware bluecat.api.API instance

# NOTE: No need to login.
# Ignore that there is `get_entities`, call the BAM endpoint directly.
data = api.raw_api.getEntities(0, ObjectType.CONFIGURATION, 0, 10)

for item in data:
    print(item["name"])

New in version 21.5.1.

search_by_object_types(pattern, types)

Search for objects based on a search pattern and a list of object types.

Parameters Description
pattern(str) Search pattern string (matches any of the various properties of a BAM entity).
types(list) List of BAM entity types (e.g. [EntityType.View, EntityType.Configuration])

Returns: An iterator for objects found that match the pattern and types. Only the consistency of the first 1000 results can be guaranteed.

search_response_policy_items(keyword, scope, start=0, count=10, properties='')

Get an array policy items for searched key words, for all the possible scope types use the constant class constants.ResponsePolicyItemSearchScope

Parameters Description
keyword The search string for which you wish to search.
  • ^—matches the beginning of a string. For example: ^ex matches example but not text.

  • $—matches the end of string. For example: ple$ matches example but not please.

  • *—matches zero or more characters within a string. For example: ex*t matches exit and excellent.

scope The scope in which the search is to be performed. You can use the class constants.ResponsePolicyItemSearchScope to access all the constants.
start A starting number from where the search result will be returned. The possible value is a positive integer ranging from 0 to 999.
count The total number of results to be returned. The possible value is a positive integer ranging from 1 to 1000.
properties Reserved for future use.

Returns: Returns an array of policy items.

Example:

from bluecat.constants import ResponsePolicyItemSearchScope

api = g.user.get_api()     # get api object
policy_list = api.search_response_policy_items('test.test',
                                               ResponsePolicyItemSearchScope.LOCAL,
                                               start=0, count=100)

New in version 20.1.1.

selective_deploy(entities, properties='')

Creates a deployment task to deploy changes made to specific DNS entities, such as resource records, to a managed DNS/DHCP Server.You must perform a full DNS deployment before proceeding to use the selective deployment API method. You can only deploy a maximum of 100 DNS entities per selective deployment API call. You cannot deploy dynamic records. You cannot deploy external host records. You cannot deploy resource records if they belong to multiple DNS/DHCP Servers.

This method is available only if executed against BAM v8.3.2 or newer. This method is available only if executed against BDDS v8.3.2 or newer.

Note: If you are using Address Manager v9.1.0 or greater, you can use the batchMode and continueOnFailure properties. For more information, refer to the Address Manager API Guide v9.1.0.
Parameters Description
entities list of entities or entity ids of the host records.
properties string including the scope option as a string value. This defines whether the deployment task includes objects that are related to the defined DNS resource records. The scope can be one of the following values:
  • related: This is the default option. deploys the DNS resource records defined in the entities as well as DNS resource records that are related to those entities.

  • specific: deploys only the DNS resource records that are defined in the entities list.

Returns: String token to check the deployment status.

selective_deploy_synchronous(entities, properties='', timeout=12)

Executes the selective deployment but also waits until deployment has completed. Same restrictions as in selective_deploy method are applied.

Parameters Description
entities list of entities or entity ids of the host records.
properties string including the scope option as a string value. This defines whether the deployment task includes objects that are related to the defined DNS resource records. The scope can be one of the following values:
  • related: This is the default option. deploys the DNS resource records defined in the entities as well as DNS resource records that are related to those entities.

  • specific: deploys only the DNS resource records that are defined in the entities list.

timeout the amount of seconds to wait till the deployment is finished. The default value is 12 seconds.

Returns: Returns a JSON with the overall deployment status after the deployment finished and the deployment status of individual entities. The request section displays a list of the entity IDs passed. The status section displays the status of the deployment. The deployment status can be FINISHED or TASK_NOT_FOUND. The responses section contains specific information about the entities including the ID of the entity, the fully qualified domain name (FQDN), record type, TTL value, record data, the operation performed on the resource record, and the result of the deployment. The errors section lists out any errors encountered during the deployment. If all entities deployed successfully, the section displays an empty list.

set_api_token(token)

Connect to existing BAM API session using provided BAM API token.

Parameters Description
token BAM API token.

spec_api

The underlying API specification Client used for communicating with BAM.

New in version 21.5.1.

update_user_defined_field(obj_type:str, udf:bluecat.udf.UserDefinedField)

Update the user-defined field (UDF) for the given BAM object type (such as “Zone”, “User”).

Parameters Description
obj_type(str) The BAM object type to which the UDF belongs
udf(UserDefinedField) The user-defined field to update

Raises: BAMException for any unsuccessful requests to BAM

Returns: None, indicating a successful request to BAM

Example:

from bluecat.constants import EntityType

api = g.user.get_api()     # get api object
udf = UserDefinedField({
    "name": 'name-1',                     # required
    "displayName": 'display name -1',     # required
    "type": 'TEXT',                       # required
    "defaultValue": 'default',
    # comma separated string of key=value
    # valid keys: 'min' 'max' 'minLength' 'maxLength' 'pattern'
    # values cannot contain comma
    "validatorProperties": 'minLength=5,maxLength=10',
    # pipe separated and ended string, values cannot contain pipe
    "predefinedValues": '',
    # pipe separated and ended string of property=value, values cannot contain pipe
    "properties": '',
    "required": False,
    "hideFromSearch": False
})
res = api.update_user_defined_field(EntityType.ZONE, udf)

New in version 21.5.1.