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.
class api.API(url, sslverify=False, ca_file=None, ca_path=None, logger=None)
Bases: object
Create a connection to the BAM API.
Parameter | 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. |
add_default_access_right(recipient_id, value, overrides='', properties='')
Parameter | 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:
|
Returns: Object ID of a created Access Right.
add_group(name, properties='')
Add a user group.
Parameter | Description |
---|---|
name | The name of the user group. |
properties | Adds object properties, including user-defined fields. |
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.
Parameter | 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). |
The email address for the user. | |
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: 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.
Parameter | 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 want to search. |
delete_configuration(name='', entity_id=0)
Delete a configuration using name or id. Does not need both.
Parameter | 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.
Parameter | Description |
---|---|
name | The name of the BAM user group. |
entity_id | The object ID of the configuration 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.
Parameter | Description |
---|---|
name | The name of the BAM user. |
entity_id | The object ID of the configuration in the BAM database. |
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.
Parameter | Description |
---|---|
hint | The following wildcards are supported in the hint option:
|
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.
classmethod get_api_client(url, use_rest, **kwargs)
Generate an API Client based on the communication method set for BlueCat Gateway.
Parameter | Description |
---|---|
url | URL to the WADL or WSDL file. |
use_rest | Whether to use REST or SOAP. |
kwargs | Any keyword arguments for either client. |
get_audit_logs(interval='5 hours', transaction_id=None, descending=False)
- 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.
Parameter | Description |
---|---|
interval | The time period of the audit logs. |
transaction_id | 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 | Orders logs based on the time of creation. The default value is false which orders logs in ascending order. |
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.
- PortalException - If BAM version is lower than 9.0.0.
get_audit_trail(entity_id, descending=True, start: int=0, count: int=10, version=1)
- 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.
Parameter | Description |
---|---|
entity_id (integer, required) | The ID of the entity for which to retrieve transaction logs. |
descending (boolean, required) | Orders results by the time of creation. Defaults to False. |
start (integer, optional) | The index of the row from where to start. |
count (integer, optional) | The maximum number of elements to be returned. |
version (integer, optional) | The version of the functionality. Allowed values: 1. Defaults to 1. |
Returns: Returns a generator that yields a dictionary representing a single log entry.
Raises:
- PortalException - If BAM version is lower than v9.0.0.
- PortalException - If BAM is not between 1 and 50.
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.
- 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.
Parameter | Description |
---|---|
indicators (list, required) | Retrieves a list of object types for the database count. The supported types are listed in bluecat.constants.BAMStats. |
types (integer, required) | The 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 v9.0.0.
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.
Parameter | Description |
---|---|
pattern | Search pattern string (will match any of the various properties of a BAM entity). |
types | List of BAM entity types (For example, [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.
Parameter | Description |
---|---|
name | Name of the BAM 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)
Parameter | Description |
---|---|
recepient_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)
Parameter | 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_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.
Parameter | 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 :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.
Parameter | Description |
---|---|
hint | The partial or full keyword value 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 | 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) -> Iterable[Dict[str, object]]:
Get the IPv4 lease information.
Parameter | Description |
---|---|
order_by (string, optional) |
Determines which key value should be used to order the list. All valid parameters are in IP4LeaseFields. |
descending (boolean, optional) | Returns the list in descending order. |
start (integer, optional) | The index of the row from where to start. |
count (integer, optional) | The maximum number of elements to be returned. |
version (integer, optional) | The version of the functionality. Allowed values: 1. Defaults to 1. |
Returns: A list that yields a dictionary representing a single IPv4 lease. The dictionary yields the following key and values:
-
ip_address_id (integer) - The ID number of the IP address.
-
ip_address (string) - The integer value of the IP address.
-
conf_id (integer) - The ID of the configuration to which the IP address belongs.
-
mac_address (string) - The MAC address of the client to which the IP address was assigned.
-
last_dhcp_status (integer, 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 (string, None) - The ID of the circuit from which the request came.
-
remote_id (string, None) - The ID of the relay agent.
-
clienthost_name (string, None) - The hostname of the client to which the IP address was assigned.
-
update_count (integer) - The number of updates to the lease.
-
last_update_time (datetime) - The timestamp of when the lease was last updated.
-
id (integer): The unique ID number of the object.
-
dhcp_client_identifier (string, 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 (string, None) - The list of parameters that the device requested from the DHCP server.
-
vendor_class_identifier (string, None) -The identifier sent by the DHCP client software running on the device.
from constants import IP4LeaseFields lease_limit = 20 # the limit for the returned elements order_by = IP4LeaseFields.IP_ADDRESS_ID # the order the query should be set to # Use a user-aware bluecat.api.API instance. api = g.user.get_api() items = api.get_ip4_leases(order_by=order_by, descending=True, limit=limit)
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.
Parameter | Description |
---|---|
order_by (string, optional) |
Determines which key value should be used to order the list All valid parameters are in IP6LeaseFields. |
descending (boolean, optional) | Returns the list in descending order. |
start (integer, optional) | The index of the row from where to start. |
count (integer, optional) | The maximum number of elements to be returned. |
version (integer, optional) | The version of the functionality. Allowed values: 1. Defaults to 1. |
Returns: A list that yields a dictionary representing a single IPv6 lease. The dictionary yields the following key and values:
-
ip_address_id (integer) - The ID number of the IP address.
-
ip_address_high (string, None) - The integer value of the high-order 64-bits of the IP address.
- ip6_address_low (string, None): The integer value of the low-order 64-bits of the IP address.
-
conf_id (integer) - The ID of the configuration to which the IP address belongs.
- duid_id (integer) - The DUID of the client to which the IP address was assigned.
-
last_dhcp_status (integer, 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 (string, None) - The ID of the circuit from which the request came.
-
remote_id (string, None) - The ID of the relay agent.
-
clienthost_name (string, None) - The hostname of the client to which the IP address was assigned.
-
update_count (integer) - The number of updates to the lease.
-
last_update_time (datetime) - The timestamp of when the lease was last updated.
-
id (integer): The unique ID number of the object.
from constants import IP6LeaseFields lease_limit = 20 # the limit for the returned elements order_by = IP6LeaseFields.IP_ADDRESS_ID # the order the query should be set to # Use a user-aware bluecat.api.API instance. api = g.user.get_api() items = api.get_ip6_leases(order_by=order_by, descending=True, limit=limit)
get_location_by_code(code)
Use this method to get the location object with the specified hierarchical location code.
Parameter | Description |
---|---|
code | The hierarchical location code, it consists 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:
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)
Gets the parent chain (configuration, view, and zone) for each list of entities.Parameter | Description |
---|---|
entity_list (string, required) | A list of entities whose parent chains are to be obtained. |
Returns: A list of dictionaries with each holding the requested details per entity from the input.
api = g.user.get_api() # get api object host_record_id = 10234 host_record_id2 = 23232 record = api.get_entity_by_id(host_record_id) # get entity objects record2 = api.get_entity_by_id(host_record_id2) bulk_value = api.get_parent_chain([record, record2])
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.
Parameter | 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_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.
- 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.
Parameter | 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 (boolean, optional) | Determines whether the sessions of the system user should be included in the result. Defaults to False. |
descending (boolean, optional) | Determines whether the returned elements to be in reverse chronological order (of the login time). Defaults to False. |
start (integer, optional) | The index of the row from where to start. |
count (integer, optional) | The maximum number of elements to be returned. |
version (integer, optional) | Version of the functionality that is to be used. Allowed values: 1. Defaults to 1. |
- id (integer) -ID of the user session
- user_id (integer) - ID of the user
- username (string) - 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 (integer) - ID of the state of the session. The valid values are defined in UserSessionState.
- machine_ip (string), may be None - IP address of the device used to log into the system
- authenticator_id (integer), may be None - ID of the authenticator
- authenticator_name (string), may be None - name of the authenticator
- response (string), may be None - response from the authenticator
Raises:
- PortalException - 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.
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 sessions = api.get_user_sessions(begin_time, end_time, include_system_user=False)
get_url()
Get the URL of the application.
get_user(username)
Get a named user.
Parameter | Description |
---|---|
username | Username of the BAM 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.
Parameter | 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)
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.
Parameter | Description |
---|---|
username | BAM username. |
password | BAM password. |
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.
Parameter | Description |
---|---|
keyword (string, required) | The search string. You can use the following characters in the
search string:
|
scope (string, required) | The scope in which the search is to be performed. Use the constant class constants.ResponsePolicyItemSearchScope for all the possible scope types. |
start (integer, required) |
A starting number where the search result will be returned. You can enter a value of a positive integer ranging from 0 to 999. |
count (integer, required) |
The total number of results to be returned. You can enter a value of a positive integer ranging from 0 to 999. |
properties | Reserved for future use. |
Returns: Returns an array of policy items.
from 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)
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.
Parameter | 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:
|
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.
Parameter | 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:
|
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.