今天,我们正在宣布我们的API的v2,该v2开启了九个新的稳定终点,允许控制pipelinesandworkflows。V2 API已在预览版本中持续数月,我们将继续添加新的终点,包括今天可用的一些较长的预览一段时间。

在此帖子中,我将概述现在稳定的V2 API中的第一个端点,以便您的生产使用稳定。

Pipelines are now first-class in the API

2019年3月,我们宣布简单的名称更改of “build processing” to “pipelines” and told you it would be a while before you had to think about pipelines again. Since then many of you have seen pipelines appear in the preview releases of the v2 API and in our new UI preview. With the v2 API we expand pipelines to give you programmatic access to triggering and retrieving them.

管道封装了你在Circleci上运行的东西。当您将管道带有提交的PIT存储库或针对项目的API调用时,该管道代表您在Circleci内部的请求的开始,并持续稳定的流水线ID以及有关触发器原因的信息,我们将归因于管道运行的演员,以及用于在管道中运行工作流的配置。

管道是Circleci要求的工作单位。每个都在给定的项目上触发,给定分支(您的默认分支应用为默认值),由特定配置(或通过我们历史的Github集成的特定配置(或通过暗示的方式检索配置的方法)。

如果您在2018年9月后添加了您的项目,则您一直在使用管道,并且可能没有意识到它。

“project_slug”

circleci v2 api使用对应于其上游存储库的项目的标识符。例如,如果要从Circleci提取关于GitHub存储库的信息https://github.com/circleci-公开/circleci-cli., you can refer to that in the CircleCI API asgh / circleci-public / circleci-cli, which is a “triplet” of the project type, the name of your “organization”, and the name of the repository. For the project type you can usegithuborbitbucketas well as the shorter formsghorBB.,现在在API v2中支持的。该组织是您的版本控制系统中的用户名或组织名称。

使用API​​ v2,我们正在引入一个称为project_slug的三联网字符串表示,它采用表单://。Project_slug当项目中拉动有关项目的信息以及按ID查找管道或工作流程时,包含在有效载荷中。然后可以使用project_slug来获取有关项目的信息。将来可能会改变Project_slug的形状,但在所有情况下,它可以作为给定项目的人类可读标识符。

Pipeline parameters

V2 API现在允许您将参数添加到管道触发器。

用您传递的参数触发管道parameterskey in the JSON packet in your POST body. For the above config this might look something like:

curl -u ${CIRCLECI_TOKEN}: -X POST --header "Content-Type: application/json" -d '{ "parameters": { "workingdir": "./myspecialdir", "image-tag": "4.8.2" } }' //www.drag240sx.com/api/v2/project/:project_slug/pipeline

与V1.1作业触发端点中的参数不同,该端点将直接注入运行作业环境,管道参数在配置处理期间解析,使它们可用于配置的大多数部分。

使用a声明管道参数parametersStanza在你的顶级钥匙.circleci / config.yml.文件。然后,您将参考范围中参数的值引用管道.Parameters.

示例Belows显示具有两个管道参数的配置,图像标签and练习犯both used on the subsequent config stanzas:

version: 2.1 parameters: image-tag: type: enum default: "latest" enum: ["latest","bleeding","stable201911"] # NOTE use of enum allows only the options you want # You could, instead, choose to make it an arbitrary string workingdir: type: string default: "main-app" jobs: build: docker: - image: circleci/node:<< pipeline.parameters.image-tag >> environment: IMAGETAG: << pipeline.parameters.image-tag >> working_directory: /Code/<< pipeline.parameters.workingdir >> steps: - run: echo "Image tag used was ${IMAGETAG}" - run: echo "$(pwd) == << pipeline.parameters.workingdir >>"

请记住,如果声明管道参数,任何具有触发凭证的人(例如,与凭借在上游repo上的提交权限上具有触发权限的用户绑定的API令牌)将能够有效地注入该值进入您的配置。在上面的示例中,如果您不想允许注入Docker标签,您将不想使用此技术。

使用管道参数的条件工作流程

We added a new什么时候clause (we also support the inverse clauseunless)在具有布尔值的工作流程声明下,以确定是否运行该工作流程。

此构造的最常见使用是使用管道参数作为值,允许API触发通过该参数来确定要运行的工作流程。

Below is an example configuration using two different pipeline parameters, one used to drive whether a particular workflow will run and another to determine if a particular step will run.

版本:2.1参数:run_integration_tests:type:boolean default:false deploy:type:boolean default:false工作流程:版本:2集成_tests:何时:<< pipeline.parameters.run_integration_tests >>作业: -  mytestjob作业:mytestjob:步骤: -结账 - 当条件:<< pipeline.parameters.doploy >>步骤: - 运行:echo“部署”

九个新终点

今天的V2公告中的星星是Circleci API V2(管道和工作流程)中第一组端点的稳定性和一般可用性。

以下管道端点分别让您,

  • 在项目分支上触发管道,并收到其ID供以后使用
  • Retrieve the latest pipelines on a given project
  • 过滤返回最近由请求者运行的管道
POST /project/{project-slug}/pipeline GET /project/{project-slug}/pipeline GET /project/{project-slug}/pipeline/mine

You can also

  • 通过其ID检索单个管道
  • Retrieve a pipeline’s workflows
  • 检索用于运行管道的源和已处理配置
get / pipeline / {pipeline-id} get / pipeline / {pipeline-id} / workflow get / pipeline / {pipeline-id} / config

另外三个新终点允许您

  • 检索个人工作流程
  • 检索个人工作流程’s jobs
  • 还有一个终端要取消工作流程
get / workflow / {id} get / workflow / {id} /作业post / workflow / {id} /取消

Circleci.API v2.supports OpenAPI

With API v2 we now have full support forOpenAPI 3。您可以下载一个现场规范,反映当前的生产API:

Learn more