Builds - Queue

服務:

Build

API 版本:

7.1

將組建排入佇列

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

含選擇性參數:

POST https://dev.azure.com/{organization}/{project}/_apis/build/builds?ignoreWarnings={ignoreWarnings}&checkInTicket={checkInTicket}&sourceBuildId={sourceBuildId}&definitionId={definitionId}&api-version=7.1

URI 參數

名稱	位於	必要	類型	Description
organization	path	True	string	Azure DevOps 組織的名稱。
project	path	True	string	項目識別碼或項目名稱
api-version	query	True	string	要使用的 API 版本。 這應該設定為 『7.1』 以使用此版本的 API。
checkInTicket	query		string
definitionId	query		integer (int32)	選擇性定義標識碼，以將組建排入佇列，而不需要本文。 如果有有效的主體，則會忽略
ignoreWarnings	query		boolean
sourceBuildId	query		integer (int32)

要求本文

名稱	類型	Description
_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)	組建的標識碼。
lastChangedBy	IdentityRef	表示上次變更組建之進程或人員的身分識別。
lastChangedDate	string (date-time)	上次變更組建的日期。
logs	BuildLogReference	組建記錄的相關信息。
orchestrationPlan	TaskOrchestrationPlanReference	組建的協調流程計劃。
parameters	string	組建的參數。
plans	TaskOrchestrationPlanReference[]	與組建相關聯的協調流程計劃（組建、清除）
priority	QueuePriority	組建的優先順序。
project	TeamProjectReference	Team 專案。
properties	PropertiesCollection	類別會將屬性包表示為索引鍵/值組的集合。 接受 DBNull 以外的所有基本類型值（任何具有 TypeCode != TypeCode.Object的類型）。 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-specific information about what triggered the build
triggeredByBuild	Build	透過建置完成觸發程式觸發此組建的組建。
uri	string	組建的 URI。
url	string	組建的 REST URL。
validationResults	BuildRequestValidationResult[]	表示驗證組建要求的結果。

回應

名稱	類型	Description
200 OK	Build	成功作業

安全性

oauth2

類型: oauth2
Flow: 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

範圍

名稱	Description
vso.build_execute	授與存取組建成品的能力，包括建置結果、定義和要求，以及能夠將組建排入佇列、更新組建屬性，以及透過服務攔截接收建置事件的相關通知的能力。

定義

名稱	Description
AgentPoolQueue	表示執行組建的佇列。
AgentSpecification	集區提供者所定義的代理程序規格。
Build	組建的數據表示。
BuildController
BuildLogReference	表示組建記錄檔的參考。
BuildReason	建立組建的原因。
BuildRepository	表示組建定義所使用的存放庫。
BuildRequestValidationResult	表示驗證組建要求的結果。
BuildResult	建置結果。
BuildStatus	組建狀態。
ControllerStatus	控制器的狀態。
DefinitionQueueStatus	值，指出是否可以針對這個定義將組建排入佇列。
DefinitionReference	表示定義的參考。
DefinitionType	定義的型別。
Demand	表示定義或組建所使用的需求。
IdentityRef
ProjectState	項目狀態。
ProjectVisibility	項目可見度。
PropertiesCollection	類別會將屬性包表示為索引鍵/值組的集合。 接受 DBNull 以外的所有基本類型值（任何具有 TypeCode != TypeCode.Object的類型）。 Byte[]、Int32、Double、DateType 和 String 類型的值會保留其類型，其他基本類型會重新調整為 String。 Byte[] 預期為base64編碼字串。
QueueOptions	佇列組建的其他選項。
QueuePriority	組建的優先順序。
ReferenceLinks	表示 REST 參考連結集合的類別。
TaskAgentPoolReference	表示代理程式集區的參考。
TaskOrchestrationPlanReference	表示協調流程計劃的參考。
TeamProjectReference	表示 TeamProject 的淺層參考。
ValidationResult	結果。

AgentPoolQueue

Object

表示執行組建的佇列。

名稱	類型	Description
_links	ReferenceLinks	表示 REST 參考連結集合的類別。
id	integer (int32)	佇列的標識碼。
name	string	佇列的名稱。
pool	TaskAgentPoolReference	這個佇列所使用的集區。
url	string	資源的完整 HTTP 連結。

AgentSpecification

Object

集區提供者所定義的代理程序規格。

名稱	類型	Description
identifier	string	代理程式規格唯一標識碼。

Build

Object

組建的數據表示。

名稱	類型	Description
_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)	組建的標識碼。
lastChangedBy	IdentityRef	表示上次變更組建之進程或人員的身分識別。
lastChangedDate	string (date-time)	上次變更組建的日期。
logs	BuildLogReference	組建記錄的相關信息。
orchestrationPlan	TaskOrchestrationPlanReference	組建的協調流程計劃。
parameters	string	組建的參數。
plans	TaskOrchestrationPlanReference[]	與組建相關聯的協調流程計劃（組建、清除）
priority	QueuePriority	組建的優先順序。
project	TeamProjectReference	Team 專案。
properties	PropertiesCollection	類別會將屬性包表示為索引鍵/值組的集合。 接受 DBNull 以外的所有基本類型值（任何具有 TypeCode != TypeCode.Object的類型）。 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-specific information about what triggered the build
triggeredByBuild	Build	透過建置完成觸發程式觸發此組建的組建。
uri	string	組建的 URI。
url	string	組建的 REST URL。
validationResults	BuildRequestValidationResult[]	表示驗證組建要求的結果。

BuildController

Object

名稱	類型	Description
_links	ReferenceLinks	表示 REST 參考連結集合的類別。
createdDate	string (date-time)	建立控制器的日期。
description	string	控制器的描述。
enabled	boolean	指出是否啟用控制器。
id	integer (int32)	資源的標識碼
name	string	連結資源名稱（定義名稱、控制器名稱等）
status	ControllerStatus	控制器的狀態。
updatedDate	string (date-time)	控制器上次更新的日期。
uri	string	控制器的 URI。
url	string	資源的完整 HTTP 連結

BuildLogReference

Object

表示組建記錄檔的參考。

名稱	類型	Description
id	integer (int32)	記錄檔的標識碼。
type	string	記錄位置的類型。
url	string	記錄資源的完整連結。

BuildReason

列舉型別

建立組建的原因。

值	Description
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

表示組建定義所使用的存放庫。

名稱	類型	Description
checkoutSubmodules	boolean	指出是否簽出子模組。
clean	string	指出從存放庫取得程式碼時，是否要清除目標資料夾。
defaultBranch	string	默認分支的名稱。
id	string	存放庫的標識碼。
name	string	存放庫的易記名稱。
properties	object
rootFolder	string	根資料夾。
type	string	存放庫的類型。
url	string	存放庫的 URL。

BuildRequestValidationResult

Object

表示驗證組建要求的結果。

名稱	類型	Description
message	string	與結果相關聯的訊息。
result	ValidationResult	結果。

BuildResult

列舉型別

建置結果。

值	Description
canceled	組建在啟動之前已取消。
failed	建置未成功。
none	沒有結果
partiallySucceeded	建置順利完成編譯，但發生其他錯誤。
succeeded	建置已順利完成。

BuildStatus

列舉型別

組建狀態。

值	Description
all	所有狀態。
cancelling	組建正在取消
completed	組建已完成。
inProgress	組建目前正在進行中。
none	沒有狀態。
notStarted	組建尚未啟動。
postponed	組建在佇列中處於非作用中狀態。

ControllerStatus

列舉型別

控制器的狀態。

值	Description
available	表示組建控制器目前可供使用。
offline	表示組建控制器已離線。
unavailable	表示無法連絡組建控制器。

DefinitionQueueStatus

列舉型別

值，指出是否可以針對這個定義將組建排入佇列。

值	Description
disabled	停用時，定義佇列不允許使用者將組建排入佇列，而且系統將不會排入排程、閘道或持續整合組建的佇列。 系統將不會啟動佇列中的組建。
enabled	啟用定義佇列可讓使用者將組建排入佇列時，系統會將排程、閘道和持續整合組建排入佇列，而佇列組建將由系統啟動。
paused	暫停時，定義佇列可讓用戶將組建排入佇列，系統將會排入排程、閘道和持續整合組建的佇列。 佇列中的組建將不會由系統啟動。

DefinitionReference

Object

表示定義的參考。

名稱	類型	Description
createdDate	string (date-time)	建立此定義版本的日期。
id	integer (int32)	參考定義的識別碼。
name	string	參考定義的名稱。
path	string	定義的資料夾路徑。
project	TeamProjectReference	項目的參考。
queueStatus	DefinitionQueueStatus	值，指出是否可以針對這個定義將組建排入佇列。
revision	integer (int32)	定義修訂編號。
type	DefinitionType	定義的型別。
uri	string	定義的 URI。
url	string	定義的 REST URL。

DefinitionType

列舉型別

定義的型別。

值	Description
build
xaml

Demand

Object

表示定義或組建所使用的需求。

名稱	類型	Description
name	string	需求所參考的功能名稱。
value	string	要求的 值。

IdentityRef

Object

名稱	類型	Description
_links	ReferenceLinks	此欄位包含圖表主旨的相關零或更多有趣連結。 您可以叫用這些連結，以取得此圖表主題的其他關聯性或更詳細的資訊。
descriptor	string	描述元是在系統執行時參考圖表主旨的主要方式。 此欄位會唯一識別帳戶和組織之間的相同圖表主題。
directoryAlias	string	已淘汰 - 查詢 IdentityRef “_links” 字典中參考的 Graph 使用者，即可擷取
displayName	string	這是圖形主體的非唯一顯示名稱。 若要變更此欄位，您必須在來源提供者中變更其值。
id	string
imageUrl	string	已淘汰 - 可在 IdentityRef “_links” 字典的 “avatar” 專案中取得
inactive	boolean	已淘汰 - 可藉由查詢 GraphUser “_links” 字典的 “membershipState” 專案中參考的 Graph 成員資格狀態來擷取
isAadIdentity	boolean	已淘汰 - 可以從描述元的主體類型推斷 （Descriptor.IsAadUserType/Descriptor.IsAadGroupType）
isContainer	boolean	已淘汰 - 可以從描述元的主體類型推斷 （Descriptor.IsGroupType）
isDeletedInOrigin	boolean
profileUrl	string	已淘汰 - 未在 ToIdentityRef 的大部分預先存在實作中使用
uniqueName	string	已淘汰 - 請改用 Domain+PrincipalName
url	string	此 URL 是此圖表主體來源資源的完整路由。

ProjectState

列舉型別

項目狀態。

值	Description
all	所有專案，不論狀態為何，但已刪除除外。
createPending	Project 已排入佇列以建立，但程式尚未啟動。
deleted	項目已刪除。
deleting	Project 正在刪除。
new	Project 正在建立中。
unchanged	專案尚未變更。
wellFormed	專案已完全建立並可供使用。

ProjectVisibility

列舉型別

項目可見度。

值	Description
private	只有具有明確存取權的使用者才能看到專案。
public	所有專案都可以看到。

PropertiesCollection

Object

類別會將屬性包表示為索引鍵/值組的集合。 接受 DBNull 以外的所有基本類型值（任何具有 TypeCode != TypeCode.Object的類型）。 Byte[]、Int32、Double、DateType 和 String 類型的值會保留其類型，其他基本類型會重新調整為 String。 Byte[] 預期為base64編碼字串。

名稱	類型	Description
count	integer (int32)	集合中的屬性計數。
item	object
keys	string[]	集合中的索引鍵集合。
values	string[]	集合中的值集合。

QueueOptions

列舉型別

佇列組建的其他選項。

值	Description
doNotRun	建立組建的方案識別碼，請勿執行
none	沒有佇列選項

QueuePriority

列舉型別

組建的優先順序。

值	Description
aboveNormal	高於一般優先順序。
belowNormal	低於一般優先順序。
high	高優先順序。
low	低優先順序。
normal	一般優先順序。

ReferenceLinks

Object

表示 REST 參考連結集合的類別。

名稱	類型	Description
links	object	連結的只讀檢視。 因為參考連結是只讀的，所以我們只想要將其公開為只讀。

TaskAgentPoolReference

Object

表示代理程式集區的參考。

名稱	類型	Description
id	integer (int32)	集區標識碼。
isHosted	boolean	值，指出此集區是否由服務管理。
name	string	集區名稱。

TaskOrchestrationPlanReference

Object

表示協調流程計劃的參考。

名稱	類型	Description
orchestrationType	integer (int32)	計劃的型別。
planId	string (uuid)	方案的標識碼。

TeamProjectReference

Object

表示 TeamProject 的淺層參考。

名稱	類型	Description
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

列舉型別

結果。

值	Description
error
ok
warning