Definitions - Create

服务:

Build

API 版本:

7.1

创建新的定义。

POST https://dev.azure.com/{organization}/{project}/_apis/build/definitions?api-version=7.1

具有可选参数:

POST https://dev.azure.com/{organization}/{project}/_apis/build/definitions?definitionToCloneId={definitionToCloneId}&definitionToCloneRevision={definitionToCloneRevision}&api-version=7.1

URI 参数

名称	在	必需	类型	说明
organization	path	True	string	Azure DevOps 组织的名称。
project	path	True	string	项目 ID 或项目名称
api-version	query	True	string	要使用的 API 版本。 这应设置为“7.1”才能使用此版本的 API。
definitionToCloneId	query		integer (int32)
definitionToCloneRevision	query		integer (int32)

请求正文

名称	类型	说明
_links	ReferenceLinks	表示 REST 引用链接集合的类。
authoredBy	IdentityRef	定义的作者。
badgeEnabled	boolean	指示是否为此定义启用锁屏提醒。
buildNumberFormat	string	内部版本号格式。
comment	string	定义的节省时间注释。
createdDate	string (date-time)	创建此版本的定义日期。
demands	Demand[]	表示定义或生成使用的需求。
description	string	说明。
draftOf	DefinitionReference	如果这是草稿定义，则引用此定义是草稿的定义。
drafts	DefinitionReference[]	与此定义关联的草稿列表（如果这不是草稿定义）。
dropLocation	string	定义的放置位置。
id	integer (int32)	所引用定义的 ID。
jobAuthorizationScope	BuildAuthorizationScope	针对此定义排队生成的作业授权范围。
jobCancelTimeoutInMinutes	integer (int32)	此定义的生成取消的作业取消超时（以分钟为单位）。
jobTimeoutInMinutes	integer (int32)	针对此定义排队生成的作业执行超时（以分钟为单位）。
latestBuild	Build	生成的数据表示形式。
latestCompletedBuild	Build	生成的数据表示形式。
metrics	BuildMetric[]	表示系统中有关生成的元数据。
name	string	引用的定义的名称。
options	BuildOption[]	表示将可选行为应用于生成定义。
path	string	定义的文件夹路径。
process	BuildProcess	生成过程。
processParameters	ProcessParameters	此定义的进程参数。
project	TeamProjectReference	对项目的引用。
properties	PropertiesCollection	类将属性包表示为键值对的集合。 接受除 TypeCode != TypeCode.Object 以外的所有基元类型（具有 DBNull的任何类型）的值。 Byte[]、Int32、Double、DateType 和 String 类型的值将保留其类型，其他基元将重新调整为 String。 Byte[] 应为 base64 编码字符串。
quality	DefinitionQuality	定义文档的质量（草稿等）
queue	AgentPoolQueue	针对此定义运行的生成的默认队列。
queueStatus	DefinitionQueueStatus	一个值，该值指示是否可以针对此定义排队生成。
repository	BuildRepository	存储库。
retentionRules	RetentionPolicy[]	表示生成定义的保留策略。
revision	integer (int32)	定义修订号。
tags	string[]
triggers	BuildTrigger[]	表示布尔定义的触发器。
type	DefinitionType	定义的类型。
uri	string	定义的 URI。
url	string	定义的 REST URL。
variableGroups	VariableGroup[]	表示变量组。
variables	<string,  BuildDefinitionVariable>

响应

名称	类型	说明
200 OK	BuildDefinition	成功作

安全性

oauth2

类型: oauth2
流向: accessCode
授权 URL: https://app.vssps.visualstudio.com/oauth2/authorize&response_type=Assertion
令牌 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

作用域

名称	说明
vso.build_execute	授予访问生成项目（包括生成结果、定义和请求）以及排队生成、更新生成属性的功能，以及通过服务挂钩接收有关生成事件的通知的能力。

定义

名称	说明
AgentPoolQueue	表示用于运行生成的队列。
AgentSpecification	池提供程序定义的代理的规范。
AuthorizationHeader
Build	生成的数据表示形式。
BuildAuthorizationScope	针对此定义排队生成的作业授权范围。
BuildController
BuildDefinition	表示生成定义。
BuildDefinitionVariable	表示生成定义使用的变量。
BuildLogReference	表示对生成日志的引用。
BuildMetric	表示系统中有关生成的元数据。
BuildOption	表示将可选行为应用于生成定义。
BuildOptionDefinitionReference	表示对生成选项定义的引用。
BuildProcess	表示生成过程。
BuildReason	生成创建的原因。
BuildRepository	表示生成定义使用的存储库。
BuildRequestValidationResult	表示验证生成请求的结果。
BuildResult	生成结果。
BuildStatus	生成状态。
BuildTrigger	表示布尔定义的触发器。
ControllerStatus	控制器的状态。
DataSourceBindingBase	表示服务终结点请求的数据源绑定。
DefinitionQuality	定义文档的质量（草稿等）
DefinitionQueueStatus	一个值，该值指示是否可以针对此定义排队生成。
DefinitionReference	表示对定义的引用。
DefinitionTriggerType	触发器的类型。
DefinitionType	定义的类型。
Demand	表示定义或生成使用的需求。
IdentityRef
ProcessParameters
ProjectState	项目状态。
ProjectVisibility	项目可见性。
PropertiesCollection	类将属性包表示为键值对的集合。 接受除 TypeCode != TypeCode.Object 以外的所有基元类型（具有 DBNull的任何类型）的值。 Byte[]、Int32、Double、DateType 和 String 类型的值将保留其类型，其他基元将重新调整为 String。 Byte[] 应为 base64 编码字符串。
QueueOptions	用于对生成进行排队的其他选项。
QueuePriority	生成优先级。
ReferenceLinks	表示 REST 引用链接集合的类。
RetentionPolicy	表示生成定义的保留策略。
TaskAgentPoolReference	表示对代理池的引用。
TaskInputDefinitionBase
TaskInputValidation
TaskOrchestrationPlanReference	表示对业务流程计划的引用。
TaskSourceDefinitionBase
TeamProjectReference	表示对 TeamProject 的浅表引用。
ValidationResult	结果。
VariableGroup	表示变量组。

AgentPoolQueue

Object

表示用于运行生成的队列。

名称	类型	说明
_links	ReferenceLinks	表示 REST 引用链接集合的类。
id	integer (int32)	队列的 ID。
name	string	队列的名称。
pool	TaskAgentPoolReference	此队列使用的池。
url	string	指向资源的完整 http 链接。

AgentSpecification

Object

池提供程序定义的代理的规范。

名称	类型	说明
identifier	string	代理规范唯一标识符。

AuthorizationHeader

Object

名称	类型	说明
name	string
value	string

Build

Object

生成的数据表示形式。

名称	类型	说明
_links	ReferenceLinks	表示 REST 引用链接集合的类。
agentSpecification	AgentSpecification	生成的代理规范。
appendCommitMessageToRunName	boolean	在 UI 中将提交消息追加到 BuildNumber。
buildNumber	string	生成的内部版本号/名称。
buildNumberRevision	integer (int32)	内部版本号修订。
controller	BuildController	生成控制器。 仅当定义类型为 Xaml 时，才会设置此设置。
definition	DefinitionReference	与生成关联的定义。
deleted	boolean	指示是否已删除生成。
deletedBy	IdentityRef	删除生成的进程或人员的标识。
deletedDate	string (date-time)	删除生成日期。
deletedReason	string	如何删除生成的说明。
demands	Demand[]	表示此生成所需的代理功能的需求列表。
finishTime	string (date-time)	生成完成的时间。
id	integer (int32)	生成的 ID。
lastChangedBy	IdentityRef	表示上次更改生成的进程或人员的标识。
lastChangedDate	string (date-time)	上次更改生成日期。
logs	BuildLogReference	有关生成日志的信息。
orchestrationPlan	TaskOrchestrationPlanReference	生成的业务流程计划。
parameters	string	生成的参数。
plans	TaskOrchestrationPlanReference[]	与生成关联的业务流程计划（生成、清理）
priority	QueuePriority	生成优先级。
project	TeamProjectReference	团队项目。
properties	PropertiesCollection	类将属性包表示为键值对的集合。 接受除 TypeCode != TypeCode.Object 以外的所有基元类型（具有 DBNull的任何类型）的值。 Byte[]、Int32、Double、DateType 和 String 类型的值将保留其类型，其他基元将重新调整为 String。 Byte[] 应为 base64 编码字符串。
quality	string	xaml 生成的质量（好、坏等）
queue	AgentPoolQueue	队列。 仅当定义类型为 Build 时，才会设置此设置。 警告：此字段已弃用，不对应于作业队列。
queueOptions	QueueOptions	用于对生成进行排队的其他选项。
queuePosition	integer (int32)	生成在队列中的当前位置。
queueTime	string (date-time)	生成排队的时间。
reason	BuildReason	生成创建的原因。
repository	BuildRepository	存储库。
requestedBy	IdentityRef	对生成进行排队的标识。
requestedFor	IdentityRef	代表生成排队的标识。
result	BuildResult	生成结果。
retainedByRelease	boolean	指示版本是否保留生成。
sourceBranch	string	源分支。
sourceVersion	string	源版本。
startTime	string (date-time)	生成启动的时间。
status	BuildStatus	生成的状态。
tags	string[]
templateParameters	object	模板表达式计算的参数
triggerInfo	object	有关触发生成的内容的 Sourceprovider 特定信息
triggeredByBuild	Build	通过生成完成触发器触发此生成的生成。
uri	string	生成的 URI。
url	string	生成的 REST URL。
validationResults	BuildRequestValidationResult[]	表示验证生成请求的结果。

BuildAuthorizationScope

枚举

针对此定义排队生成的作业授权范围。

值	说明
project	使用的标识应将生成服务帐户权限限定为生成定义所在的项目。 这对于将生成作业隔离到特定团队项目非常有用，以避免在生成过程中意外升级特权攻击。
projectCollection	使用的标识应具有范围限定为项目集合的生成服务帐户权限。 当单个生成的资源分散在多个项目中时，这非常有用。

BuildController

Object

名称	类型	说明
_links	ReferenceLinks	表示 REST 引用链接集合的类。
createdDate	string (date-time)	控制器的创建日期。
description	string	控制器的说明。
enabled	boolean	指示是否启用控制器。
id	integer (int32)	资源的 ID
name	string	链接资源的名称（定义名称、控制器名称等）
status	ControllerStatus	控制器的状态。
updatedDate	string (date-time)	控制器上次更新的日期。
uri	string	控制器的 URI。
url	string	指向资源的完整 http 链接

BuildDefinition

Object

表示生成定义。

名称	类型	说明
_links	ReferenceLinks	表示 REST 引用链接集合的类。
authoredBy	IdentityRef	定义的作者。
badgeEnabled	boolean	指示是否为此定义启用锁屏提醒。
buildNumberFormat	string	内部版本号格式。
comment	string	定义的节省时间注释。
createdDate	string (date-time)	创建此版本的定义日期。
demands	Demand[]	表示定义或生成使用的需求。
description	string	说明。
draftOf	DefinitionReference	如果这是草稿定义，则引用此定义是草稿的定义。
drafts	DefinitionReference[]	与此定义关联的草稿列表（如果这不是草稿定义）。
dropLocation	string	定义的放置位置。
id	integer (int32)	所引用定义的 ID。
jobAuthorizationScope	BuildAuthorizationScope	针对此定义排队生成的作业授权范围。
jobCancelTimeoutInMinutes	integer (int32)	此定义的生成取消的作业取消超时（以分钟为单位）。
jobTimeoutInMinutes	integer (int32)	针对此定义排队生成的作业执行超时（以分钟为单位）。
latestBuild	Build	生成的数据表示形式。
latestCompletedBuild	Build	生成的数据表示形式。
metrics	BuildMetric[]	表示系统中有关生成的元数据。
name	string	引用的定义的名称。
options	BuildOption[]	表示将可选行为应用于生成定义。
path	string	定义的文件夹路径。
process	BuildProcess	生成过程。
processParameters	ProcessParameters	此定义的进程参数。
project	TeamProjectReference	对项目的引用。
properties	PropertiesCollection	类将属性包表示为键值对的集合。 接受除 TypeCode != TypeCode.Object 以外的所有基元类型（具有 DBNull的任何类型）的值。 Byte[]、Int32、Double、DateType 和 String 类型的值将保留其类型，其他基元将重新调整为 String。 Byte[] 应为 base64 编码字符串。
quality	DefinitionQuality	定义文档的质量（草稿等）
queue	AgentPoolQueue	针对此定义运行的生成的默认队列。
queueStatus	DefinitionQueueStatus	一个值，该值指示是否可以针对此定义排队生成。
repository	BuildRepository	存储库。
retentionRules	RetentionPolicy[]	表示生成定义的保留策略。
revision	integer (int32)	定义修订号。
tags	string[]
triggers	BuildTrigger[]	表示布尔定义的触发器。
type	DefinitionType	定义的类型。
uri	string	定义的 URI。
url	string	定义的 REST URL。
variableGroups	VariableGroup[]	表示变量组。
variables	<string,  BuildDefinitionVariable>

BuildDefinitionVariable

Object

表示生成定义使用的变量。

名称	类型	说明
allowOverride	boolean	指示是否可以在队列时设置该值。
isSecret	boolean	指示变量的值是否为机密。
value	string	变量的值。

BuildLogReference

Object

表示对生成日志的引用。

名称	类型	说明
id	integer (int32)	日志的 ID。
type	string	日志位置的类型。
url	string	日志资源的完整链接。

BuildMetric

Object

表示系统中有关生成的元数据。

名称	类型	说明
date	string (date-time)	范围的日期。
intValue	integer (int32)	值。
name	string	指标的名称。
scope	string	范围。

BuildOption

Object

表示将可选行为应用于生成定义。

名称	类型	说明
definition	BuildOptionDefinitionReference	对生成选项的引用。
enabled	boolean	指示是否启用该行为。
inputs	object

BuildOptionDefinitionReference

Object

表示对生成选项定义的引用。

名称	类型	说明
id	string (uuid)	引用的生成选项的 ID。

BuildProcess

Object

表示生成过程。

名称	类型	说明
type	integer (int32)	进程的类型。

BuildReason

枚举

生成创建的原因。

值	说明
all	所有原因。
batchedCI	已为触发器 TriggerType.BatchedContinuousIntegration 启动生成。
buildCompletion	生成是在另一个生成完成时启动的。
checkInShelveset	已为触发器 ContinuousIntegrationType.Gated 启动生成。
individualCI	已为触发器 TriggerType.ContinuousIntegration 启动生成。
manual	生成是手动启动的。
none	没有理由。 不应使用此值。
pullRequest	生成是通过拉取请求启动的。 在资源版本 3 中添加。
resourceTrigger	当管道中的资源触发生成时启动生成
schedule	已为触发器 TriggerType.Schedule 启动生成。
scheduleForced	已为触发器 TriggerType.ScheduleForced 启动生成。
triggered	生成是出于保留策略目的触发的。
userCreated	生成由用户创建。
validateShelveset	生成是手动启动的，用于专用验证。

BuildRepository

Object

表示生成定义使用的存储库。

名称	类型	说明
checkoutSubmodules	boolean	指示是否签出子模块。
clean	string	指示从存储库获取代码时是否清理目标文件夹。
defaultBranch	string	默认分支的名称。
id	string	存储库的 ID。
name	string	存储库的友好名称。
properties	object
rootFolder	string	根文件夹。
type	string	存储库的类型。
url	string	存储库的 URL。

BuildRequestValidationResult

Object

表示验证生成请求的结果。

名称	类型	说明
message	string	与结果关联的消息。
result	ValidationResult	结果。

BuildResult

枚举

生成结果。

值	说明
canceled	生成在启动之前已取消。
failed	生成未成功完成。
none	无结果
partiallySucceeded	生成成功完成编译，但出现其他错误。
succeeded	生成成功完成。

BuildStatus

枚举

生成状态。

值	说明
all	所有状态。
cancelling	生成正在取消
completed	生成已完成。
inProgress	生成当前正在进行中。
none	无状态。
notStarted	生成尚未启动。
postponed	生成在队列中处于非活动状态。

BuildTrigger

Object

表示布尔定义的触发器。

名称	类型	说明
triggerType	DefinitionTriggerType	触发器的类型。

ControllerStatus

枚举

控制器的状态。

值	说明
available	指示生成控制器当前可用。
offline	指示生成控制器已脱机。
unavailable	指示无法联系生成控制器。

DataSourceBindingBase

Object

表示服务终结点请求的数据源绑定。

名称	类型	说明
callbackContextTemplate	string	此数据源支持的分页格式（ContinuationToken/SkipTop）。
callbackRequiredTemplate	string	需要后续调用？
dataSourceName	string	获取或设置数据源的名称。
endpointId	string	获取或设置终结点 ID。
endpointUrl	string	获取或设置服务终结点的 URL。
headers	AuthorizationHeader[]	获取或设置授权标头。
initialContextTemplate	string	定义查询参数的初始值
parameters	object	获取或设置数据源的参数。
requestContent	string	获取或设置 http 请求正文
requestVerb	string	获取或设置 http 请求谓词
resultSelector	string	获取或设置结果选择器。
resultTemplate	string	获取或设置结果模板。
target	string	获取或设置数据源的目标。

DefinitionQuality

枚举

定义文档的质量（草稿等）

值	说明
definition
draft

DefinitionQueueStatus

枚举

一个值，该值指示是否可以针对此定义排队生成。

值	说明
disabled	禁用后，定义队列将不允许用户对生成进行排队，并且系统不会对计划的、封闭的或持续集成生成进行排队。 系统不会启动队列中的生成。
enabled	启用定义队列后，生成可由用户排队，系统将对计划生成、封闭和持续集成生成进行排队，排队生成将由系统启动。
paused	暂停时，定义队列允许用户对生成进行排队，系统将按计划、封闭和持续集成生成进行排队。 队列中的生成不会由系统启动。

DefinitionReference

Object

表示对定义的引用。

名称	类型	说明
createdDate	string (date-time)	创建此版本的定义日期。
id	integer (int32)	所引用定义的 ID。
name	string	引用的定义的名称。
path	string	定义的文件夹路径。
project	TeamProjectReference	对项目的引用。
queueStatus	DefinitionQueueStatus	一个值，该值指示是否可以针对此定义排队生成。
revision	integer (int32)	定义修订号。
type	DefinitionType	定义的类型。
uri	string	定义的 URI。
url	string	定义的 REST URL。

DefinitionTriggerType

枚举

触发器的类型。

值	说明
all	所有类型。
batchedContinuousIntegration	应按指定的时间间隔为多个更改集启动生成。
batchedGatedCheckIn	应为每个批签入启动验证生成。
buildCompletion	当另一个生成完成时，应触发生成。
continuousIntegration	应为每个更改集启动生成。
gatedCheckIn	应为每个签入启动验证生成。
none	仅手动生成。
pullRequest	创建或更新 GitHub 拉取请求时，应触发生成。 在资源版本 3 中添加
schedule	无论更改集是否存在，都应按指定的计划启动生成。

DefinitionType

枚举

定义的类型。

值	说明
build
xaml

Demand

Object

表示定义或生成使用的需求。

名称	类型	说明
name	string	需求引用的功能的名称。
value	string	所需的值。

IdentityRef

Object

名称	类型	说明
_links	ReferenceLinks	此字段包含有关图形主题的零个或多个有趣的链接。 可以调用这些链接以获取有关此图形主题的其他关系或更详细的信息。
descriptor	string	描述符是在系统运行时引用图形主题的主要方法。 此字段将唯一标识帐户和组织中的同一图形主题。
directoryAlias	string	已弃用 - 可以通过查询 IdentityRef“_links”字典的“self”条目中引用的 Graph 用户来检索
displayName	string	这是图形主题的非唯一显示名称。 若要更改此字段，必须在源提供程序中更改其值。
id	string
imageUrl	string	已弃用 - 在 IdentityRef“_links”字典的“虚拟形象”条目中可用
inactive	boolean	已弃用 - 可以通过查询 GraphUser“_links”字典的“membershipState”条目中引用的 Graph 成员身份状态来检索
isAadIdentity	boolean	已弃用 - 可以从描述符的主题类型推断（Descriptor.IsAadUserType/Descriptor.IsAadGroupType）
isContainer	boolean	已弃用 - 可以从描述符的主题类型推断（描述符.IsGroupType）
isDeletedInOrigin	boolean
profileUrl	string	已弃用 - 不在 ToIdentityRef 的大多数预先存在的实现中使用
uniqueName	string	已弃用 - 请改用 Domain+PrincipalName
url	string	此 URL 是指向此图形主题的源资源的完整路由。

ProcessParameters

Object

名称	类型	说明
dataSourceBindings	DataSourceBindingBase[]	表示服务终结点请求的数据源绑定。
inputs	TaskInputDefinitionBase[]
sourceDefinitions	TaskSourceDefinitionBase[]

ProjectState

枚举

项目状态。

值	说明
all	所有项目，无论状态如何，都已删除。
createPending	项目已排队创建，但该过程尚未启动。
deleted	项目已被删除。
deleting	项目正在删除。
new	正在创建项目。
unchanged	项目尚未更改。
wellFormed	项目已完全创建并可供使用。

ProjectVisibility

枚举

项目可见性。

值	说明
private	只有具有显式访问权限的用户才能看到该项目。
public	项目对所有人可见。

PropertiesCollection

Object

类将属性包表示为键值对的集合。 接受除 TypeCode != TypeCode.Object 以外的所有基元类型（具有 DBNull的任何类型）的值。 Byte[]、Int32、Double、DateType 和 String 类型的值将保留其类型，其他基元将重新调整为 String。 Byte[] 应为 base64 编码字符串。

名称	类型	说明
count	integer (int32)	集合中的属性计数。
item	object
keys	string[]	集合中的键集。
values	string[]	集合中的值集。

QueueOptions

枚举

用于对生成进行排队的其他选项。

值	说明
doNotRun	为生成创建计划 ID，不要运行它
none	无队列选项

QueuePriority

枚举

生成优先级。

值	说明
aboveNormal	高于正常优先级。
belowNormal	低于正常优先级。
high	高优先级。
low	低优先级。
normal	正常优先级。

ReferenceLinks

Object

表示 REST 引用链接集合的类。

名称	类型	说明
links	object	链接的只读视图。 由于引用链接是只读的，因此我们只想将其公开为只读链接。

RetentionPolicy

Object

表示生成定义的保留策略。

名称	类型	说明
artifactTypesToDelete	string[]
artifacts	string[]
branches	string[]
daysToKeep	integer (int32)	要保留生成的天数。
deleteBuildRecord	boolean	指示是否应删除生成记录本身。
deleteTestResults	boolean	指示是否删除与生成关联的测试结果。
minimumToKeep	integer (int32)	要保留的最小内部版本号。

TaskAgentPoolReference

Object

表示对代理池的引用。

名称	类型	说明
id	integer (int32)	池 ID。
isHosted	boolean	一个值，该值指示此池是否由服务管理。
name	string	池名称。

TaskInputDefinitionBase

Object

名称	类型	说明
aliases	string[]
defaultValue	string
groupName	string
helpMarkDown	string
label	string
name	string
options	object
properties	object
required	boolean
type	string
validation	TaskInputValidation
visibleRule	string

TaskInputValidation

Object

名称	类型	说明
expression	string	条件表达式
message	string	说明验证失败时用户如何更正的消息

TaskOrchestrationPlanReference

Object

表示对业务流程计划的引用。

名称	类型	说明
orchestrationType	integer (int32)	计划的类型。
planId	string (uuid)	计划的 ID。

TaskSourceDefinitionBase

Object

名称	类型	说明
authKey	string
endpoint	string
keySelector	string
selector	string
target	string

TeamProjectReference

Object

表示对 TeamProject 的浅表引用。

名称	类型	说明
abbreviation	string	项目缩写。
defaultTeamImageUrl	string	指向默认团队标识映像的 URL。
description	string	项目的说明（如果有）。
id	string (uuid)	项目标识符。
lastUpdateTime	string (date-time)	上次更新时间的项目。
name	string	项目名称。
revision	integer (int64)	项目修订。
state	ProjectState	项目状态。
url	string	指向对象完整版本的 URL。
visibility	ProjectVisibility	项目可见性。

ValidationResult

枚举

结果。

值	说明
error
ok
warning

VariableGroup

Object

表示变量组。

名称	类型	说明
alias	string	变量组的名称。
description	string	说明。
id	integer (int32)	变量组的 ID。
name	string	变量组的名称。
type	string	变量组的类型。
variables	<string,  BuildDefinitionVariable>