4.4.3. Fields

Warning

This API is deprecated.

Axonius API v2 is now available, we recommend you move to API v2.

New features will no longer be added to this API. Axonius will only provide bug fixes.

Read about API v2

API for working with fields for assets.

axonius_api_client.api.assets.fields.fuzzyfinder(value, collection, accessor=<function <lambda>>)

Fuzzy finder

Parameters:

• value (str) – A partial string which is typically entered by a user.

• collection (typing.Iterable) – A collection of strings which will be filtered based on the value.

• accessor (typing.Callable) – If the collection is not an iterable of strings, then use the accessor to fetch the string that will be used for fuzzy matching.

Returns:

A list of suggestions narrowed down from collection using the value.

Return type:

suggestions

class axonius_api_client.api.assets.fields.Fields(parent)

Bases: ChildMixins

API for working with fields for the parent asset type.

Examples

Create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices  # or client.users

• Get schemas of all adapters and their fields: get()

• Validate field names supplied: validate()

See also

• Device assets axonius_api_client.api.assets.devices.Devices

• User assets axonius_api_client.api.assets.users.Users

Parameters:

parent (axonius_api_client.api.mixins.Model) –

get()

Get the schema of all adapters and their fields. :rtype: dict

Examples

Get all fields for all adapters

>>> fields = apiobj.fields.get()

See the adapter names

>>> print(list(fields))

See the field fully qualified name, short name, and title for all fields of an adapter

>>> schemas = fields['agg']
>>> for schema in schemas:
...     qual = schema['name_qual']
...     name = schema['name_base']
...     title = schema['title']
...     print(f"title {title!r}, qualified name {name!r}, base name {name!r}")

validate(fields=None, fields_regex=None, fields_regex_root_only=True, fields_manual=None, fields_fuzzy=None, fields_default=True, fields_error=True, fields_root=None, empty_ok=False)

Get the fully qualified field names for getting asset data.

Examples

• fields gets parsed by get_field_names_eq()

• fields_regex gets parsed by get_field_names_re()

• fields_fuzzy gets parsed by get_field_names_fuzzy()

• fields_root gets parsed by get_field_names_root()

• fields_default will add axonius_api_client.api.assets.users.Users.fields_default or axonius_api_client.api.assets.devices.Devices.fields_default based on the parent asset type

Notes

This is used in a number of ways to allow the user to supply fields that are easier to refer to than the fully qualified name or title of a field.

Parameters:

• fields (typing.Union[str, typing.List[str], None]) – list of fields that must equal their base name, qual name, or title

• fields_regex (typing.Union[str, typing.List[str], None]) – list of fields to regex match against their base name, qual name, or title

• fields_manual (typing.Union[str, typing.List[str], None]) – list of already fully qualified field names

• fields_fuzzy (typing.Union[str, typing.List[str], None]) – list of fields to fuzzy match against their base name or title

• fields_default (bool) – include the default fields defined in the parent API object

• fields_root (typing.Optional[str]) – include all root fields from a single adapter

• fields_regex_root_only (bool) –

• fields_error (bool) –

• empty_ok (bool) –

Raises:

ApiError – if no fields selected after all processing is done

Return type:

typing.List[str]

get_field_name(value, field_manual=False, fields_custom=None, selectable_only=True, key='name_qual')

Get the fully qualified name of a field.

Examples

First, create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices

Get the FQDN of a field on the aggregated adapter

>>> apiobj.fields.get_field_name(value='hostname')
'specific_data.data.hostname'
>>> apiobj.fields.get_field_name(value='agg:hostname')
'specific_data.data.hostname'

Get the title of a field on the aggregated adapter

>>> apiobj.fields.get_field_name(value='hostname', key="title")
'Host Name'

Get the FQDN of a field on the AWS adapter

>>> apiobj.fields.get_field_name(value='aws:aws_device_type')
'adapters_data.aws_adapter.aws_device_type'

Parameters:

• value (str) – field to find in format of adapter_name:field_name

• field_manual (bool) – treat the field name as fully qualified

• fields_custom (typing.Optional[dict]) – custom schemas to search in addition to API schemas

• key (str) – key of schema to return, or if empty return the schema itself

• selectable_only (bool) –

Raises:

ApiError – if more than one field found in value after splitting it

Return type:

str

get_field_names_re(value, key='name_qual', root_only=True)

Get field names using regex.

Examples

First, create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices

Get all aggregated field FQDNs that start with host

>>> apiobj.fields.get_field_names_re('^host')
['specific_data.data.hostname', 'specific_data.data.hostname_preferred']

Get fields names for AWS adapter that start with id and AGG adapter that start with host

>>> apiobj.fields.get_field_names_re(['aws:^id', '^host'])
[
    'adapters_data.aws_adapter.id',
    'specific_data.data.hostname',
    'specific_data.data.hostname_preferred'
]

Get all aggregated field titles that start with host

>>> apiobj.fields.get_field_names_re('^host', key="title")
['Host Name', 'Preferred Host Name']

Get all aggregated field FQDNs that have a title of ‘Host Name’

>>> apiobj.fields.get_field_names_re('Host Name')
['specific_data.data.hostname', 'specific_data.data.hostname_preferred']

Get all field FQDNs that start with id for all adapters that match regex ‘ac’

>>> apiobj.fields.get_field_names_re('ac:^id')
[
    'adapters_data.active_directory_adapter.id',
    'adapters_data.carbonblack_defense_adapter.id',
    'adapters_data.limacharlie_adapter.id'
]

Parameters:

• value (typing.Union[str, typing.List[str]]) – regex to search for fields

• key (str) – key of schema to return

• root_only (bool) –

Return type:

typing.List[str]

get_field_names_eq(value, key='name_qual', fields_error=True, selectable_only=True)

Get field names that equal a value.

Examples

First, create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices

Get field names that equal aggregated hostname or id and AWS device type

>>> apiobj.fields.get_field_names_eq(['hostname,id', 'aws:aws_device_type'])
[
    'specific_data.data.hostname',
    'specific_data.data.id',
    'adapters_data.aws_adapter.aws_device_type'
]

Get field names that equal aggregated hostname or id

>>> apiobj.fields.get_field_names_eq('hostname,id')
['specific_data.data.hostname', 'specific_data.data.id']

Parameters:

• value (typing.Union[str, typing.List[str]]) – value to search for fields

• key (str) – key of schema to return

• fields_error (bool) –

• selectable_only (bool) –

Return type:

typing.List[str]

get_field_names_fuzzy(value, key='name_qual')

Get field names using that equal a value.

Examples

First, create a client using axonius_api_client.connect.Connect and assume apiobj is either client.devices or client.users

>>> apiobj = client.devices

Get field names that fuzzy match a misspelt version of hostname

>>> apiobj.fields.get_field_names_fuzzy('hostnme')
['specific_data.data.hostname']

Parameters:

• value (str) – value to search for fields

• key (str) – key of schema to return

Return type:

typing.List[str]

get_field_schemas_root(adapter)

Get schemas of all root fields for a given adapter.

Parameters:

adapter (str) – name of adapter to get all root fields for

Return type:

typing.List[dict]

See also

get_field_names_root()

Notes

root fields are fields that are fields that are not sub-fields of complex fields

For instance ‘specific_data.data.network_interfaces.ips’ is NOT a root field, since ‘ips’ is a sub-field of ‘specific_data.data.network_interfaces’

get_field_names_root(adapter, key='name_qual')

Get names of all root fields for a given adapter.

Parameters:

adapter (str) – name of adapter to get all root fields for

Return type:

typing.List[str]

See also

get_field_schemas_root()

Parameters:

key (str) –

static fuzzy_filter(search, schemas, root_only=False, key='name_qual', fuzzy_keys=['name_base', 'title'], **kwargs)

Perform a fuzzy search against a set of field schemas.

Parameters:

• search (str) – string to search for against the keys in fuzzy_keys

• schemas (typing.List[dict]) – field schemas to search through

• root_only (bool) – only search against schemas of root fields

• key (str) – return the schema key value instead of the field schemas

• fuzzy_keys (typing.List[str]) – list of keys to check search against in each field schema

Return type:

typing.List[dict]

get_adapter_names(value)

Find adapter names that regex match a value.

Parameters:

value (str) – regex of adapter to match

Raises:

NotFoundError – when no adapter name matches supplied value

Return type:

typing.List[str]

get_adapter_name(value)

Find an adapter name that equals a value.

Parameters:

value (str) – name of adapter

Raises:

NotFoundError – when no adapter name equals supplied value

Return type:

str

get_field_schemas(value, schemas, keys=['name', 'name_base', 'name_qual', 'title'])

Find field schemes that regex match a value.

Parameters:

• value (str) – regex of name to match

• schemas (typing.List[dict]) – list of field schemas to search through

• keys (typing.List[str]) – list of keys to check regex value against

Return type:

typing.List[dict]

get_field_schema(value, schemas, keys=['name', 'name_base', 'name_qual', 'title'], fields_error=True, selectable_only=True, **kwargs)

Find a field name that equals a value.

Parameters:

• value (str) – name of field

• schemas (typing.List[dict]) – list of field schemas to search through

• keys (typing.List[str]) – list of keys to check if value equals

• **kwargs – passed to fuzzy_filter() to print fuzzy matches in error if no matches found

• fields_error (bool) –

• selectable_only (bool) –

Raises:

NotFoundError – when no field name equals supplied value

Return type:

dict

split_searches(value)

Split a list of strings into adapter:field(s) format.

Parameters:

value (typing.Union[typing.List[str], str]) – format of 'adapter:field1,field2' or ['adapter1:field1', 'adapter2:field2']

Return type:

typing.List[typing.Tuple[str, typing.List[str]]]

split_search(value, adapter='agg')

Split a string into adapter and field(s).

Parameters:

• value (str) – format of 'adapter:field1,field2' or 'field1,field2' or 'field1'

• adapter (str) – default adapter name to use if no ‘adapter:’ found in value

Raises:

ApiError – if no fields found after splitting on ‘:’

Return type:

typing.Tuple[str, typing.List[str]]

_prettify_schemas(schemas, tmpl='{adapter_name}:{name_base:{len_max}} -> {column_title}', len_key='name_base')

Prettify a set of schemas for output in human friendly format.

Parameters:

• schemas (typing.List[dict]) – field schemas to prettify

• tmpl (str) – template to use to prettify schemas

• len_key (str) – schema key to get max length of and pass into tmpl as “len_max”

Return type:

typing.List[str]

_get()

Private API method to get the schema of all fields.

Return type:

axonius_api_client.api.json_api.generic.Metadata

LOG: logging.Logger = None

Logger for this object.

__init__(parent)

Mixins model for API child objects.

Parameters:

parent (axonius_api_client.api.mixins.Model) – parent API model of this child

__repr__()

Show info for this model object.

Return type:

str

__str__()

Show info for this model object.

Return type:

str

_init(parent)

Post init method for subclasses to use for extra setup.

Parameters:

parent (axonius_api_client.api.mixins.Model) – parent API model of this child

auth: axonius_api_client.auth.model.AuthModel = None

Authentication model with bound Http object to use for requests.

http: axonius_api_client.http.Http = None

Http object to use for requests.

parent: axonius_api_client.api.mixins.Model = None

Parent API model of this child.