API参考

Circleci API可用于使API调用检索有关用户，作业，工作流和管道的详细信息。目前有两个支持的API版本：

API v2包括API v1.1中没有的一些强大特性(例如对管道和管道参数的支持)。我们建议CircleCI云用户尽快将他们的脚本迁移到API v2稳定端点。

CIRCLECI API V1.1和API V2的部分都得到支持，通常可用。Circleci期望最终的生活结束（EOL）API V1.1支持API V2，因为更多API v2端点被宣布为稳定。当Circleci API V1.1将停止时，将在将来的日期传送进一步的指导。

API V2简介

CircleCI API v2允许您使用具有几个新特性的端点，这些新特性除了优化您在工作中使用API的方式外，还可以改善API体验。API v2目前正在积极开发中，因此，该API的稳定性被称为“混合”。

API v2端点的当前类别为:

身份验证
管道
工作流程
用户
项目
工作(预览)
的见解

注意：CircleCI API v2的一部分仍然处于“预览”状态。预览端点还没有得到完全支持，或者被认为是普遍可用的。对API v2预览端点的破坏更改是事先计划好的，并在API v2中断变更日志。

开始使用API v2

CircleCI API v2与以前的API版本向后兼容，它使用存储库名称标识您的项目。例如，如果您想从CircleCI获取关于GitHub存储库的信息https://github.com/CircleCI-Public/circleci-cli，您可以在CircleCI API中引用该信息为gh / circleci-public / circleci-cli，这是项目类型的“三重态”，“组织”的名称以及存储库的名称。对于您可以使用的项目类型GitHub.或Bitbucket.以及较短的形式“大酒店”或BB.，现在API v2支持它们。该组织是您的版本控制系统中的用户名或组织名称。

使用API v2，Circleci正在引入一个称为Triplet的字符串表示project_slug.，这采取以下形式：

/ /

该project_slug.当提取有关项目的信息以及通过ID查找管道或工作流时，在有效负载中包含project_slug.然后可以用来获取有关项目的信息。未来是可能的一种形状project_slug.可能会改变，但在所有情况下，它都可以作为给定项目的人类可读标识符使用。

身份验证

CircleCI API v2允许用户通过发送API令牌作为HTTP请求的用户名进行身份验证。例如，如果你已经设置circleci_token.在你的贝壳的环境中，你可以使用卷曲有了这个标记，如下所示:

curl -u $ {circleci_token}：//www.drag240sx.com/api/v2/me

注意，这：包含，表示没有密码。注意那项目令牌API v2目前不支持。

使用参数示例触发管道

下面是一个简单的例子卷曲要触发带参数的管道：

        curl -u $ {circleci_token}：-x post  -  header“content-type：application / json”-d'{“参数”：{“myparam”：“./myspecialdir”，“myspecialversion”：“4.8.2“}}'//www.drag240sx.com/api/v2/project/ {project_slug }/pipeline
       

在上面的例子中project_slug.会采取表格:风投/:org/:项目。例如，项目蛞蝓(slug)gh / circleci-public / circleci-cli讲CircleCI使用GitHub组织circlech - public中命名的库中的项目circleci-cli。

重要的管道参数不被视为敏感数据和不得用于敏感值(机密值)。中可以找到有关正确使用敏感数据的信息项目设置和上下文指南。

端点的变化

circleci api v2版本包括几个新终点，并弃用了其他一些。除了已删除的端点之外，以下部分列出了为此发布添加的端点。

有关所有API V2端点的完整列表，请参阅API v2参考指南，其中包含每个端点的详细描述，以及关于必需和可选参数、HTTP状态和错误代码的信息，以及您可能在工作流程中使用的代码示例。

新的端点

下表描述了为这个更新的v2版本添加到CircleCI API的新端点。

终点	描述
`得到/工作流/:id`	此端点使用户可以根据。返回单个工作流`id`参数正在请求中传递
`得到/工作流/:id /工作`	此indoint使用户能够根据其唯一检索与特定工作流关联的所有作业`id`。
`GET /项目/:project_slug`	这个端点使用户能够检索一个特定的项目由其独特的蛞蝓。
`POST /项目/:project_slug /管道`	此端点使用户能够通过其独特的SLUG检索单个项目。
`获取/ pipeline /：ID`	此端点使用户可以根据。检索单个管道`id`传入请求。
`得到/管道/:id /配置`	此端点使用户能够检索特定管道的配置。
`get / project /：project_slug / pipelines / [：filter]`	此端点使用户能够检索项目的最新管道集。
`获得/见解:project-slug /工作流`	此端点使您能够检索单个项目工作流的摘要指标。
`得到/见解:project-slug /工作流/:workflow-name`	此端点使您可以检索最近的工作流程运行。
`GET / INSIGHTS /：Project-SLUG / WORKFLOWS /：工作流名/作业`	此端点使您能够检索项目工作流作业的摘要指标。
`GET / INSIGHTS /：Project-SLUC / WORKFLOWS /：工作流名/作业/：作业名称`	此端点使您能够检索工作流中作业的最近运行情况。

弃用端点

对于这个更新的API v2版本，有几个端点已经不推荐使用，它们列在下表中。

终点	描述
`POST /项目/:vcs-type /:用户名/:项目`	此端点允许用户触发新的构建。
`POST /项目/:vcs-type /:用户名/:/构建项目`	此端点使用户能够通过项目触发新构建。
`删除/项目/:vcs-type /用户名/:项目/构建缓存`	此端点使用户能够为特定项目清除项目缓存。
`获得/最近建立`	此端点使用户能够检索最近构建的数组。

API V2和服务器客户

对于CircleCI服务器的自托管安装，目前不支持API v2。

数据的见解

Circleci API V2使您可以调用特定的端点以检索有关作业和工作流程的详细洞察和数据。这些信息可以非常有用，更有用，更好地了解您的作业和工作流程，同时还为您提供可以使用的数据点来优化工作流程和构建。详述API参考指南因为文档中提供了这些API端点。一些insight端点的例子包括:

GET / {vcs_slug} / {org_name} /项目/ {project_name}
GET / {vcs_slug} / {org_name} /项目/ {project_name} /工作流
get / {vcs_slug} / {org_name} / projects / {project_name} / workflows / {workflow_name} /作业