Custom tags API - POST tags
Add custom tags to the specified monitored entities.
The request consumes and produces an application/json
payload.
This request is an Early Adopter release and may be changed in non-compatible way.
POST |
|
Authentication
To execute this request, you need the Write entities (entities.write
) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
entitySelector | string |
Specifies the entities where you want to update tags. You need to set one of these criteria:
And you can add one or several of the following criteria. Values are case-sensitive and the
To set several criteria, separate them with a comma ( The length of the string is limited to 10,000 characters. |
query | required |
from | string |
The start of the requested timeframe. You can use one of the following formats:
If not set, the relative timeframe of 24 hours is used ( |
query | optional |
to | string |
The end of the requested timeframe. You can use one of the following formats:
If not set, the current timestamp is used. |
query | optional |
body | AddEntityTags |
The JSON body of the request. Contains tags to be added to the matching entities. |
body | optional |
Body format
The AddEntityTags object
A list of tags to be added to monitored entities.
Element | Type | Description | Required |
---|---|---|---|
tags | AddEntityTag[] |
A list of tags to be added to monitored entities. |
required |
The AddEntityTag object
The custom tag to be added to monitored entities.
Element | Type | Description | Required |
---|---|---|---|
value | string |
The value of the custom tag to be added to monitored entities. May be null |
optional |
key | string |
The key of the custom tag to be added to monitored entities. |
required |
This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.
{
"tags": [
{
"key": "mainApp"
},
{
"key": "bookings",
"value": "42"
}
]
}
Response
Response codes
Code | Description |
---|---|
200 | Success |
Response body
The AddedEntityTags object
A list of custom tags added to monitored entities.
Element | Type | Description |
---|---|---|
appliedTags | METag[] | A list of added custom tags. |
matchedEntitiesCount | integer | The number of monitored entities where the tags have been added. |
The METag object
The tag of a monitored entity.
Element | Type | Description |
---|---|---|
stringRepresentation | string | The string representation of the tag. |
value | string | The value of the tag. |
key | string | The key of the tag. |
context | string | The origin of the tag, such as AWS or Cloud Foundry. Custom tags use the |
{
"appliedTags": [
{
"context": "CONTEXTLESS",
"key": "mainApp",
"stringRepresentation": "mainApp"
},
{
"context": "CONTEXTLESS",
"key": "booking",
"stringRepresentation": "booking"
}
],
"matchedEntitiesCount": 2
}
Example
In this example, the request adds the REST-test and RESTexample custom tags to hosts that already have the easyTravel tag. To achieve that, the entitySelector query parameter is set to type("HOST"),tag("easyTravel")
.
The API token is passed in the Authorization header.
Curl
curl -L -X POST 'https://mySampleEnv.live.dynatrace.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)' \
-H 'Authorization: Api-Token abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
--data-raw '{
"tags": [
{
"key": "REST-test"
},
{
"key": "RESTexample"
}
]
}'
Request URL
https://mySampleEnv.live.dynatrace.com/api/v2/tags?entitySelector=type(%22HOST%22),tag(%22easyTravel%22)
Request body
api-examples/env/tags/post-tags.json
{
"tags": [
{
"key": "REST-test"
},
{
"key": "RESTexample"
}
]
}
Response body
{
"matchedEntitiesCount": 3,
"appliedTags": [
{
"context": "CONTEXTLESS",
"key": "REST-test",
"stringRepresentation": "REST-test"
},
{
"context": "CONTEXTLESS",
"key": "RESTexample",
"stringRepresentation": "RESTexample"
}
]
}
Response code
200