Help us learn about your current experience with the documentation. Take the survey.

功能标志 API

版本: Free, Premium, Ultimate
产品: GitLab.com, GitLab Self-Managed, GitLab Dedicated

使用此 API 与 GitLab 功能标志进行交互。

前提条件：

您必须至少拥有 Developer 角色。

列出项目的功能标志

获取所请求项目的所有功能标志。

GET /projects/:id/feature_flags

使用 page 和 per_page 分页参数来控制结果的分页。

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`scope`	string	否	功能标志的条件，可选值：`enabled`、`disabled`。

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

示例响应：

[
   {
      "name":"merge_train",
      "description":"This feature is about merge train",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:51.423Z",
      "updated_at":"2019-11-04T08:13:51.423Z",
      "scopes":[],
      "strategies": [
        {
          "id": 1,
          "name": "userWithId",
          "parameters": {
            "userIds": "user1"
          },
          "scopes": [
            {
              "id": 1,
              "environment_scope": "production"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "name":"new_live_trace",
      "description":"This is a new live trace feature",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:10.507Z",
      "updated_at":"2019-11-04T08:13:10.507Z",
      "scopes":[],
      "strategies": [
        {
          "id": 2,
          "name": "default",
          "parameters": {},
          "scopes": [
            {
              "id": 2,
              "environment_scope": "staging"
            }
          ],
          "user_list": null
        }
      ]
   },
   {
      "name":"user_list",
      "description":"This feature is about user list",
      "active": true,
      "version": "new_version_flag",
      "created_at":"2019-11-04T08:13:10.507Z",
      "updated_at":"2019-11-04T08:13:10.507Z",
      "scopes":[],
      "strategies": [
        {
          "id": 2,
          "name": "gitlabUserList",
          "parameters": {},
          "scopes": [
            {
              "id": 2,
              "environment_scope": "staging"
            }
          ],
          "user_list": {
            "id": 1,
            "iid": 1,
            "name": "My user list",
            "user_xids": "user1,user2,user3"
          }
        }
      ]
   }
]

获取单个功能标志

获取单个功能标志。

GET /projects/:id/feature_flags/:feature_flag_name

使用 page 和 per_page 分页参数来控制结果的分页。

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`feature_flag_name`	string	是	功能标志的名称。

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

示例响应：

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T19:56:33.119Z",
  "updated_at": "2020-05-13T19:56:33.119Z",
  "scopes": [],
  "strategies": [
    {
      "id": 36,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 37,
          "environment_scope": "production"
        }
      ],
      "user_list": null
    }
  ]
}

创建功能标志

创建新功能标志。

POST /projects/:id/feature_flags

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`name`	string	是	功能标志的名称。
`version`	string	是	已弃用功能标志的版本。必须为 `new_version_flag`。省略此参数将创建传统功能标志。
`description`	string	否	功能标志的描述。
`active`	boolean	否	标志的激活状态。默认为 true。
`strategies`	strategy JSON 对象的数组	否	功能标志策略。
`strategies:name`	JSON	否	策略名称。可以是 `default`、`gradualRolloutUserId`、`userWithId` 或 `gitlabUserList`。在 GitLab 13.5 及更高版本中，可以是 `flexibleRollout`。
`strategies:parameters`	JSON	否	策略参数。
`strategies:scopes`	JSON	否	策略的作用域。
`strategies:scopes:environment_scope`	string	否	作用域的环境范围。
`strategies:user_list_id`	integer/string	否	功能标志用户列表的 ID。如果策略是 `gitlabUserList`。

curl "https://gitlab.example.com/api/v4/projects/1/feature_flags" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
  "name": "awesome_feature",
  "version": "new_version_flag",
  "strategies": [{ "name": "default", "parameters": {}, "scopes": [{ "environment_scope": "production" }] }]
}
EOF

示例响应：

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T19:56:33.119Z",
  "updated_at": "2020-05-13T19:56:33.119Z",
  "scopes": [],
  "strategies": [
    {
      "id": 36,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 37,
          "environment_scope": "production"
        }
      ]
    }
  ]
}

更新功能标志

更新功能标志。

PUT /projects/:id/feature_flags/:feature_flag_name

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`feature_flag_name`	string	是	功能标志的当前名称。
`description`	string	否	功能标志的描述。
`active`	boolean	否	标志的激活状态。
`name`	string	否	功能标志的新名称。
`strategies`	strategy JSON 对象的数组	否	功能标志策略。
`strategies:id`	JSON	否	功能标志策略 ID。
`strategies:name`	JSON	否	策略名称。
`strategies:_destroy`	boolean	否	当为 true 时删除策略。
`strategies:parameters`	JSON	否	策略参数。
`strategies:scopes`	JSON	否	策略的作用域。
`strategies:scopes:id`	JSON	否	环境范围 ID。
`strategies:scopes:environment_scope`	string	否	作用域的环境范围。
`strategies:scopes:_destroy`	boolean	否	当为 true 时删除作用域。
`strategies:user_list_id`	integer/string	否	功能标志用户列表的 ID。如果策略是 `gitlabUserList`。

curl "https://gitlab.example.com/api/v4/projects/1/feature_flags/awesome_feature" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --header "Content-type: application/json" \
     --data @- << EOF
{
  "strategies": [{ "name": "gradualRolloutUserId", "parameters": { "groupId": "default", "percentage": "25" }, "scopes": [{ "environment_scope": "staging" }] }]
}
EOF

示例响应：

{
  "name": "awesome_feature",
  "description": null,
  "active": true,
  "version": "new_version_flag",
  "created_at": "2020-05-13T20:10:32.891Z",
  "updated_at": "2020-05-13T20:10:32.891Z",
  "scopes": [],
  "strategies": [
    {
      "id": 38,
      "name": "gradualRolloutUserId",
      "parameters": {
        "groupId": "default",
        "percentage": "25"
      },
      "scopes": [
        {
          "id": 40,
          "environment_scope": "staging"
        }
      ]
    },
    {
      "id": 37,
      "name": "default",
      "parameters": {},
      "scopes": [
        {
          "id": 39,
          "environment_scope": "production"
        }
      ]
    }
  ]
}

删除功能标志

删除功能标志。

DELETE /projects/:id/feature_flags/:feature_flag_name

属性	类型	必需	描述
`id`	integer/string	是	项目的 ID 或 URL 编码路径。
`feature_flag_name`	string	是	功能标志的名称。

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