# Environments API

> 原文：[https://docs.gitlab.com/ee/api/environments.html](https://docs.gitlab.com/ee/api/environments.html)

*   [List environments](#list-environments)
*   [Get a specific environment](#get-a-specific-environment)
*   [Create a new environment](#create-a-new-environment)
*   [Edit an existing environment](#edit-an-existing-environment)
*   [Delete an environment](#delete-an-environment)
*   [Stop an environment](#stop-an-environment)

# Environments API[](#environments-api "Permalink")

## List environments[](#list-environments "Permalink")

获取给定项目的所有环境.

```
GET /projects/:id/environments 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | no | 使用此名称返回环境. 与`search`互斥 |
| `search` | string | no | 返回符合搜索条件的环境列表. 与`name`互斥 |
| `states` | string | no | 列出与特定状态匹配的所有环境. 接受的值： `available`或已`stopped` . 如果没有给出状态值，则返回所有环境. |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments?name=review%2Ffix-foo" 
```

响应示例：

```
[  {  "id":  1,  "name":  "review/fix-foo",  "slug":  "review-fix-foo-dfjre3",  "external_url":  "https://review-fix-foo-dfjre3.example.gitlab.com",  "state":  "available"  }  ] 
```

## Get a specific environment[](#get-a-specific-environment "Permalink")

```
GET /projects/:id/environments/:environment_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `environment_id` | integer | yes | 环境的 ID |

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" 
```

回应范例

```
{  "id":  1,  "name":  "review/fix-foo",  "slug":  "review-fix-foo-dfjre3",  "external_url":  "https://review-fix-foo-dfjre3.example.gitlab.com"  "state":  "available",  "last_deployment":  {  "id":  100,  "iid":  34,  "ref":  "fdroid",  "sha":  "416d8ea11849050d3d1f5104cf8cf51053e790ab",  "created_at":  "2019-03-25T18:55:13.252Z",  "status":  "success",  "user":  {  "id":  1,  "name":  "Administrator",  "state":  "active",  "username":  "root",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://localhost:3000/root"  }  "deployable":  {  "id":  710,  "status":  "success",  "stage":  "deploy",  "name":  "staging",  "ref":  "fdroid",  "tag":  false,  "coverage":  null,  "created_at":  "2019-03-25T18:55:13.215Z",  "started_at":  "2019-03-25T12:54:50.082Z",  "finished_at":  "2019-03-25T18:55:13.216Z",  "duration":  21623.13423,  "user":  {  "id":  1,  "name":  "Administrator",  "username":  "root",  "state":  "active",  "avatar_url":  "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",  "web_url":  "http://gitlab.dev/root",  "created_at":  "2015-12-21T13:14:24.077Z",  "bio":  null,  "location":  null,  "public_email":  "",  "skype":  "",  "linkedin":  "",  "twitter":  "",  "website_url":  "",  "organization":  null  }  "commit":  {  "id":  "416d8ea11849050d3d1f5104cf8cf51053e790ab",  "short_id":  "416d8ea1",  "created_at":  "2016-01-02T15:39:18.000Z",  "parent_ids":  [  "e9a4449c95c64358840902508fc827f1a2eab7df"  ],  "title":  "Removed fabric to fix #40",  "message":  "Removed fabric to fix #40\n",  "author_name":  "Administrator",  "author_email":  "admin@example.com",  "authored_date":  "2016-01-02T15:39:18.000Z",  "committer_name":  "Administrator",  "committer_email":  "admin@example.com",  "committed_date":  "2016-01-02T15:39:18.000Z"  },  "pipeline":  {  "id":  34,  "sha":  "416d8ea11849050d3d1f5104cf8cf51053e790ab",  "ref":  "fdroid",  "status":  "success",  "web_url":  "http://localhost:3000/Commit451/lab-coat/pipelines/34"  },  "web_url":  "http://localhost:3000/Commit451/lab-coat/-/jobs/710",  "artifacts":  [  {  "file_type":  "trace",  "size":  1305,  "filename":  "job.log",  "file_format":  null  }  ],  "runner":  null,  "artifacts_expire_at":  null  }  }  } 
```

## Create a new environment[](#create-a-new-environment "Permalink")

使用给定名称和`external_url`创建一个新环境.

如果成功创建了环境，则返回`201`否则返回`400` .

```
POST /projects/:id/environments 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `name` | string | yes | 环境名称 |
| `external_url` | string | no | Place to link to for this environment |

```
curl --data "name=deploy&external_url=https://deploy.example.gitlab.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments" 
```

响应示例：

```
{  "id":  1,  "name":  "deploy",  "slug":  "deploy",  "external_url":  "https://deploy.example.gitlab.com",  "state":  "available"  } 
```

## Edit an existing environment[](#edit-an-existing-environment "Permalink")

更新现有环境的名称和/或`external_url` .

如果成功更新了环境，它将返回`200` . 如果出现错误，则返回状态码`400` .

```
PUT /projects/:id/environments/:environments_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `environment_id` | integer | yes | 环境的 ID |
| `name` | string | no | 环境的新名称 |
| `external_url` | string | no | 新的`external_url` |

```
curl --request PUT --data "name=staging&external_url=https://staging.example.gitlab.com" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" 
```

响应示例：

```
{  "id":  1,  "name":  "staging",  "slug":  "staging",  "external_url":  "https://staging.example.gitlab.com",  "state":  "available"  } 
```

## Delete an environment[](#delete-an-environment "Permalink")

如果成功删除了环境，则返回`204`如果环境不存在，则返回`404` .

```
DELETE /projects/:id/environments/:environment_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `environment_id` | integer | yes | 环境的 ID |

```
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" 
```

## Stop an environment[](#stop-an-environment "Permalink")

如果成功停止了环境，则返回`200`如果环境不存在，则返回`404` .

```
POST /projects/:id/environments/:environment_id/stop 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 经过身份验证的用户拥有[的项目](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `environment_id` | integer | yes | 环境的 ID |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1/stop" 
```

响应示例：

```
{  "id":  1,  "name":  "deploy",  "slug":  "deploy",  "external_url":  "https://deploy.example.gitlab.com",  "state":  "stopped"  } 
```