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
deploymentGroupId
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

DeploymentTargetExpands

Include these additional details in the returned objects.

$top
query

integer

int32

Maximum number of deployment targets to return. Default is 1000.

agentJobResult
query

TaskAgentJobResultFilter

Get only deployment targets that have this last job result.

agentStatus
query

TaskAgentStatusFilter

Get only deployment targets that have this status.

continuationToken
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.

partialNameMatch
query

boolean

When set to true, treats name as pattern. Else treats it as absolute match. Default is false.

propertyFilters
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

DeploymentMachine[]

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
Get deployment targets filtered by agent status
Get deployment targets having given tags
Get deployment targets in pages
Get deployment targets including their last job requests
List all deployment targets in a deployment group

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
DeploymentMachine

Deployment target.

DeploymentTargetExpands

Include these additional details in the returned objects.

IdentityRef
JObject

Represents a JSON object.

JToken

Represents an abstract JSON token.

PackageVersion
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.

ReferenceLinks

The class to represent a collection of REST reference links.

TaskAgent

A task agent.

TaskAgentAuthorization

Provides data necessary for authorizing the agent using OAuth 2.0 authentication flows.

TaskAgentCloudRequest
TaskAgentJobRequest

A job request for an agent.

TaskAgentJobResultFilter

Get only deployment targets that have this last job result.

TaskAgentPoolOptions

Additional pool settings and details

TaskAgentPoolReference
TaskAgentPoolType

Gets or sets the type of the pool

TaskAgentPublicKey

Represents the public key portion of an RSA asymmetric key.

TaskAgentReference

A reference to an agent.

TaskAgentStatus

Whether or not the agent is online.

TaskAgentStatusFilter

Get only deployment targets that have this status.

TaskAgentUpdate

Details about an agent update.

TaskAgentUpdateReason
TaskAgentUpdateReasonType
TaskOrchestrationOwner
TaskResult

The result of this request.

Demand

Name Type Description
name

string

value

string

DeploymentMachine

Deployment target.

Name Type Description
agent

TaskAgent

Deployment agent.

id

integer

Deployment target Identifier.

properties

PropertiesCollection

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

ReferenceLinks

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

JToken

Represents an abstract JSON token.

type

string

Gets the node type for this JToken.

JToken

Represents an abstract JSON token.

Name Type Description
first

JToken

Get the first child token of this token.

hasValues

boolean

Gets a value indicating whether this token has child tokens.

item

JToken

Represents an abstract JSON token.

last

JToken

Get the last child token of this token.

next

JToken

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

JToken

Gets the previous sibling token of this node.

root

JToken

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.

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

ReferenceLinks

The class to represent a collection of REST reference links.

accessPoint

string

This agent's access point.

assignedAgentCloudRequest

TaskAgentCloudRequest

The agent cloud request that's currently associated with this agent.

assignedRequest

TaskAgentJobRequest

The request which is currently assigned to this agent.

authorization

TaskAgentAuthorization

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

TaskAgentJobRequest

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

TaskAgentUpdate

Pending update for this agent.

properties

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.

provisioningState

string

Provisioning state of this agent.

status

TaskAgentStatus

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

TaskAgentPublicKey

Public key used to verify the identity of this agent.

TaskAgentCloudRequest

Name Type Description
agent

TaskAgentReference

A reference to an agent.

agentCloudId

integer

agentConnectedTime

string

agentData

JObject

Represents a JSON object.

agentSpecification

JObject

Represents a JSON object.

pool

TaskAgentPoolReference

provisionRequestTime

string

provisionedTime

string

releaseRequestTime

string

requestId

string

TaskAgentJobRequest

A job request for an agent.

Name Type Description
agentSpecification

JObject

Represents a JSON object.

assignTime

string

The date/time this request was assigned.

data

object

Additional data about the request.

definition

TaskOrchestrationOwner

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

TaskAgentReference[]

A reference to an agent.

matchesAllAgentsInPool

boolean

orchestrationId

string

owner

TaskOrchestrationOwner

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

TaskAgentReference

The agent allocated for this request.

result

TaskResult

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

TaskAgentPoolOptions

Additional pool settings and details

poolType

TaskAgentPoolType

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

ReferenceLinks

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

TaskAgentStatus

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

TaskAgentUpdateReason

Reason for this update.

requestTime

string

Date on which this update was requested.

requestedBy

IdentityRef

Identity which requested this update.

sourceVersion

PackageVersion

Source agent version of the update.

targetVersion

PackageVersion

Target agent version of the update.

TaskAgentUpdateReason

Name Type Description
code

TaskAgentUpdateReasonType

TaskAgentUpdateReasonType

Name Type Description
downgrade

string

manual

string

minAgentVersionRequired

string

TaskOrchestrationOwner

Name Type Description
_links

ReferenceLinks

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