# Project-level Variables API

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

*   [List project variables](#list-project-variables)
*   [Show variable details](#show-variable-details)
*   [Create variable](#create-variable)
*   [Update variable](#update-variable)
*   [Remove variable](#remove-variable)
*   [The `filter` parameter](#the-filter-parameter)
    *   [Enable or disable](#enable-or-disable)

# Project-level Variables API[](#project-level-variables-api "Permalink")

## List project variables[](#list-project-variables "Permalink")

获取项目变量的列表.

```
GET /projects/:id/variables 
```

| Attribute | Type | required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 一个项目的 ID 或经过身份验证的用户拥有[的该项目的 Urlencoded NAMESPACE / PROJECT_NAME](README.html#namespaced-path-encoding) |

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

```
[  {  "key":  "TEST_VARIABLE_1",  "variable_type":  "env_var",  "value":  "TEST_1"  },  {  "key":  "TEST_VARIABLE_2",  "variable_type":  "env_var",  "value":  "TEST_2"  }  ] 
```

## Show variable details[](#show-variable-details "Permalink")

获取项目特定变量的详细信息.

```
GET /projects/:id/variables/:key 
```

| Attribute | Type | required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 一个项目的 ID 或经过身份验证的用户拥有[的该项目的 Urlencoded NAMESPACE / PROJECT_NAME](README.html#namespaced-path-encoding) |
| `key` | string | yes | 变量的`key` |
| `filter` | hash | no | 可用的过滤器： `[environment_scope]` . 请参阅[`filter`参数详细信息](#the-filter-parameter) . |

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

```
{  "key":  "TEST_VARIABLE_1",  "variable_type":  "env_var",  "value":  "TEST_1",  "protected":  false,  "masked":  true  } 
```

## Create variable[](#create-variable "Permalink")

创建一个新变量.

```
POST /projects/:id/variables 
```

| Attribute | Type | required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 一个项目的 ID 或经过身份验证的用户拥有[的该项目的 Urlencoded NAMESPACE / PROJECT_NAME](README.html#namespaced-path-encoding) |
| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed |
| `value` | string | yes | 变量的`value` |
| `variable_type` | string | no | 变量的类型. 可用类型为： `env_var` （默认）和`file` |
| `protected` | boolean | no | 变量是否受保护 |
| `masked` | boolean | no | 变量是否被屏蔽 |
| `environment_scope` | string | no | 变量的`environment_scope` |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" 
```

```
{  "key":  "NEW_VARIABLE",  "value":  "new value",  "protected":  false,  "variable_type":  "env_var",  "masked":  false,  "environment_scope":  "*"  } 
```

## Update variable[](#update-variable "Permalink")

更新项目的变量.

```
PUT /projects/:id/variables/:key 
```

| Attribute | Type | required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 一个项目的 ID 或经过身份验证的用户拥有[的该项目的 Urlencoded NAMESPACE / PROJECT_NAME](README.html#namespaced-path-encoding) |
| `key` | string | yes | 变量的`key` |
| `value` | string | yes | 变量的`value` |
| `variable_type` | string | no | 变量的类型. 可用类型为： `env_var` （默认）和`file` |
| `protected` | boolean | no | 变量是否受保护 |
| `masked` | boolean | no | 变量是否被屏蔽 |
| `environment_scope` | string | no | 变量的`environment_scope` |
| `filter` | hash | no | 可用的过滤器： `[environment_scope]` . 请参阅[`filter`参数详细信息](#the-filter-parameter) . |

```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" 
```

```
{  "key":  "NEW_VARIABLE",  "value":  "updated value",  "variable_type":  "env_var",  "protected":  true,  "masked":  false,  "environment_scope":  "*"  } 
```

## Remove variable[](#remove-variable "Permalink")

删除项目的变量.

```
DELETE /projects/:id/variables/:key 
```

| Attribute | Type | required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 一个项目的 ID 或经过身份验证的用户拥有[的该项目的 Urlencoded NAMESPACE / PROJECT_NAME](README.html#namespaced-path-encoding) |
| `key` | string | yes | 变量的`key` |
| `filter` | hash | no | 可用的过滤器： `[environment_scope]` . 请参阅[`filter`参数详细信息](#the-filter-parameter) . |

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

## The `filter` parameter[](#the-filter-parameter "Permalink")

版本历史

*   在 GitLab 13.2 中[引入](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/34490) .
*   它部署在功能标记后面，默认情况下处于禁用状态.
*   在 GitLab.com 上已禁用.
*   要在 GitLab 自管实例中使用它，请让 GitLab 管理员启用它.

此参数用于按属性（例如`environment_scope`进行过滤.

用法示例：

```
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/VARIABLE_1?filter[environment_scope]=production" 
```

### Enable or disable[](#enable-or-disable "Permalink")

[有权访问 GitLab Rails 控制台的 GitLab 管理员](../administration/feature_flags.html)可以为您的实例启用它.

要启用它：

```
Feature.enable(:ci_variables_api_filter_environment_scope) 
```

禁用它：

```
Feature.disable(:ci_variables_api_filter_environment_scope) 
```