Targets - List
Get a list of deployment targets in a deployment group.
GET https://dev.azure.com/{organization}/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
GET https://dev.azure.com/{organization}/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?tags={tags}&name={name}&partialNameMatch={partialNameMatch}&$expand={$expand}&agentStatus={agentStatus}&agentJobResult={agentJobResult}&continuationToken={continuationToken}&$top={$top}&enabled={enabled}&propertyFilters={propertyFilters}&api-version=7.1-preview.1
URI Parameters
Name | In | Required | Type | Description |
---|---|---|---|---|
deployment
|
path | True |
integer int32 |
ID of the deployment group. |
organization
|
path | True |
string |
The name of the Azure DevOps organization. |
project
|
path | True |
string |
Project ID or project name |
api-version
|
query | True |
string |
Version of the API to use. This should be set to '7.1-preview.1' to use this version of the api. |
$expand
|
query |
Include these additional details in the returned objects. |
||
$top
|
query |
integer int32 |
Maximum number of deployment targets to return. Default is 1000. |
|
agent
|
query |
Get only deployment targets that have this last job result. |
||
agent
|
query |
Get only deployment targets that have this status. |
||
continuation
|
query |
string |
Get deployment targets with names greater than this continuationToken lexicographically. |
|
enabled
|
query |
boolean |
Get only deployment targets that are enabled or disabled. Default is 'null' which returns all the targets. |
|
name
|
query |
string |
Name pattern of the deployment targets to return. |
|
partial
|
query |
boolean |
When set to true, treats name as pattern. Else treats it as absolute match. Default is false. |
|
property
|
query |
string array (string) |
||
tags
|
query |
string array (string) |
Get only the deployment targets that contain all these comma separted list of tags. |
Responses
Name | Type | Description |
---|---|---|
200 OK |
successful operation |
Security
oauth2
Type:
oauth2
Flow:
accessCode
Authorization URL:
https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
Token URL:
https://app.vssps.visualstudio.com/oauth2/token?client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
Scopes
Name | Description |
---|---|
vso.machinegroup_manage | Provides ability to manage deployment group and agent pools |
Examples
Get deployment targets by partial name match
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
{
"count": 1,
"value": [
{
"tags": [
"web"
],
"id": 5,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/5"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=5"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:19:41.053Z",
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "online"
}
}
]
}
Get deployment targets filtered by agent status
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
{
"count": 1,
"value": [
{
"tags": [
"web"
],
"id": 5,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/5"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=5"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:19:41.053Z",
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "online"
}
}
]
}
Get deployment targets having given tags
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
{
"count": 1,
"value": [
{
"tags": [
"db",
"web"
],
"id": 7,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/7"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=7"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:26:48.11Z",
"id": 7,
"name": "demoTarget11",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "offline"
}
}
]
}
Get deployment targets in pages
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
x-MS-ContinuationToken: demoTarget2
{
"count": 2,
"value": [
{
"tags": [
"web"
],
"id": 5,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/5"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=5"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:19:41.053Z",
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "online"
}
},
{
"tags": [
"db",
"web"
],
"id": 7,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/7"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=7"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:26:48.11Z",
"id": 7,
"name": "demoTarget11",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "offline"
}
}
]
}
Get deployment targets including their last job requests
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
{
"count": 1,
"value": [
{
"tags": [
"web"
],
"id": 5,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/5"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=5"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:19:41.053Z",
"lastCompletedRequest": {
"requestId": 1,
"queueTime": "2018-02-19T09:28:48.2633333Z",
"assignTime": "2018-02-19T09:28:48.2633333Z",
"receiveTime": "2018-02-19T09:28:52.2811279Z",
"finishTime": "2018-02-19T09:28:57.7333333Z",
"result": "succeeded",
"serviceOwner": "0000000d-0000-8888-8000-000000000000",
"hostId": "86088ab1-30d8-4526-9663-3406752b8bc6",
"scopeId": "91879ed9-819b-46f3-9e0b-52ed4b20c04c",
"planType": "Deployment",
"planId": "b7245fde-fb04-40f3-b187-78772599f522",
"jobId": "2fd39b55-daaa-499a-ad70-1896ac468a9f",
"demands": [
"DotNetFramework",
"Agent.Version -gtVersion 1.102"
],
"reservedAgent": {
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"enabled": true,
"status": "online"
},
"definition": {
"_links": {
"web": {
"href": "https://dev.azure.com/fabrikam/91879ed9-819b-46f3-9e0b-52ed4b20c04c/_release?definitionId=1"
},
"self": {
"href": "https://https://vsrm.dev.azure.com/fabrikam/91879ed9-819b-46f3-9e0b-52ed4b20c04c/_apis/Release/definitions/1"
}
},
"id": 1,
"name": "New Release Definition"
},
"owner": {
"_links": {
"web": {
"href": "https://dev.azure.com/fabrikam/91879ed9-819b-46f3-9e0b-52ed4b20c04c/_release?releaseId=1&_a=release-summary"
},
"self": {
"href": "https://https://vsrm.dev.azure.com/fabrikam/91879ed9-819b-46f3-9e0b-52ed4b20c04c/_apis/Release/releases/1"
}
},
"id": 1,
"name": "Release-1 / Environment 1"
},
"data": {},
"agentDelays": []
},
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "online"
}
}
]
}
List all deployment targets in a deployment group
Sample Request
GET https://dev.azure.com/fabrikam/{project}/_apis/distributedtask/deploymentgroups/{deploymentGroupId}/targets?api-version=7.1-preview.1
Sample Response
{
"count": 3,
"value": [
{
"tags": [
"web"
],
"id": 5,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/5"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=5"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:19:41.053Z",
"id": 5,
"name": "demoTarget1",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "online"
}
},
{
"tags": [
"db",
"web"
],
"id": 7,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/7"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=7"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:26:48.11Z",
"id": 7,
"name": "demoTarget11",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "offline"
}
},
{
"tags": [
"db"
],
"id": 6,
"agent": {
"_links": {
"self": {
"href": "https://dev.azure.com/fabrikam/_apis/distributedtask/pools/17/agents/6"
},
"web": {
"href": "https://dev.azure.com/fabrikam/_admin/_AgentPool#_a=agents&poolId=17&agentId=6"
}
},
"maxParallelism": 1,
"createdOn": "2018-02-19T09:23:58.267Z",
"id": 6,
"name": "demoTarget2",
"version": "2.127.0",
"osDescription": "Microsoft Windows 10.0.14393 ",
"enabled": true,
"status": "offline"
}
}
]
}
Definitions
Name | Description |
---|---|
Demand | |
Deployment |
Deployment target. |
Deployment |
Include these additional details in the returned objects. |
Identity |
|
JObject |
Represents a JSON object. |
JToken |
Represents an abstract JSON token. |
Package |
|
Properties |
The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a |
Reference |
The class to represent a collection of REST reference links. |
Task |
A task agent. |
Task |
Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows. |
Task |
|
Task |
A job request for an agent. |
Task |
Get only deployment targets that have this last job result. |
Task |
Additional pool settings and details |
Task |
|
Task |
Gets or sets the type of the pool |
Task |
Represents the public key portion of an RSA asymmetric key. |
Task |
A reference to an agent. |
Task |
Whether or not the agent is online. |
Task |
Get only deployment targets that have this status. |
Task |
Details about an agent update. |
Task |
|
Task |
|
Task |
|
Task |
The result of this request. |
Demand
Name | Type | Description |
---|---|---|
name |
string |
|
value |
string |
DeploymentMachine
Deployment target.
Name | Type | Description |
---|---|---|
agent |
Deployment agent. |
|
id |
integer |
Deployment target Identifier. |
properties |
Properties of the deployment target. |
|
tags |
string[] |
Tags of the deployment target. |
DeploymentTargetExpands
Include these additional details in the returned objects.
Name | Type | Description |
---|---|---|
assignedRequest |
string |
Include the job request assigned to the deployment agent. |
capabilities |
string |
Include capabilities of the deployment agent. |
lastCompletedRequest |
string |
Include the last completed job request of the deployment agent. |
none |
string |
No additional properties. |
IdentityRef
Name | Type | Description |
---|---|---|
_links |
This field contains zero or more interesting links about the graph subject. These links may be invoked to obtain additional relationships or more detailed information about this graph subject. |
|
descriptor |
string |
The descriptor is the primary way to reference the graph subject while the system is running. This field will uniquely identify the same graph subject across both Accounts and Organizations. |
directoryAlias |
string |
Deprecated - Can be retrieved by querying the Graph user referenced in the "self" entry of the IdentityRef "_links" dictionary |
displayName |
string |
This is the non-unique display name of the graph subject. To change this field, you must alter its value in the source provider. |
id |
string |
|
imageUrl |
string |
Deprecated - Available in the "avatar" entry of the IdentityRef "_links" dictionary |
inactive |
boolean |
Deprecated - Can be retrieved by querying the Graph membership state referenced in the "membershipState" entry of the GraphUser "_links" dictionary |
isAadIdentity |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsAadUserType/Descriptor.IsAadGroupType) |
isContainer |
boolean |
Deprecated - Can be inferred from the subject type of the descriptor (Descriptor.IsGroupType) |
isDeletedInOrigin |
boolean |
|
profileUrl |
string |
Deprecated - not in use in most preexisting implementations of ToIdentityRef |
uniqueName |
string |
Deprecated - use Domain+PrincipalName instead |
url |
string |
This url is the full route to the source resource of this graph subject. |
JObject
Represents a JSON object.
Name | Type | Description |
---|---|---|
item |
Represents an abstract JSON token. |
|
type |
string |
Gets the node type for this JToken. |
JToken
Represents an abstract JSON token.
Name | Type | Description |
---|---|---|
first |
Get the first child token of this token. |
|
hasValues |
boolean |
Gets a value indicating whether this token has child tokens. |
item |
Represents an abstract JSON token. |
|
last |
Get the last child token of this token. |
|
next |
Gets the next sibling token of this node. |
|
parent |
string |
Gets or sets the parent. |
path |
string |
Gets the path of the JSON token. |
previous |
Gets the previous sibling token of this node. |
|
root |
Gets the root JToken of this JToken. |
|
type |
string |
Gets the node type for this JToken. |
PackageVersion
Name | Type | Description |
---|---|---|
major |
integer |
|
minor |
integer |
|
patch |
integer |
PropertiesCollection
The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a TypeCode != TypeCode.Object
) except for DBNull
are accepted. Values of type Byte[], Int32, Double, DateType and String preserve their type, other primitives are retuned as a String. Byte[] expected as base64 encoded string.
Name | Type | Description |
---|---|---|
count |
integer |
The count of properties in the collection. |
item |
object |
|
keys |
string[] |
The set of keys in the collection. |
values |
string[] |
The set of values in the collection. |
ReferenceLinks
The class to represent a collection of REST reference links.
Name | Type | Description |
---|---|---|
links |
object |
The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only. |
TaskAgent
A task agent.
Name | Type | Description |
---|---|---|
_links |
The class to represent a collection of REST reference links. |
|
accessPoint |
string |
This agent's access point. |
assignedAgentCloudRequest |
The agent cloud request that's currently associated with this agent. |
|
assignedRequest |
The request which is currently assigned to this agent. |
|
authorization |
Authorization information for this agent. |
|
createdOn |
string |
Date on which this agent was created. |
enabled |
boolean |
Whether or not this agent should run jobs. |
id |
integer |
Identifier of the agent. |
lastCompletedRequest |
The last request which was completed by this agent. |
|
maxParallelism |
integer |
Maximum job parallelism allowed for this agent. |
name |
string |
Name of the agent. |
osDescription |
string |
Agent OS. |
pendingUpdate |
Pending update for this agent. |
|
properties |
The class represents a property bag as a collection of key-value pairs. Values of all primitive types (any type with a |
|
provisioningState |
string |
Provisioning state of this agent. |
status |
Whether or not the agent is online. |
|
statusChangedOn |
string |
Date on which the last connectivity status change occurred. |
systemCapabilities |
object |
System-defined capabilities supported by this agent's host. Warning: To set capabilities use the PUT method, PUT will completely overwrite existing capabilities. |
userCapabilities |
object |
User-defined capabilities supported by this agent's host. Warning: To set capabilities use the PUT method, PUT will completely overwrite existing capabilities. |
version |
string |
Agent version. |
TaskAgentAuthorization
Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.
Name | Type | Description |
---|---|---|
authorizationUrl |
string |
Endpoint used to obtain access tokens from the configured token service. |
clientId |
string |
Client identifier for this agent. |
publicKey |
Public key used to verify the identity of this agent. |
TaskAgentCloudRequest
Name | Type | Description |
---|---|---|
agent |
A reference to an agent. |
|
agentCloudId |
integer |
|
agentConnectedTime |
string |
|
agentData |
Represents a JSON object. |
|
agentSpecification |
Represents a JSON object. |
|
pool | ||
provisionRequestTime |
string |
|
provisionedTime |
string |
|
releaseRequestTime |
string |
|
requestId |
string |
TaskAgentJobRequest
A job request for an agent.
Name | Type | Description |
---|---|---|
agentSpecification |
Represents a JSON object. |
|
assignTime |
string |
The date/time this request was assigned. |
data |
object |
Additional data about the request. |
definition |
The pipeline definition associated with this request |
|
demands |
Demand[] |
A list of demands required to fulfill this request. |
finishTime |
string |
The date/time this request was finished. |
hostId |
string |
The host which triggered this request. |
jobId |
string |
ID of the job resulting from this request. |
jobName |
string |
Name of the job resulting from this request. |
lockedUntil |
string |
The deadline for the agent to renew the lock. |
matchedAgents |
A reference to an agent. |
|
matchesAllAgentsInPool |
boolean |
|
orchestrationId |
string |
|
owner |
The pipeline associated with this request |
|
planGroup |
string |
|
planId |
string |
Internal ID for the orchestration plan connected with this request. |
planType |
string |
Internal detail representing the type of orchestration plan. |
poolId |
integer |
The ID of the pool this request targets |
priority |
integer |
|
queueId |
integer |
The ID of the queue this request targets |
queueTime |
string |
The date/time this request was queued. |
receiveTime |
string |
The date/time this request was receieved by an agent. |
requestId |
integer |
ID of the request. |
reservedAgent |
The agent allocated for this request. |
|
result |
The result of this request. |
|
scopeId |
string |
Scope of the pipeline; matches the project ID. |
serviceOwner |
string |
The service which owns this request. |
statusMessage |
string |
|
userDelayed |
boolean |
TaskAgentJobResultFilter
Get only deployment targets that have this last job result.
Name | Type | Description |
---|---|---|
all |
string |
All deployment targets. |
failed |
string |
Only those deployment targets on which last job failed (Abandoned, Canceled, Failed, Skipped). |
neverDeployed |
string |
Only those deployment targets that never executed a job. |
passed |
string |
Only those deployment targets on which last job Passed (Succeeded, Succeeded with issues). |
TaskAgentPoolOptions
Additional pool settings and details
Name | Type | Description |
---|---|---|
elasticPool |
string |
TaskAgentPool backed by the Elastic pool service |
none |
string |
|
preserveAgentOnJobFailure |
string |
Set to true if agents are held for investigation after a TaskAgentJobRequest failure |
singleUseAgents |
string |
Set to true if agents are re-imaged after each TaskAgentJobRequest |
TaskAgentPoolReference
Name | Type | Description |
---|---|---|
id |
integer |
|
isHosted |
boolean |
Gets or sets a value indicating whether or not this pool is managed by the service. |
isLegacy |
boolean |
Determines whether the pool is legacy. |
name |
string |
|
options |
Additional pool settings and details |
|
poolType |
Gets or sets the type of the pool |
|
scope |
string |
|
size |
integer |
Gets the current size of the pool. |
TaskAgentPoolType
Gets or sets the type of the pool
Name | Type | Description |
---|---|---|
automation |
string |
A typical pool of task agents |
deployment |
string |
A deployment pool |
TaskAgentPublicKey
Represents the public key portion of an RSA asymmetric key.
Name | Type | Description |
---|---|---|
exponent |
string[] |
Gets or sets the exponent for the public key. |
modulus |
string[] |
Gets or sets the modulus for the public key. |
TaskAgentReference
A reference to an agent.
Name | Type | Description |
---|---|---|
_links |
The class to represent a collection of REST reference links. |
|
accessPoint |
string |
This agent's access point. |
enabled |
boolean |
Whether or not this agent should run jobs. |
id |
integer |
Identifier of the agent. |
name |
string |
Name of the agent. |
osDescription |
string |
Agent OS. |
provisioningState |
string |
Provisioning state of this agent. |
status |
Whether or not the agent is online. |
|
version |
string |
Agent version. |
TaskAgentStatus
Whether or not the agent is online.
Name | Type | Description |
---|---|---|
offline |
string |
|
online |
string |
TaskAgentStatusFilter
Get only deployment targets that have this status.
Name | Type | Description |
---|---|---|
all |
string |
All deployment targets. |
offline |
string |
Only deployment targets that are offline. |
online |
string |
Only deployment targets that are online. |
TaskAgentUpdate
Details about an agent update.
Name | Type | Description |
---|---|---|
currentState |
string |
Current state of this agent update. |
reason |
Reason for this update. |
|
requestTime |
string |
Date on which this update was requested. |
requestedBy |
Identity which requested this update. |
|
sourceVersion |
Source agent version of the update. |
|
targetVersion |
Target agent version of the update. |
TaskAgentUpdateReason
Name | Type | Description |
---|---|---|
code |
TaskAgentUpdateReasonType
Name | Type | Description |
---|---|---|
downgrade |
string |
|
manual |
string |
|
minAgentVersionRequired |
string |
TaskOrchestrationOwner
Name | Type | Description |
---|---|---|
_links |
The class to represent a collection of REST reference links. |
|
id |
integer |
|
name |
string |
TaskResult
The result of this request.
Name | Type | Description |
---|---|---|
abandoned |
string |
|
canceled |
string |
|
failed |
string |
|
skipped |
string |
|
succeeded |
string |
|
succeededWithIssues |
string |
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for