概述

Teamcity提供REST API目的：整合外部应用，与TeamCity server建立脚本化交互。REST API可以使用URL路径访问资源。为了使用REST API，需要一个外部应用向TeamCity server发出HTTP请求，然后解析响应。

常见使用原则

1）http://<TeamCity Server host>:<port>/app/rest/server #给出一些可以访问的对象。这很重要，给出了可以访问的对象。！！！！
例如：
http://10.10.10.10:8001/app/rest/server 2）http://<TeamCity Server host>:<port>/app/rest/agents #获取所有的授权agent的列表
3）http://<TeamCity Server host>:<port>/app/rest/agents/id:100 #获取id为100的agent的信息
4)http://<TeamCity Server host>:<port>/app/rest/agents/$help #获取哪些可以定位特定agent的属性有哪些！！！！
#注意：$help前的对象需要是复数形式。如 http://<TeamCity Server host>:<port>/app/rest/buildQueue/$help访问失败。此时用aa:bb代替$help即可。
5)上述4）返回的大多属性可以用于<field_name>。即支持下面这种请求格式：
http://<TeamCity Server host>:<port>/app/rest/agents/<agentLocator>/<field_name>

认证方式

这里以powershell中Invoke-RestMetho 访问rest api为例。
1.推荐的认证方式是：token-based HTTP authentication
$apiKey = “aaa0eczczc1emVEMkNjUGdffdfddddd9r.ODljN2UyNjktNDA1Mi00OGQzLTg3NDEtOWYwYzhmNjliYTY5”
$headers = @{}
$headers.Add(“Authorization”,“Bearer $apiKey”)
Invoke-RestMethod -Headers $headers -Uri “http://:/app/rest/agents”
其中$apiKey的在Teamcity UI的生成方式:My Settings & Tools | Access Tokens
2.用户名，密码认证(基本的http认证，慢)
$currentUser = “xxx”
$currentPassword = “xxxx”
$pass = ConvertTo-SecureString -AsPlainText $currentPassword -Force
$Cred = New-Object System.Management.Automation.PSCredential -ArgumentList currentUser,currentUser,currentUser,pass
Invoke-RestMethod -Credential $Cred -Uri "http://<TeamCity Server host>:<port>/httpAuth/app/rest/buildTypes

常见对象和常见定位器

url	定位器	说明
http://<TeamCity Server host>:<port>/app/rest/projects	id, internalId, uuid, project, affectedProject, name, archived, build, buildType, defaultTemplate, vcsRoot, projectFeature, pool, $singleValue, start, count
http://<TeamCity Server host>:<port>/app/rest/builds	id, taskId, project, affectedProject, buildType, branch, agent, agentName, agentTypeId, user, personal, state, tag, property, compatibleAgent, number, status, canceled, pinned, queuedDate, startDate, finishDate, sinceBuild, sinceDate, untilBuild, untilDate, failedToStart, snapshotDependency, artifactDependency, hanging, composite, history, defaultFilter, $singleValue, start, count, lookupLimit]
http://<TeamCity Server host>:<port>/app/rest/buildQueue	id, taskId, project, buildType, agent, user, personal, $singleValue, star
http://<TeamCity Server host>:<port>/app/rest/agents	id, name, connected, authorized, enabled, parameter, ip, pool, build, compatible, $singleValue, start, count
http://<TeamCity Server host>:<port>/app/rest/users	id,username,group,affectedGroup,property,email,name,lastLogin,role	id是内部用户id，数字类型；property 是用户的属性，值是参数条件
http://<TeamCity Server host>:<port>/app/rest/userGroups
http://<TeamCity Server host>:<port>/app/rest/agentPools
http://<TeamCity Server host>:<port>/app/rest/investigations
http://<TeamCity Server host>:<port>/app/rest/mutes
http://<TeamCity Server host>:<port>/app/rest/vcs-roots

2.不同类型的定位器
完整定位器

ProjectLocator

属性名	值类型	说明和实例
name	project name	找到特定名字的project
affectedProject	ProjectLocator	值是上层的项目名。值的类型是ProjectLocator，是一种递归定义。用来找子项目。如http://<TeamCity Server host>:<port>/app/rest/projects?locator=affectedProject:(name:aa),会搜索aa的子项目
Project	ProjectLocator	值是父项目的名字，用来找子项目
build	BuildLocator	build定位器
buildType	buildTypeLocator	build type定位器
count	整数	对于分页调用，指明每页返回多少个实体(entity)
item	item:(<locator1>),item:(<locator2>…)	提供多个定位器，返回一组结果
projectFeature	ProjectLocator	项目特征定位器
start	整数	对于分页调用，从那个实体开始呈现页面

BuildTypeLocator

和 ProjectLocator共有的属性:affectedProject,project,build,count,item,start

属性名	值类型	说明和实例
name	string	值是目标build的类型的名字,如http://<TeamCity Server host>:<port>/app/rest/buildTypes/name:aa/triggers,获取aa这个build的触发器
paused	布尔类型	值是true，false

BuildLocator

和 ProjectLocator共有的属性:affectedProject,project,buildType,count,item

属性名	值类型	说明和实例
agent	AgentLocator	值是agent定位器
any	布尔类型	描述State
canceled	布尔类型	build被取消
compatibleAgent	AgentLocator	值是agent定位器
defaultFilter	布尔类型	值为true时，只返回通常的build(已经完成的，且未被取消，不是没开始的，不是个人的，在默认分支上的)
failedToStart	布尔类型	没能开始而失败的的build
finishDate	string	date:<yyyyMMddTHHmmss+ZZZZ>,build:<build locator>,condition:<before/after>
finished	布尔类型	build已经完成
hanging	布尔类型	build悬挂了
history	布尔类型	是历史build
lookupLimit	整数	返回最近的几个结果，值指明返回几个结果。如http://<TeamCity Server host>:<port>/app/rest/buildTypes/name:buildName/builds?locator=lookupLimit:1&fields=build(startDate)，返回最近buildName最近一次build的启动时间。
pinned	布尔类型	is pinned
property	property:(name:<name>,value:<value>,matchType:<matchType>)
queued	布尔类型	true表示在排队
running	布尔类型	true表示运行
startDate	date:<yyyyMMddTHHmmss+ZZZZ>,build:<build locator>,condition:<before/after>	返回日期，或者返回build dimension
queuedDate	同上	同上
state	string	值可以是:queued,running,finished,any
status	string	值可以是FAILURE,SUCESS,UNKNOWN(从未运行过)
tag	TagLocator	标签定位器

URL 结构

http://<TeamCity Server host>:<port>/<authType>/app/rest/<apiVersion>/<restApiPath>?<parameters>说明
<TeamCity Server host>和<port>:通常是TeamCity server机器的ip和服务端口
<authType>：说明认证类型。如httpAuth，guestAuth等等。（可选）
app/rest：是TeamCity REST API的根路径
<apiVersion>：指明REST API的版本(可选)
<span style="color: red;"><restApiPath>?<parameters>：是整个URL中REST API部分。通常，获取获取多个对象使用：.../app/rest/<items>，如.../app/rest/builds,.../app/rest/projects等。
这类URL通常接收定位器参数，定位器用来过滤返回的对象。然而.../app/rest/<items>/<item_locator>这类URL返回的是单独对象。若item_locator匹配了多个对象，会返回第一个。!!!
多个或单个对象的请求通常使用fileds参数。!!!

定位器（通常返回一个对象）

官方文档
定位器有两种格式，但格式都是
属性名：属性值

单属性定位器：不含,:-( )这些字符即可。若此时，属性值含有逗号，需要用圆括号括起来。

例如：…/app/rest/projects获取多个project。而.../app/rest/projects/<projectsLocator>则可以获取对应属性的project。如http://<TeamCity Server host>:<port>/app/rest/projects/name:aaa 获取名字为aaa的project。

多属性定位器：用逗号隔开多个属性。一般格式如下：

<dimension1>:<value1>,<dimension2>:<value2>,<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)#dimension1是属性名，value1是属性值。<dimension2>:<value2>这一组一样。<dimension3>:(<dimension3.1>:<value3.1>,<dimension3.2>:<value3.2>)指明了一个嵌套的属性，要用圆括号括起来。即具有属性dimension3的对象中，又有属性dimension3.1，dimension3.2
注意：如果属性值中有逗号，应该用()包裹起来。

例如：

http://<TeamCity Server host>:<port>/app/rest/buildTypes/id:bt284/<items>?locator=<dimension1>:<value1>,<dimension2>:<value2>
如
http://<TeamCity Server host>:<port>/app/rest/buildTypes/id:bt284/builds?locator=status:SUCCESS,tag:EAP
http://<TeamCity Server host>:<port>/app/rest/builds/?locator=<buildLocator>

支持的HTTP方法

GET:取回数据
POST:创建一个资源
PUT:更新资源
DELETE：删除资源

响应格式

REST API根据HTTP ‘Accept’ header的值，返回的对象格式有：普遍文本(返回单一值)，xml和json，后两者返回的都是复杂值。
HTTP接受的头格式分别为:text/plain,application/xml,application/json

完全响应和部分响应

默认的，请求一列实体时，只有基本字段会被包含在响应中。请求一个单独的入口时，所有字段都会包含在响应中。是返回基本字段还是所有字段，取决于一个特定的实体。
对于返回xml和json格式的情况，通过提供fields请求参数请求参数即可。fields请求参数描述的是top-entity和sub-entity的fields。参数语法示例：

field,field2(field2_subfield1,field2_subfield1)
即：包含top-entity的field和field2，对field，包含了field2_subfield1,field2_subfield1，顺序不重要。
http://teamcity.jetbrains.com/app/rest/buildTypes?locator=affectedProject:(id:TeamCityPluginsByJetBrains)&fields=buildType(id,name,project)http://teamcity.jetbrains.com/app/rest/builds?locator=buildType:(id:bt345),count:10&fields=count,build(number,status,statusText,agent,lastChange,tags,pinned)

日志

rest api请求访问日志(包括错误信息)可以在logs\teamcity-rest.log中看到。
官方说明

TeamCity REST API相关推荐

Teamcity REST API(二)
0.teamcity内置的有用的变量 "%system.teamcity.buildType.id%" "%system.teamcity.projectName%&qu ...
vs 调试无法加载自定义可视化工具_推荐 5 款好用的REST API工具
作者 | Marta Krzyk 首发|架构头条译者 | 王强策划 | 小智市面上可用的 REST API 工具选项有很多,我们来看看其中一些开发人员最喜欢的工具. 1 API 定义 Swagg ...
teamcity mysql 配置_TeamCity : Build 基本配置
前文中我们在 TeamCity 中创建了一个项目 HelloApp,并在这个项目中创建了一个名为 HelloAppDailyBuild 的Build 用来编译 demo 程序.本文我们将详细介绍 Bu ...
C++ API设计笔记
<C++ API设计>原英文版由Martin Reddy著,中文版出版于2013年,这里是中文版的笔记. 1. API简介 1.1 什么是API:API(Application Progr ...
软件测试八款优秀的API安全测试工具，会用三款工作效率能提升50%
Postman Postman完全具备作为API测试工具的资格,但其更为人所知的名号却是打造安全API的全套协作平台.数百万Windows.Linux和iOS开发人员使用Postman不是没有原因的. ...
分享几款超好用的 REST API 工具
大家好,我是辰哥市面上可用的 REST API 工具选项有很多,我们来看看开发人员最喜欢的一些工具. 1API 定义 Swagger Editor 是图形可视化的流行选项.你可以使用 JSON 或 ...
十分钟熟知Gitlab API
https://www.jianshu.com/p/ab377b7a156f?from=groupmessage 前言 Gitlab作为一个开源.强大的分布式版本控制系统,已经成为互联网公司.软件开发 ...
TeamCity的安装(docker) 构建和部署 (1)
目录前言安装teamCity 配置安装docker镜像初始化安装teamAgent 官方docker方式安装我的agent docker镜像 agent的配置文件配置构建和使用创建构建项 ...
TeamCity+Gradle实现自动构建App安装包和补丁包
相信大家在用AS打包的时候,最烦的就是打包要很久,如果可以自动化打包岂不是很方便,所以我之前也是被安排做了这个任务.利用TeamCity+Gradle去实现自动构建App安装包和补丁包,这里做个记录. ...

TeamCity REST API

文章目录

概述