api module - Platform - BlueCat Gateway - 21.11.2

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.

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

Returns: Object ID of a created Access Right.

add_group(name, properties='')

Add a user group

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

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.

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.

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

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.

delete_group(name='', entity_id=0)

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

delete_user(name='', entity_id=0)

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

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.

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.

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.

Returns: The initialized client.

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

Gets Audit logs.

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

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

Type: bool, optional

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

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.

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)

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

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.

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.

Returns: Access Right object.

get_deployment_task_status(deployment_token)

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.

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.

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.

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

get_group(group_name)

Get Group

Returns: User Group.

get_host_records_by_hint(hint, retrieve_fields=True)

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

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.

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.

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.

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.

Return type: Iterator[Dict]

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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

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.