Label
Labels are pre-defined or custom key / value pairs that can be tied to elements for easy recognition and selection.
The following elements in the platform can have labels:
Structure
key
string
Yes
The name of the label
value
string
Yes
The value of the label
Table 1: Label element structure
Requirements
A Label element has the following constraints:
allowed characters in the label key are a-z 0-9 _ -
the label key may be no longer than 50 characters
the label value may be no longer than 150 characters
Adding & updating labels
Labels in the ApplicationBuild and ApplicationInstance elements are stored as an array of Label elements:
PUT /applicationInstance/{applicationInstanceId}
Figure 1: Example labels for an ApplicationInstance element
When you want to add a new label, you can PUT an element with only that new label. You would submit:
PUT /applicationInstance/{applicationInstanceId}
Figure 2: Example of adding a new label to an ApplicationInstance element
The result will be that the element has 3 labels: label1
, label2
and label3
.
When you want to update a label, you only have to submit that one label for the element:
PUT /applicationInstance/{applicationInstanceId}
Figure 3: Example of updating an existing label of an ApplicationInstance element
Deleting a label is done by submitting a label with a null value:
PUT /applicationInstance/{applicationInstanceId}
Figure 4: Example of deleting a label from an ApplicationInstance element
After these example mutations, the element ends up with the following labels:
GET /applicationInstance/{applicationInstanceId}
Figure 5: The resulting labels for an ApplicationInstance element after applying the examples
Pre-defined labels
For ApplicationInstance elements, the platform creates a number of default labels (platform defined labels):
application_id
fleet_id
host_id
dc_location_id
region_id
region_name
application_build_id
These labels are always present for all ApplicationInstance elements. It does mean that user-defined labels cannot have the same name as platform defined labels. These names are reserved.
Using labels
Labels can be used to trim selections of elements.
In the API v3, using labels is done by adding a label expression as an URL query parameter.
An example of a label expression:
When used in an API v3 request the expression must be url encoded:
If you filter on region_name (or any other label with a string value) you must wrap the search value in double quotes:
The url encoded request:
Last updated