Tag devices

  • Article

 

Update the tags registered for a set of devices running an application.

Devices can be identified by their regular device identifier or by a custom user identifier. The custom user identifier is simply a special reserved tag, which key is userid. To set this special tag, use this command or use the SDK’s sendAppInfo function.

Note

Updates are performed asynchronously.
This means that a few seconds are needed before the modifications appear in the results of the Get device command.

Request

Tag by device IDs or user IDs.

Method

Request URI

HTTP version

POST

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

HTTP/1.1

POST

https://management.azure.com/subscriptions/{subscription-id}/resourcegroups/{resource-group-name}/providers/Microsoft.MobileEngagement/appcollections/{app-collection}/apps/{app-resource-name}/users/tag?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.

Request Headers

The following table describes required and optional request headers.

Request Header

Description

Authorization

See Authentication.

Content-Type

application/json

Accept (optional)

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

Request Body

A JSON object with the following properties:

Property

Description

tags

A JSON objects describing the set of tags to record for a set of users.

Example:

{
  "5a2fbedd9e3322348f699776b50b78f1": {
    "userid": "alice",
    "subscriptionMovies": "true"
  },
  "94740937eb1aa554a586683a8bb3592e": {
    "userid": "bob",
    "subscriptionSports": null
  }
}

deleteOnNull (optional) 

If this parameter is true, tags with a null value will be deleted.

Default value: false.

Response

A 200 status code is returned on success.

Response Status Codes

Code

Description

200

OK, response body includes rejected devices.

400

Can be caused by one of the following conditions:

  • Invalid parameters.

  • Application is not enabled.

Check response body for details.

401

Authentication error.

413

Can be caused by having too many device identifiers (current limit is 1000).

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

invalidIds

A JSON array containing all identifiers that have been rejected.

Please note that if the request parameters are valid but all the specified devices are rejected, the status code
is still 200 with a response including all the devices as being rejected.

Examples

Example using device identifiers

In this example device ID 94740937eb1aa554a586683a8bb3592e does not exist and is reported in invalidIds.

POST /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/devices/tag?api-version=2014-12-01 HTTP/1.1
Host: management.azure.com
Accept: */*
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9

{
  "tags": {
    "5a2fbedd9e3322348f699776b50b78f1": {
      "userid": "alice",
      "subscriptionMovies": "true"
    },
    "94740937eb1aa554a586683a8bb3592e": {
      "userid": "bob",
      "subscriptionSports": null
    }
  },
  "deleteOnNull" : true
}

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

{
  "invalidIds" : [ "94740937eb1aa554a586683a8bb3592e" ]
}

Example using user identifiers

In this example the user ID bob does not exist and is reported in invalidIds.

POST /subscriptions/84211edf-7c40-4c47-b152-a6a7233843b7/resourcegroups/MobileEngagement/providers/Microsoft.MobileEngagement/appcollections/myAppCollection/apps/myApp-android/users/tag?api-version=2014-12-01 HTTP/1.1
Host: management.azure.com
Accept: */*
Content-Type: application/json
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSIsImtpZCI6Ik1uQ19WWmNBVGZNNXBPWWlKSE1iYTlnb0VLWSJ9

{
  "tags": {
    "alice": {
      "subscriptionMovies": "true"
      "subscriptionSports": "false"
    },
    "bob": {
      "subscriptionSports": "false"
    }
  }
}

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

{
  "invalidIds" : [ "bob" ]
}