Retrieving Objects From Nautobot¶
Endpoint class provides three methods
Record objects from Nautobot.
get()method is used to get a single Record.
filter()method will return a list of Records.
all()method will return all Records for the Model.
Using the Get Method¶
The Retrieving Records sections shows how to use the
get() method by passing in keyword arguments.
Another way to retrieve a Record is by passing in the value of the PK,
which is the ID for most objects.
>>> dev = nautobot.dcim.devices.get('2302f2a1-2ed4-4ac9-a43a-285c95190071') >>> dev.name 'hq-access-01' >>> dev.status Active >>> dev.device_type c9300-48 >>> dev.device_role Access
If an entry with the specified value for the PK does not exist,
None in the above example.
When using the
with keyword arguments, the keyword arguments must match only a single Record.
If multiple Records are matched, then a
ValueError is raised.
>>> dev = nautobot.dcim.devices.get(model="CSR1000V") Traceback (most recent call last): ... ValueError: get() returned more than one result. Check that the kwarg(s) passed are valid for this endpoint or use filter() or all() instead.
Using the Filter Method¶
The error message from the previous example suggests to use the
Using this method will return a list of
instances; one for each matching record.
This method also supports:
filtering a single field with multiple values
filtering based on custom fields
filtering with lookup expressions
The simplest usage of the
method is to pass keyword arguments with single values.
The previous example raised an exception using the
but will return all matches using
>>> # Get all CSR1000V devices >>> devices = nautobot.dcim.devices.filter(model="CSR1000V") >>> # Show a list of Records are returned >>> devices [jcy-bb-01.infra.ntc.com, jcy-rtr-01.infra.ntc.com, jcy-rtr-02.infra.ntc.com] >>> # Show accessing data from the first CSR1000V device >>> dev1 = devices >>> dev1.name 'jcy-bb-01.infra.ntc.com' >>> dev1.status Active
Filtering with OR logic¶
filter() method allows
using an OR condition by passing in a list of values to match against the field.
The example below gets all devices located in either Site
>>> # There are 100 devices total >>> nautobot.dcim.devices.count() 100 >>> # There are 20 dc devices >>> dev_dc_site = nautobot.dcim.devices.filter(site="dc") >>> len(dev_dc_site) 20 >>> # There are 5 hq devices >>> dev_hq_site = nautobot.dcim.devices.filter(site="hq") >>> len(dev_hq_site) 5 # The filter method will grab all devices in both sites >>> dev_hq_dc_sites = nautobot.dcim.devices.filter(site=["hq", "dc"]) >>> len(dev_all_sites) 25
Filtering based on a Custom Field¶
Nautobot provides Custom Fields
as a way of extending a Model’s fields.
These fields can be referenced in the API by appending cf_ to the field’s name.
The below example has a custom field named owner, which is used to filter the devices
by passing the
cf_owner keyword argument.
>>> devices = nautobot.dcim.devices.filter(cf_owner="John Smith") >>> devices [switch0, switch1] >>> # Show device has an owner of "John Smith" >>> devices.custom_fields["owner"] 'John Smith'
Filtering with Lookup Expressions¶
The Nautobot API uses Lookup Expressions to filter using something other than the exact matches that have been used so far. There are several expressions that can be used; they generally cover things like:
The example below shows how use negation with __n.
From the previous examples, there are 100 devices total, and 25 are located in either the dc or hq site.
site__n to get the negation of these sites returns 75 devices.
>>> devices = nautobot.dcim.devices.filter(site__n=["hq", "dc"]) >>> len(devices) 75 >>> # Show the device is not in either hq or dc site >>> devices.site branch1
Using the All Method¶
all() is used to get all records of a specific endpoint.
This will return a list of all
Record objects for the specific Endpoint.
>>> devices = nautobot.dcim.devices.all() >>> len(devices) 100 >>> dev1 = devices >>> dev1.name 'hq-access-01' >>> dev1.status Active
all can use threading by passing
use_threading=True when instantiating the
The following two pages cover interacting with the returned
The next page covers additional Update operations, which is followed by a discussion of other features and methods.