API class - Platform - BlueCat Gateway - 20.1.1

The API class is the main entry point into the BAM API. Most use cases involve instantiating an API instance, connecting to BAM, and going from there.

An example is as follows:

#!/usr/bin/python
from bluecat import api, api_exception

try:

    # Create a connection - the URL is the same one as used for raw BAM REST API connections.
    conn = API('http://192.168.56.191/Services/REST/application.wadl')

    # Log in using an API user configured via the BAM UI.
    conn.login('admin', 'admin')

    c = conn.get_configuration('Configuration Name')
    for s in c.get_servers():

        # Print the server name and any service IP4 addresses it has.
        print (s.name(), s.get_service_ip4_addresses())

except APIException as e:
    # Something went wrong.
    print (e.get_message())

some code

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.

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: The object ID of a created access right.

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: The object ID for the new Address Manager user.

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.

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.

get_aliases_by_hint(hint, retrieve_fields=True)

Get a list of alias records that matches hint.

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.

classmethod get_api_client(url, use_rest, **kwargs)

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

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

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

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

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

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

Raises:

api = g.user.get_api()           # get api object
entity_id = 10081                # Retrieve audit trail logs for entity_id
audit_trail = api.get_audit_trail(entity_id)

for trail in audit_trail:
print(trail)

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:

from bluecat.constants import BAMStats

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

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

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)

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_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 :param group_name: Group name :return: 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) -> Iterable[Dict[str, object]]:

Get the IPv4 lease information.

Returns: A list that yields a dictionary representing a single IPv4 lease. The dictionary yields the following key and values:

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

Get the IPv6 lease information.

Returns: A list that yields a dictionary representing a single IPv6 lease. The dictionary yields the following key and values:

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)

Returns: A list of dictionaries with each holding the requested details per entity from the input.

classmethod get_portal_version(folder_path=None)

Get the version of the BlueCat Gateway 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_user_sessions(begin_time:typing.Union[datetime.datetime, NoneType]=None,, end_time: typing.Union[datetime.datetime, NoneType]=None, include_system_user: bool=False, descending: bool=False, start: int=0, count: int=10, version: int=1) → typing.Iterable[typing.Dict[str, object]]

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

Raises:

get_url()

Get the URL of the application.

get_user(username)

Get a named user.

Returns: user object for the username.

get_version()

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

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)

Log in 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()

Log out from the BAM API.

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

Get an array of policy items for searched keywords.

Returns: Returns an array of policy items.

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 and external host records. You cannot deploy resource records if they belong to multiple DNS/DHCP Servers.

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