4.4.3. Fields

API for working with fields for assets.

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[typing.List[str], str, None]) – list of fields that must equal their base name, qual name, or title

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

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

• fields_fuzzy (typing.Union[typing.List[str], 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[dict]

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 thru 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

__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