Documentation

Mistake on this page? Email us
Docs › Managing devices › Deployed devices › Device filters and attributes › Using attributes and filters through the APIs

Using attributes and filters through the APIs

This page explains how to create device attributes and filters using the Device Management APIs. See the page on the concepts of attributes and filters before following this tutorial.

There are two main ways to use filters through the APIs:

  • By appending the filter (starting with ?) to the URL of a request:
    • Everything after ? is part of the filter.
    • The filter must be URL-encoded.
    • This method does not save the filter for later use.
  • By making a request to POST /v3/device-queries.
    • You define the filter in the message body of the request, not as part of the URL.
    • This method saves the filter for later use.

Creating custom attribute and value pairs

When you create an attribute, you create the attribute and assign its value at the same time. You can assign custom attributes to one device at a time.

Create attributes using PUT /v3/devices/{device_id}, defining the attribute(s) in the message body. When you give the value of a custom attribute:

  • Surround the value in quotation marks.
  • Escape inner quotation marks with a backward slash. See the example for Location below.

Note: You can add custom attributes to one device at a time.

One important thing to understand about attributes and values is that Device Management makes no assumptions about them, and doesn't validate them. If you misspell an attribute or value, you'll create a new one. If you create a new device and try to give its Location attribute the value Camridge (missing b), Device Management will not indicate this error. Similarly, you might create a second attribute by spelling it Locaion (missing t), so you won't find Cambridge by filtering on Location.

To create the attribute Location and the value Cambridge, use the following request:

curl -X PUT https://api.us-east-1.mbedcloud.com/v3/device/0158f770ba880000000000010010000a
    -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{"custom_attributes": "{\"Location\":\"Cambridge\"}"}'

Note: Attribute-value pairs are case-sensitive. The attribute location is distinct from Location.

The device's entry in Device Directory now has "custom_attributes": {"Location": "Cambridge"},.

Filter structure

A filter consists of an attribute, an operator, an equal sign (=), and a value. Separate the operator from the attribute with two underscores (__):

lifecycle_status__eq=enabled // Finds all devices with lifecycle status 'enabled'.

or

id__neq=016e58d1b1760000000000010014dd97 // Finds devices with a device ID not equal to 016e58d1b1760000000000010014dd97.

If the value of the field contains more than one word, (for example, a two-word name), insert an ampersand between them:

name__eq=Special&Devices

See the full list of attributes and operators.

You can experiment with creating filters and test them using Advanced view in Device Management Portal. The raw query string you create in Portal's advanced filter view will work in your HTTP requests.

Constructing multi-attribute filters

To create a multi-attribute filter, insert an ampersand (&) between attributes. You can also use multiple operators:

state__eq=registered&lifecycle_status=enabled

or, to find devices where state is registered and lifecycle status is not enabled:

state__eq=registered&lifecycle_status__neq=enabled

One-time device filters

This method of filtering returns a list of devices, but does not save the filter for later use. Construct the filter, and put it at the end of the URL in your request.

Call `GET /v3/devices?{filter}:

  curl -X POST https://api.us-east-1.mbedcloud.com/v3/devices?lifecycle_status__eq=enabled \
  -H "Authorization: Bearer <api_key>"

This will list devices with lifecycle status enabled. However, you can't use this type of filter to target devices in an update campaign.

Saving filters

Creating a filter using POST /v3/device-queries saves the filter for later use. You can refer to the filter using the id this interface returns. You can also append the filter to the URL of a request.

You can save filters to reuse and edit later through both the APIs and Device Management Portal; this section explains how to save and list filters through the APIs.

The following command creates a filter with:

  • The name Test Filter.
  • The value "mechanism=connector".
curl -X POST https://api.us-east-1.mbedcloud.com/v3/device-queries/ \
     -H "Authorization: Bearer <api_key>" \
     -H "Content-Type: application/json" \
     -d '{"name": "Test Filter","query": "mechanism__eq=connector","description": "Filtering by mechanism"}'

This produces a filter entry. The most relevant fields in it are:

{
   "name":"Test Filter",
   "id":"0158f770ba880000000000010010000a",
   "object":"device-query",
   "description":"Filtering by mechanism",
   "query":"mechanism__eq=connector"
}

The id field is the ID of the saved filter. You can use this ID to retrieve the filter later:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/device-queries/0158f770ba880000000000010010000a/
-H "Authorization: Bearer <api_key>"

This is also the ID you use to specify which devices you're applying an update to when you create a campaign.

Listing created filters

To list all the filters in your account, call:

curl -X GET https://api.us-east-1.mbedcloud.com/v3/device-queries/
-H "Authorization: Bearer <api_key>"

This produces a list of all your filters:

{
   "object":"list",
   "limit":50,
   "has_more":false,
   "after":null,
   "data":[
      {
         "object":"device-query",
         "updated_at":"2016-12-09T17:18:39.181780Z",
         "description":"",
         "id":"0158e4980a3200000000000100100001",
         "name":"Special Devices",
         "query":"name__eq=Special&Devices",
         "etag":"2016-12-09T17:18:39.181795Z",
         "created_at":"2016-12-09T17:18:39.181735Z",
         "query_id":"0158e4980a3200000000000100100001"
      },
      {
         "object":"device-query",
         "updated_at":"2016-12-12T11:51:12.856009Z",
         "description":"",
         "id":"0158f2df56d000000000000100100004",
         "name":"device-query: 0158f2de9992000000000001001001f8",
         "query":"id__eq=0158f2de9992000000000001001001f8",
         "etag":"2016-12-12T11:51:12.856024Z",
         "created_at":"2016-12-12T11:51:12.855975Z",
         "query_id":"0158f2df56d000000000000100100004"
      },
      {
         "object":"device-query",
         "updated_at":"2016-12-13T09:08:29.969605Z",
         "description":"",
         "id":"0158f770ba880000000000010010000a",
         "name":"Test Filter",
         "query":"mechanism__eq=connector",
         "etag":"2016-12-13T09:08:29.969626Z",
         "created_at":"2016-12-13T09:08:29.969532Z",
         "query_id":"0158f770ba880000000000010010000a"
      }
   ],
   "order":"ASC"
}
Previous Next