Share via

Query devices

  • Article

 

Query the information associated to the devices running an application.

The queried device information is the same as the Get device command, but currently limited to the appInfo and meta properties.

Request

Method

Request URI

HTTP version

GET

https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.MobileEngagement/appcollections/{app-collection}/apps/{app-resource-name}/devices?api-version=2014-12-01

HTTP/1.1

Authentication

See Authentication.

Request URI Path Parameters

None.

Query String Parameters

Parameter

Description

api-version

API version, the only supported value is 2014-12-01.

$top (optional)

Number of devices to return with each call. Defaults to 100 and cannot return more. Passing a greater value is ignored.

The response contains a nextLink property describing the URI path to get the next page of results if not all results could be returned at once.

$select (optional)

By default all meta and appInfo properties are returned, this property is used to restrict the output to the desired properties.

It also excludes all devices from the output that have none of the selected properties.

In other terms, only devices having at least one of the selected property being set is part of the results.

Examples:

  • $select=appInfo : select all devices having at least 1 appInfo, return them all and don’t return any meta property.

  • $select=meta : return only meta properties in the output.

  • $select=appInfo,meta/firstSeen,meta/lastSeen : return all appInfo, plus meta object containing only firstSeen and lastSeen properties.

The format is thus a comma separated list of properties to select.

Use appInfo to select all appInfo properties, meta to select all meta properties.

Use appInfo/{key} and meta/{key} to select specific appInfo and meta properties.

$filter (optional)

Filter can be used to reduce the number of results.

Filter is a boolean expression that can look like the following examples:

  • $filter=deviceId gt 'abcdef0123456789abcdef0123456789'

  • $filter=lastModified le 1447284263690L

  • $filter=(deviceId ge 'abcdef0123456789abcdef0123456789') and (deviceId lt 'bacdef0123456789abcdef0123456789') and (lastModified gt 1447284263690L)

The first example is used automatically for paging when returning the nextLink property.

The filter expression is a combination of checks on some properties that can be compared to their value.

The available operators are:

  • gt : greater than

  • ge : greater than or equals

  • lt : less than

  • le : less than or equals

  • and : to add multiple checks (all checks must pass), optional parentheses can be used.

The properties that can be used in the expression are the following:

  • deviceId {operator} '{deviceIdValue}' : a lexicographical comparison is made on the deviceId value, use single quotes for the value.

  • lastModified {operator} {number}L : returns only meta properties or appInfo properties whose last value modification timestamp compared to the specified value is matching (value is milliseconds since January 1st, 1970 UTC).

Please note the L character after the number of milliseconds, its required when the number of milliseconds exceeds 2^31 - 1 (which is always the case for recent timestamps).

Using lastModified excludes all devices from the output that have no property matching the timestamp criteria, like $select.

Please note that the internal value of lastModified timestamp for a given property is never part of the results.

Request Headers

The following table describes required and optional request headers.

Request Header

Description

Authorization

See Authentication.

Accept (optional)

Its recommended to pass */* or application/json to have JSON error responses.

Request Body

None.

Response

Response Status Codes

Code

Description

200

Devices are returned as JSON.

400

Invalid parameters or application is disabled. Check response body for details.

401

Authentication error.

For information about status codes, see Status and Error Codes.

Response Headers

Content-Type

application/json

Response Body

A JSON object containing the following properties if the request was successful.

Property

Description

value

JSON array containing one JSON object per device. Each device JSON object have the following properties:

Property

Description

deviceId

Device identifier.

meta

Application usage data in the form of a JSON object with the following properties.

Property

Description

firstSeen

First time the device used the application in milliseconds since January 1st, 1970 UTC.

lastSeen

Last time the device used the application in milliseconds since January 1st, 1970 UTC.

lastInfo

Timestamp corresponding to the info object in milliseconds since January 1st, 1970 UTC.

lastLocation

Timestamp corresponding to the location object in milliseconds since January 1st, 1970 UTC.

nativePushEnabled

Boolean indicating if native push notifications (like Android’s GCM or Apple’s APNS) are enabled for the application. This boolean is set to true when the application registers successfully to the native push service, and set to false when the native push service reports to Mobile Engagement that the application can no longer be pushed (which means that it has been uninstalled). This report is performed a few hours after Mobile Engagement has tried to perform a native push to a device on which the application has been uninstalled.

appInfo

Also known as tags, a key-value set as a JSON object with the following properties. Some tags are standard tags defined by Azure Mobile Engagement and others are defined by the application.

Property

Description

userid

Standard tag. Customer specific user identifier (e.g. alice@contoso.com), this value can be used to reference the device when using this API or the Tag devices API.

optin

Standard tag. User global opt-in to Mobile Engagement Reach service (true or false).

apsEnabledNotifications

Standard tag. For iOS applications only. An integer bit mask indicating the types of notifications enabled in the application (i.e. badges, sounds, alerts and Newsstand assets). This value is the same as the return value from UIApplication#enabledRemoteNotificationTypes (15: all types of notifications are enabled, 0: none are enabled).

badge

Standard tag. For iOS applications only. An integer indicating the current badge value of the application. This value is used and updated by Native push campaigns in the Reach API.

<custom boolean tag name>

Custom tag. Custom boolean tag (one of true or false).

<custom integer tag name>

Custom tag. Custom integer tag (e.g. -1200546666).

<custom date tag name>

Custom tag. Custom date tag (CCYY-MM-DD format: e.g. 1969-12-07 stands for 7 Dec 1969).

<custom string tag name>

Custom tag. Custom string tag (e.g. My string).

nextLink

  

If partial results are returned, this property describes a URI path to get the next result page.

The following is an example.

{
    "value": [
        {
            "meta": {
                "lastSeen": 1447284263852,
                "firstSeen": 1447284263852,
                "lastLocation": 1447284263811,
                "lastInfo": 1447284263690,
                "nativePushEnabled": true
            },
            "appInfo": {
                "scoreLevel1": "3",
                "scoreLevel2": "5"
            },
            "deviceId": "446cb485edc9424ba509bc6e97002d56"
        },
        {
            "meta": {
                "lastSeen": 1447729996536,
                "firstSeen": 1446679215422,
                "lastLocation": 1447729996772,
                "lastInfo": 1446776042448,
                "nativePushEnabled": true
            },
            "appInfo": {
                "scoreLevel1": "1",
            },
            "deviceId": "46135ee6e705f3916b16678994c0e767"
        }
    ],
    "nextLink": "/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$filter=deviceId%20gt%20'46135ee6e705f3916b16678994c0e767'"
}

Examples

$top

Example using $top query string parameter. Get the first two devices, with all properties:

Meaning you can get the next 2 devices using the URI described by nextLink in the result. Notice $filter=deviceId gt '46135ee6e705f3916b16678994c0e767' gets added to the parameters (spaces are URL encoded).

Thus next page can be retrieved using the following URI:

/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$filter=deviceId gt '46135ee6e705f3916b16678994c0e767'

GET /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2 HTTP/1.1
Host: management.azure.com
Accept: */*
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iL

HTTP/1.1 200 OK
Content-Type: application/json

{
    "value": [
        {
            "meta": {
                "lastSeen": 1447284263852,
                "firstSeen": 1447284263852,
                "lastLocation": 1447284263811,
                "lastInfo": 1447284263690,
                "nativePushEnabled": true
            },
            "appInfo": {
                "scoreLevel1": "3",
                "scoreLevel2": "5"
            },
            "deviceId": "446cb485edc9424ba509bc6e97002d56"
        },
        {
            "meta": {
                "lastSeen": 1447729996536,
                "firstSeen": 1446679215422,
                "lastLocation": 1447729996772,
                "lastInfo": 1446776042448,
                "nativePushEnabled": true
            },
            "appInfo": {
                "scoreLevel1": "1",
            },
            "deviceId": "46135ee6e705f3916b16678994c0e767"
        }
    ],
    "nextLink": "/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$filter=deviceId%20gt%20'46135ee6e705f3916b16678994c0e767'"
}

$select

Selecting only score for level 2 excludes all devices not having reported a score for that level.

GET /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$select=appInfo/scoreLevel2 HTTP/1.1
Host: management.azure.com
Accept: */*
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iL

HTTP/1.1 200 OK
Content-Type: application/json

{
    "value": [
        {
            "appInfo": {
                "scoreLevel1": "3",
                "scoreLevel2": "5"
            },
            "deviceId": "446cb485edc9424ba509bc6e97002d56"
        },
    ],
    "nextLink": "/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$select=appInfo/scoreLevel2&$filter=deviceId%20gt%20'446cb485edc9424ba509bc6e97002d56'"
}

But if we select also meta properties, the excluded device is back on the results as any device has at least 1 meta property (if not all).

GET /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$select=meta,appInfo/scoreLevel2 HTTP/1.1
Host: management.azure.com
Accept: */*
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iL

HTTP/1.1 200 OK
Content-Type: application/json

{
    "value": [
        {
            "meta": {
                "lastSeen": 1447284263852,
                "firstSeen": 1447284263852,
                "lastLocation": 1447284263811,
                "lastInfo": 1447284263690,
                "nativePushEnabled": true
            },
            "appInfo": {
                "scoreLevel2": "5"
            },
            "deviceId": "446cb485edc9424ba509bc6e97002d56"
        },
        {
            "meta": {
                "lastSeen": 1447729996536,
                "firstSeen": 1446679215422,
                "lastLocation": 1447729996772,
                "lastInfo": 1446776042448,
                "nativePushEnabled": true
            },
            "deviceId": "46135ee6e705f3916b16678994c0e767"
        }
    ],
    "nextLink": "/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$select=meta,appInfo/scoreLevel2&$filter=deviceId%20gt%20'446cb485edc9424ba509bc6e97002d56'"
}

Note that second device appInfo object is thus unset.

$filter

Previous examples already show the $filter parameter generated in nextLink for paging. But you can use it for other purposes.

For example, if you want to check all appInfo properties that have been modified since the last time you called the API, you can also use the lastModified property in the filter expression.

Suppose the last time you called the API is November 17th 2015 at midnight UTC (1447718400000L in milliseconds), the call looks like this:

GET /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01&$top=2&$select=appInfo&$filter=lastModified%20ge%201447718400000L  HTTP/1.1
Host: management.azure.com
Accept: */*
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9.eyJhdWQiOiJodHRwczovL21hbmFnZW1lbnQuY29yZS53aW5kb3dzLm5ldC8iL

HTTP/1.1 200 OK
Content-Type: application/json

{
    "value": [
        {
            "appInfo": {
                "scoreLevel3": "4"
                "scoreLevel4": "2"
            },
            "deviceId": "446cb485edc9424ba509bc6e97002d56"
        },
        {
            "appInfo": {
                "scoreLevel3": "5"
            },
            "deviceId": "46135ee6e705f3916b16678994c0e767"
        }
    ],
    "nextLink": "/subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices?api-version=2014-12-01$top=2&$select=appInfo&$filter=lastModified%20ge%201447718400000L%20and%20deviceId%20gt%20'446cb485edc9424ba509bc6e97002d56'"
}

The original request is using $filter=lastModified ge 1447718400000L, and since there is paging, the generated nextLink property is thus using the and operator like this: $filter=lastModified ge 1447718400000L and deviceId gt '46135ee6e705f3916b16678994c0e767'.