4.4.3. Fields

API for working with fields for assets.

class axonius_api_client.api.assets.fields.Fields(parent)[source]

Bases: axonius_api_client.api.mixins.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()

Parameters

parent (axonius_api_client.api.mixins.Model) –

get()[source]

Get the schema of all adapters and their fields.

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}")
Return type

dict

validate(fields=None, fields_regex=None, fields_manual=None, fields_fuzzy=None, fields_default=True, fields_root=None)[source]

Get the fully qualified field names for getting asset data.

Examples

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
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, key='name_qual')[source]

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

Raises

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

Return type

str

get_field_names_re(value, key='name_qual')[source]

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
Return type

typing.List[str]

get_field_names_eq(value, key='name_qual')[source]

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
Return type

typing.List[str]

get_field_names_fuzzy(value, key='name_qual')[source]

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)[source]

Get schemas of all root fields for a given adapter.

Parameters

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

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 it ‘ips’ is a sub field of ‘specific_data.data.network_interfaces’

Return type

typing.List[dict]

get_field_names_root(adapter, key='name_qual')[source]

Get names of all root fields for a given adapter.

Parameters

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

Parameters

key (str) –

Return type

typing.List[str]

static fuzzy_filter(search, schemas, root_only=False, do_contains=True, token_score=70, partial_score=50, key='name_qual', fuzzy_keys=['name_base', 'title'], **kwargs)[source]

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

  • do_contains (bool) – allow matches based on the search string is in fuzzy_keys

  • token_score (int) – fuzzy scoring needed for a token match

  • partial_score (int) – fuzzy scoring needed for a partial match

  • names – return the fully qualified field names instead of the field schemas

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

  • key (str) –

Return type

typing.List[dict]

get_adapter_names(value)[source]

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)[source]

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'])[source]

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'], **kwargs)[source]

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

Raises

NotFoundError – when no field name equals supplied value

Return type

dict

split_searches(value)[source]

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 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')[source]

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()[source]

Private API method to get the schema of all fields.

Return type

dict

__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