# Groups API

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

*   [List groups](#list-groups)
*   [List a group’s subgroups](#list-a-groups-subgroups)
*   [List a group’s projects](#list-a-groups-projects)
*   [List a group’s shared projects](#list-a-groups-shared-projects)
*   [Details of a group](#details-of-a-group)
    *   [Disabling the results limit](#disabling-the-results-limit)
*   [New group](#new-group)
    *   [Options for `default_branch_protection`](#options-for-default_branch_protection)
*   [New Subgroup](#new-subgroup)
*   [Transfer project to group](#transfer-project-to-group)
*   [Update group](#update-group)
    *   [Disabling the results limit](#disabling-the-results-limit-1)
*   [Remove group](#remove-group)
*   [Restore group marked for deletion](#restore-group-marked-for-deletion-premium)
*   [Search for group](#search-for-group)
*   [Hooks](#hooks)
    *   [List group hooks](#list-group-hooks)
    *   [Get group hook](#get-group-hook)
    *   [Add group hook](#add-group-hook)
    *   [Edit group hook](#edit-group-hook)
    *   [Delete group hook](#delete-group-hook)
*   [Group Audit Events](#group-audit-events-starter)
*   [Sync group with LDAP](#sync-group-with-ldap-starter)
*   [Group members](#group-members)
*   [LDAP Group Links](#ldap-group-links)
    *   [List LDAP group links](#list-ldap-group-links-starter)
    *   [Add LDAP group link with CN or filter](#add-ldap-group-link-with-cn-or-filter-starter)
    *   [Delete LDAP group link](#delete-ldap-group-link-starter)
    *   [Delete LDAP group link with CN or filter](#delete-ldap-group-link-with-cn-or-filter-starter)
*   [Namespaces in groups](#namespaces-in-groups)
*   [Group badges](#group-badges)
*   [Group Import/Export](#group-importexport)
*   [Share Groups with Groups](#share-groups-with-groups)
    *   [Create a link to share a group with another group](#create-a-link-to-share-a-group-with-another-group)
    *   [Delete link sharing group with another group](#delete-link-sharing-group-with-another-group)

# Groups API[](#groups-api "Permalink")

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

获取已认证用户的可见组列表. 在未经身份验证的情况下访问时，仅返回公共组.

默认情况下，此请求一次返回 20 个结果，因为 API 结果[是分页的](README.html#pagination) .

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `skip_groups` | 整数数组 | no | 跳过传递的组 ID |
| `all_available` | boolean | no | 显示您有权访问的所有组（对于经过身份验证的用户，默认值为`false` ；对于管理员，默认`false` `true` ）； `owned`属性和`min_access_level`具有优先权 |
| `search` | string | no | 返回符合搜索条件的授权组列表 |
| `order_by` | string | no | 按`name` ， `path`或`id` . 默认`name` |
| `sort` | string | no | 按`asc`或`desc`顺序排列组. 默认为`asc` |
| `statistics` | boolean | no | 包括组统计信息（仅管理员） |
| `with_custom_attributes` | boolean | no | 在响应中包括[自定义属性](custom_attributes.html) （仅管理员） |
| `owned` | boolean | no | 限制为当前用户明确拥有的组 |
| `min_access_level` | integer | no | 限制为当前用户至少具有此[访问级别的组](members.html#valid-access-levels) |
| `top_level_only` | boolean | no | 限于顶级组，不包括所有子组 |

```
GET /groups 
```

```
[  {  "id":  1,  "name":  "Foobar Group",  "path":  "foo-bar",  "description":  "An interesting group",  "visibility":  "public",  "share_with_group_lock":  false,  "require_two_factor_authentication":  false,  "two_factor_grace_period":  48,  "project_creation_level":  "developer",  "auto_devops_enabled":  null,  "subgroup_creation_level":  "owner",  "emails_disabled":  null,  "mentions_disabled":  null,  "lfs_enabled":  true,  "default_branch_protection":  2,  "avatar_url":  "http://localhost:3000/uploads/group/avatar/1/foo.jpg",  "web_url":  "http://localhost:3000/groups/foo-bar",  "request_access_enabled":  false,  "full_name":  "Foobar Group",  "full_path":  "foo-bar",  "file_template_project_id":  1,  "parent_id":  null,  "created_at":  "2020-01-15T12:36:29.590Z"  }  ] 
```

当添加参数`statistics=true`且经过身份验证的用户是管理员时，将返回其他组统计信息.

```
GET /groups?statistics=true 
```

```
[  {  "id":  1,  "name":  "Foobar Group",  "path":  "foo-bar",  "description":  "An interesting group",  "visibility":  "public",  "share_with_group_lock":  false,  "require_two_factor_authentication":  false,  "two_factor_grace_period":  48,  "project_creation_level":  "developer",  "auto_devops_enabled":  null,  "subgroup_creation_level":  "owner",  "emails_disabled":  null,  "mentions_disabled":  null,  "lfs_enabled":  true,  "default_branch_protection":  2,  "avatar_url":  "http://localhost:3000/uploads/group/avatar/1/foo.jpg",  "web_url":  "http://localhost:3000/groups/foo-bar",  "request_access_enabled":  false,  "full_name":  "Foobar Group",  "full_path":  "foo-bar",  "file_template_project_id":  1,  "parent_id":  null,  "created_at":  "2020-01-15T12:36:29.590Z",  "statistics":  {  "storage_size"  :  212,  "repository_size"  :  33,  "wiki_size"  :  100,  "lfs_objects_size"  :  123,  "job_artifacts_size"  :  57,  "packages_size":  0,  "snippets_size"  :  50,  }  }  ] 
```

您可以按名称或路径搜索组，请参见下文.

您可以使用以下[自定义属性](custom_attributes.html)进行过滤：

```
GET /groups?custom_attributes[key]=value&custom_attributes[other_key]=other_value 
```

## List a group’s subgroups[](#list-a-groups-subgroups "Permalink")

在 GitLab 10.3 中[引入](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15142) .

获取此组中可见的直接子组的列表. 在未经身份验证的情况下访问时，仅返回公共组.

默认情况下，此请求一次返回 20 个结果，因为 API 结果[是分页的](README.html#pagination) .

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 直接父组[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `skip_groups` | 整数数组 | no | 跳过传递的组 ID |
| `all_available` | boolean | no | 显示您有权访问的所有组（对于经过身份验证的用户，默认值为`false` ；对于管理员，默认`false` `true` ）； `owned`属性和`min_access_level`具有优先权 |
| `search` | string | no | 返回符合搜索条件的授权组列表 |
| `order_by` | string | no | 按`name` ， `path`或`id` . 默认`name` |
| `sort` | string | no | 按`asc`或`desc`顺序排列组. 默认为`asc` |
| `statistics` | boolean | no | 包括组统计信息（仅管理员） |
| `with_custom_attributes` | boolean | no | 在响应中包括[自定义属性](custom_attributes.html) （仅管理员） |
| `owned` | boolean | no | 限制为当前用户明确拥有的组 |
| `min_access_level` | integer | no | 限制为当前用户至少具有此[访问级别的组](members.html#valid-access-levels) |

```
GET /groups/:id/subgroups 
```

```
[  {  "id":  1,  "name":  "Foobar Group",  "path":  "foo-bar",  "description":  "An interesting group",  "visibility":  "public",  "share_with_group_lock":  false,  "require_two_factor_authentication":  false,  "two_factor_grace_period":  48,  "project_creation_level":  "developer",  "auto_devops_enabled":  null,  "subgroup_creation_level":  "owner",  "emails_disabled":  null,  "mentions_disabled":  null,  "lfs_enabled":  true,  "default_branch_protection":  2,  "avatar_url":  "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg",  "web_url":  "http://gitlab.example.com/groups/foo-bar",  "request_access_enabled":  false,  "full_name":  "Foobar Group",  "full_path":  "foo-bar",  "file_template_project_id":  1,  "parent_id":  123,  "created_at":  "2020-01-15T12:36:29.590Z"  }  ] 
```

## List a group’s projects[](#list-a-groups-projects "Permalink")

获取此组中的项目列表. 在未经身份验证的情况下访问时，仅返回公共项目.

默认情况下，此请求一次返回 20 个结果，因为 API 结果[是分页的](README.html#pagination) .

```
GET /groups/:id/projects 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `archived` | boolean | no | 受存档状态限制 |
| `visibility` | string | no | 受`public` ， `internal`或`private`可见性限制 |
| `order_by` | string | no | 返回按`id` ， `name` ， `path` ， `created_at` ， `updated_at`或`last_activity_at`字段排序的项目. 默认为`created_at` |
| `sort` | string | no | 返回按`asc`或`desc`顺序排序的项目. 默认为`desc` |
| `search` | string | no | 返回符合搜索条件的授权项目列表 |
| `simple` | boolean | no | 仅返回每个项目的 ID，URL，名称和路径 |
| `owned` | boolean | no | 受当前用户拥有的项目限制 |
| `starred` | boolean | no | 受当前用户加注星标的项目限制 |
| `with_issues_enabled` | boolean | no | 受具有问题功能的项目限制. 默认为`false` |
| `with_merge_requests_enabled` | boolean | no | 受启用合并请求功能的项目限制. 默认为`false` |
| `with_shared` | boolean | no | 包括共享给该组的项目. 默认为`true` |
| `include_subgroups` | boolean | no | 将项目包括在该组的子组中. 默认为`false` |
| `min_access_level` | integer | no | 限于当前用户至少具有此[访问级别的项目](members.html#valid-access-levels) |
| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.html) in response (admins only) |
| `with_security_reports` | boolean | no | 仅返回在任何版本中都存在安全报告工件的项目. 这意味着"启用了安全报告的项目". 默认为`false` |

响应示例：

```
[  {  "id":  9,  "description":  "foo",  "default_branch":  "master",  "tag_list":  [],  "archived":  false,  "visibility":  "internal",  "ssh_url_to_repo":  "git@gitlab.example.com/html5-boilerplate.git",  "http_url_to_repo":  "http://gitlab.example.com/h5bp/html5-boilerplate.git",  "web_url":  "http://gitlab.example.com/h5bp/html5-boilerplate",  "name":  "Html5 Boilerplate",  "name_with_namespace":  "Experimental / Html5 Boilerplate",  "path":  "html5-boilerplate",  "path_with_namespace":  "h5bp/html5-boilerplate",  "issues_enabled":  true,  "merge_requests_enabled":  true,  "wiki_enabled":  true,  "jobs_enabled":  true,  "snippets_enabled":  true,  "created_at":  "2016-04-05T21:40:50.169Z",  "last_activity_at":  "2016-04-06T16:52:08.432Z",  "shared_runners_enabled":  true,  "creator_id":  1,  "namespace":  {  "id":  5,  "name":  "Experimental",  "path":  "h5bp",  "kind":  "group"  },  "avatar_url":  null,  "star_count":  1,  "forks_count":  0,  "open_issues_count":  3,  "public_jobs":  true,  "shared_with_groups":  [],  "request_access_enabled":  false  }  ] 
```

**注意：**为了区分组中的项目和共享给组的项目，可以使用`namespace`属性. 将项目共享给组后，其`namespace`将与请求的组不同.

## List a group’s shared projects[](#list-a-groups-shared-projects "Permalink")

获取共享给该组的项目的列表. 未经身份验证访问时，仅返回公共共享项目.

默认情况下，此请求一次返回 20 个结果，因为 API 结果[是分页的](README.html#pagination) .

```
GET /groups/:id/projects/shared 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) |
| `archived` | boolean | no | 受存档状态限制 |
| `visibility` | string | no | 受`public` ， `internal`或`private`可见性限制 |
| `order_by` | string | no | 返回按`id` ， `name` ， `path` ， `created_at` ， `updated_at`或`last_activity_at`字段排序的项目. 默认为`created_at` |
| `sort` | string | no | 返回按`asc`或`desc`顺序排序的项目. 默认为`desc` |
| `search` | string | no | 返回符合搜索条件的授权项目列表 |
| `simple` | boolean | no | 仅返回每个项目的 ID，URL，名称和路径 |
| `starred` | boolean | no | 受当前用户加注星标的项目限制 |
| `with_issues_enabled` | boolean | no | 受具有问题功能的项目限制. 默认为`false` |
| `with_merge_requests_enabled` | boolean | no | 受启用合并请求功能的项目限制. 默认为`false` |
| `min_access_level` | integer | no | 限于当前用户至少具有此[访问级别的项目](members.html#valid-access-levels) |
| `with_custom_attributes` | boolean | no | 在响应中包括[自定义属性](custom_attributes.html) （仅管理员） |

响应示例：

```
[  {  "id":8,  "description":"Shared project for Html5 Boilerplate",  "name":"Html5 Boilerplate",  "name_with_namespace":"H5bp / Html5 Boilerplate",  "path":"html5-boilerplate",  "path_with_namespace":"h5bp/html5-boilerplate",  "created_at":"2020-04-27T06:13:22.642Z",  "default_branch":"master",  "tag_list":[  ],  "ssh_url_to_repo":"ssh://git@gitlab.com/h5bp/html5-boilerplate.git",  "http_url_to_repo":"http://gitlab.com/h5bp/html5-boilerplate.git",  "web_url":"http://gitlab.com/h5bp/html5-boilerplate",  "readme_url":"http://gitlab.com/h5bp/html5-boilerplate/-/blob/master/README.md",  "avatar_url":null,  "star_count":0,  "forks_count":4,  "last_activity_at":"2020-04-27T06:13:22.642Z",  "namespace":{  "id":28,  "name":"H5bp",  "path":"h5bp",  "kind":"group",  "full_path":"h5bp",  "parent_id":null,  "avatar_url":null,  "web_url":"http://gitlab.com/groups/h5bp"  },  "_links":{  "self":"http://gitlab.com/api/v4/projects/8",  "issues":"http://gitlab.com/api/v4/projects/8/issues",  "merge_requests":"http://gitlab.com/api/v4/projects/8/merge_requests",  "repo_branches":"http://gitlab.com/api/v4/projects/8/repository/branches",  "labels":"http://gitlab.com/api/v4/projects/8/labels",  "events":"http://gitlab.com/api/v4/projects/8/events",  "members":"http://gitlab.com/api/v4/projects/8/members"  },  "empty_repo":false,  "archived":false,  "visibility":"public",  "resolve_outdated_diff_discussions":false,  "container_registry_enabled":true,  "container_expiration_policy":{  "cadence":"7d",  "enabled":true,  "keep_n":null,  "older_than":null,  "name_regex":null,  "name_regex_keep":null,  "next_run_at":"2020-05-04T06:13:22.654Z"  },  "issues_enabled":true,  "merge_requests_enabled":true,  "wiki_enabled":true,  "jobs_enabled":true,  "snippets_enabled":true,  "can_create_merge_request_in":true,  "issues_access_level":"enabled",  "repository_access_level":"enabled",  "merge_requests_access_level":"enabled",  "forking_access_level":"enabled",  "wiki_access_level":"enabled",  "builds_access_level":"enabled",  "snippets_access_level":"enabled",  "pages_access_level":"enabled",  "emails_disabled":null,  "shared_runners_enabled":true,  "lfs_enabled":true,  "creator_id":1,  "import_status":"failed",  "open_issues_count":10,  "ci_default_git_depth":50,  "public_jobs":true,  "build_timeout":3600,  "auto_cancel_pending_pipelines":"enabled",  "build_coverage_regex":null,  "ci_config_path":null,  "shared_with_groups":[  {  "group_id":24,  "group_name":"Commit451",  "group_full_path":"Commit451",  "group_access_level":30,  "expires_at":null  }  ],  "only_allow_merge_if_pipeline_succeeds":false,  "request_access_enabled":true,  "only_allow_merge_if_all_discussions_are_resolved":false,  "remove_source_branch_after_merge":true,  "printing_merge_request_link_enabled":true,  "merge_method":"merge",  "suggestion_commit_message":null,  "auto_devops_enabled":true,  "auto_devops_deploy_strategy":"continuous",  "autoclose_referenced_issues":true,  "repository_storage":"default"  }  ] 
```

## Details of a group[](#details-of-a-group "Permalink")

获取组的所有详细信息. 如果可以公开访问该组，则无需身份验证即可访问该端点. 如果请求的用户是该组的管理员，它将也返回该组的`runners_token` .

```
GET /groups/:id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 认证用户拥有[的组](README.html#namespaced-path-encoding)的 ID 或[URL 编码路径](README.html#namespaced-path-encoding) . |
| `with_custom_attributes` | boolean | no | 在响应中包括[自定义属性](custom_attributes.html) （仅管理员）. |
| `with_projects` | boolean | no | 包括属于指定组的项目的详细信息（默认为`true` ）. （已弃用， [将在 API v5 中删除](https://gitlab.com/gitlab-org/gitlab/-/issues/213797) .要获取组中所有项目的详细信息，请使用[列出组的项目终结点](#list-a-groups-projects) .） |

**注意：**响应中的`projects`和`shared_projects`属性已弃用，并将[在 API v5 中删除](https://gitlab.com/gitlab-org/gitlab/-/issues/213797) . 要获取组内所有项目的详细信息，请使用[列出组的项目](#list-a-groups-projects)或[列出组的共享项目](#list-a-groups-shared-projects)端点.

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4" 
```

该端点返回：

*   GitLab 12.5 和更早版本中的所有项目和共享项目.
*   [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/31031)及更高版本中最多有 100 个项目和共享项目. 要获取组中所有项目的详细信息，请使用[列出组的项目端点](#list-a-groups-projects)的[列表](#list-a-groups-projects) .

响应示例：

```
{  "id":  4,  "name":  "Twitter",  "path":  "twitter",  "description":  "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",  "visibility":  "public",  "avatar_url":  null,  "web_url":  "https://gitlab.example.com/groups/twitter",  "request_access_enabled":  false,  "full_name":  "Twitter",  "full_path":  "twitter",  "runners_token":  "ba324ca7b1c77fc20bb9",  "file_template_project_id":  1,  "parent_id":  null,  "created_at":  "2020-01-15T12:36:29.590Z",  "shared_with_groups":  [  {  "group_id":  28,  "group_name":  "H5bp",  "group_full_path":  "h5bp",  "group_access_level":  20,  "expires_at":  null  }  ],  "projects":  [  //  Deprecated  and  will  be  removed  in  API  v5  {  "id":  7,  "description":  "Voluptas veniam qui et beatae voluptas doloremque explicabo facilis.",  "default_branch":  "master",  "tag_list":  [],  "archived":  false,  "visibility":  "public",  "ssh_url_to_repo":  "git@gitlab.example.com:twitter/typeahead-js.git",  "http_url_to_repo":  "https://gitlab.example.com/twitter/typeahead-js.git",  "web_url":  "https://gitlab.example.com/twitter/typeahead-js",  "name":  "Typeahead.Js",  "name_with_namespace":  "Twitter / Typeahead.Js",  "path":  "typeahead-js",  "path_with_namespace":  "twitter/typeahead-js",  "issues_enabled":  true,  "merge_requests_enabled":  true,  "wiki_enabled":  true,  "jobs_enabled":  true,  "snippets_enabled":  false,  "container_registry_enabled":  true,  "created_at":  "2016-06-17T07:47:25.578Z",  "last_activity_at":  "2016-06-17T07:47:25.881Z",  "shared_runners_enabled":  true,  "creator_id":  1,  "namespace":  {  "id":  4,  "name":  "Twitter",  "path":  "twitter",  "kind":  "group"  },  "avatar_url":  null,  "star_count":  0,  "forks_count":  0,  "open_issues_count":  3,  "public_jobs":  true,  "shared_with_groups":  [],  "request_access_enabled":  false  },  {  "id":  6,  "description":  "Aspernatur omnis repudiandae qui voluptatibus eaque.",  "default_branch":  "master",  "tag_list":  [],  "archived":  false,  "visibility":  "internal",  "ssh_url_to_repo":  "git@gitlab.example.com:twitter/flight.git",  "http_url_to_repo":  "https://gitlab.example.com/twitter/flight.git",  "web_url":  "https://gitlab.example.com/twitter/flight",  "name":  "Flight",  "name_with_namespace":  "Twitter / Flight",  "path":  "flight",  "path_with_namespace":  "twitter/flight",  "issues_enabled":  true,  "merge_requests_enabled":  true,  "wiki_enabled":  true,  "jobs_enabled":  true,  "snippets_enabled":  false,  "container_registry_enabled":  true,  "created_at":  "2016-06-17T07:47:24.661Z",  "last_activity_at":  "2016-06-17T07:47:24.838Z",  "shared_runners_enabled":  true,  "creator_id":  1,  "namespace":  {  "id":  4,  "name":  "Twitter",  "path":  "twitter",  "kind":  "group"  },  "avatar_url":  null,  "star_count":  0,  "forks_count":  0,  "open_issues_count":  8,  "public_jobs":  true,  "shared_with_groups":  [],  "request_access_enabled":  false  }  ],  "shared_projects":  [  //  Deprecated  and  will  be  removed  in  API  v5  {  "id":  8,  "description":  "Velit eveniet provident fugiat saepe eligendi autem.",  "default_branch":  "master",  "tag_list":  [],  "archived":  false,  "visibility":  "private",  "ssh_url_to_repo":  "git@gitlab.example.com:h5bp/html5-boilerplate.git",  "http_url_to_repo":  "https://gitlab.example.com/h5bp/html5-boilerplate.git",  "web_url":  "https://gitlab.example.com/h5bp/html5-boilerplate",  "name":  "Html5 Boilerplate",  "name_with_namespace":  "H5bp / Html5 Boilerplate",  "path":  "html5-boilerplate",  "path_with_namespace":  "h5bp/html5-boilerplate",  "issues_enabled":  true,  "merge_requests_enabled":  true,  "wiki_enabled":  true,  "jobs_enabled":  true,  "snippets_enabled":  false,  "container_registry_enabled":  true,  "created_at":  "2016-06-17T07:47:27.089Z",  "last_activity_at":  "2016-06-17T07:47:27.310Z",  "shared_runners_enabled":  true,  "creator_id":  1,  "namespace":  {  "id":  5,  "name":  "H5bp",  "path":  "h5bp",  "kind":  "group"  },  "avatar_url":  null,  "star_count":  0,  "forks_count":  0,  "open_issues_count":  4,  "public_jobs":  true,  "shared_with_groups":  [  {  "group_id":  4,  "group_name":  "Twitter",  "group_full_path":  "twitter",  "group_access_level":  30,  "expires_at":  null  },  {  "group_id":  3,  "group_name":  "Gitlab Org",  "group_full_path":  "gitlab-org",  "group_access_level":  10,  "expires_at":  "2018-08-14"  }  ]  }  ]  } 
```

使用 GitLab [Starter，Bronze 或更高版本的用户](https://about.gitlab.com/pricing/)还将看到`shared_runners_minutes_limit`和`extra_shared_runners_minutes_limit`参数：

其他响应参数：

```
{  "id":  4,  "description":  "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",  "shared_runners_minutes_limit":  133,  "extra_shared_runners_minutes_limit":  133,  ...  } 
```

Users on GitLab [Silver, Premium, or higher](https://about.gitlab.com/pricing/) will also see the `marked_for_deletion_on` attribute:

```
{  "id":  4,  "description":  "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",  "marked_for_deletion_on":  "2020-04-03",  ...  } 
```

当添加参数`with_projects=false` ，将不返回项目.

```
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4?with_projects=false" 
```

响应示例：

```
{  "id":  4,  "name":  "Twitter",  "path":  "twitter",  "description":  "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.",  "visibility":  "public",  "avatar_url":  null,  "web_url":  "https://gitlab.example.com/groups/twitter",  "request_access_enabled":  false,  "full_name":  "Twitter",  "full_path":  "twitter",  "file_template_project_id":  1,  "parent_id":  null  } 
```

### Disabling the results limit[](#disabling-the-results-limit "Permalink")

如果它破坏了使用 GitLab 12.4 和更早版本开发的集成，则可以禁用 100 个结果限制.

要在迁移到使用[列表的组项目](#list-a-groups-projects)终结点时禁用限制，请要求具有 Rails 控制台访问权限的 GitLab 管理员运行以下命令：

```
Feature.disable(:limit_projects_in_groups_api) 
```

## New group[](#new-group "Permalink")

创建一个新的项目组. 仅适用于可以创建组的用户.

```
POST /groups 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes | 组的名称. |
| `path` | string | yes | 组的路径. |
| `description` | string | no | 组的描述. |
| `membership_lock` | boolean | no | 阻止将新成员添加到该组中的项目成员中. |
| `visibility` | string | no | 小组的知名度. 可以是`private` ， `internal`或`public` . |
| `share_with_group_lock` | boolean | no | 防止与该组中的另一个组共享项目. |
| `require_two_factor_authentication` | boolean | no | 要求该组中的所有用户设置双重身份验证. |
| `two_factor_grace_period` | integer | no | 实施两因素身份验证之前的时间（以小时为单位）. |
| `project_creation_level` | string | no | 确定开发人员是否可以在组中创建项目. 可`noone` （没有之一）， `maintainer` （维护者），或`developer` （开发+维护者）. |
| `auto_devops_enabled` | boolean | no | 对于该组中的所有项目，默认为 Auto DevOps 管道. |
| `subgroup_creation_level` | string | no | 允许创建子组. 可以是`owner` （所有者）或`maintainer` （维护者）. |
| `emails_disabled` | boolean | no | 禁用电子邮件通知 |
| `avatar` | mixed | no | 该组头像的图像文件. [在 GitLab 12.9 中引入](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) |
| `mentions_disabled` | boolean | no | 禁止一个人被提及 |
| `lfs_enabled` | boolean | no | 为该组中的项目启用/禁用大文件存储（LFS）. |
| `request_access_enabled` | boolean | no | 允许用户请求成员访问权限. |
| `parent_id` | integer | no | 用于创建嵌套组的父组 ID. |
| `default_branch_protection` | integer | no | 请参阅[`default_branch_protection`选项](#options-for-default_branch_protection) . 默认为全局级别的默认分支保护设置. |
| `shared_runners_minutes_limit` | integer | no | 该组的管道分钟配额（包括在计划中）. 可以为`nil` （默认值；继承系统默认值）， `0` （无限制）或`> 0` |
| `extra_shared_runners_minutes_limit` | integer | no | 该组的额外管道分钟配额（在计划中包括的分钟之外购买）. |

### Options for `default_branch_protection`[](#options-for-default_branch_protection "Permalink")

`default_branch_protection`属性确定开发人员和维护人员是否可以推送到适用的 master 分支，如下表所示：

| Value | Description |
| --- | --- |
| `0` | 没有保护. 开发人员和维护人员可以：
-推送新的提交
-强制推送更改
-删除分支 |
| `1` | 部分保护. 开发人员和维护人员可以：
-推送新的提交 |
| `2` | 全面保护. 只有维护者可以：
-推送新的提交 |

## New Subgroup[](#new-subgroup "Permalink")

这类似于创建" [新建"组](#new-group) . 您将需要" [列表"组](#list-groups)调用中的`parent_id` . 然后，您可以输入所需的内容：

*   `subgroup_path`
*   `subgroup_name`

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
  --data '{"path": "<subgroup_path>", "name": "<subgroup_name>", "parent_id": <parent_group_id> } \
  "https://gitlab.example.com/api/v4/groups/" 
```

## Transfer project to group[](#transfer-project-to-group "Permalink")

将项目传输到组名称空间. 尽管不需要实例管理员访问权限的[替代 API 端点](projects.html#transfer-a-project-to-a-new-namespace)可用，但仅对实例管理员可用. 当项目存储库中存在标记的程序包时，传输项目可能会失败.

```
POST  /groups/:id/projects/:project_id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the target group](README.html#namespaced-path-encoding) |
| `project_id` | integer/string | yes | 项目的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |

```
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/4/projects/56" 
```

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

更新项目组. 仅对组所有者和管理员可用.

```
PUT /groups/:id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer | yes | 组的 ID. |
| `name` | string | no | 组的名称. |
| `path` | string | no | 组的路径. |
| `description` | string | no | 组的描述. |
| `membership_lock` | boolean | no | 阻止将新成员添加到该组中的项目成员中. |
| `share_with_group_lock` | boolean | no | 防止与该组中的另一个组共享项目. |
| `visibility` | string | no | 组的可见性级别. 可以是`private` ， `internal`或`public` . |
| `require_two_factor_authentication` | boolean | no | 要求该组中的所有用户设置双重身份验证. |
| `two_factor_grace_period` | integer | no | 实施两因素身份验证之前的时间（以小时为单位）. |
| `project_creation_level` | string | no | 确定开发人员是否可以在组中创建项目. 可`noone` （没有之一）， `maintainer` （维护者），或`developer` （开发+维护者）. |
| `auto_devops_enabled` | boolean | no | 对于该组中的所有项目，默认为 Auto DevOps 管道. |
| `subgroup_creation_level` | string | no | 允许创建子组. 可以是`owner` （所有者）或`maintainer` （维护者）. |
| `emails_disabled` | boolean | no | 禁用电子邮件通知 |
| `avatar` | mixed | no | 该组头像的图像文件. [在 GitLab 12.9 中引入](https://gitlab.com/gitlab-org/gitlab/-/issues/36681) |
| `mentions_disabled` | boolean | no | 禁止一个人被提及 |
| `lfs_enabled` (optional) | boolean | no | 为该组中的项目启用/禁用大文件存储（LFS）. |
| `request_access_enabled` | boolean | no | 允许用户请求成员访问权限. |
| `default_branch_protection` | integer | no | See [Options for `default_branch_protection`](#options-for-default_branch_protection). |
| `file_template_project_id` | integer | no | 从中加载自定义文件模板的项目的 ID. |
| `shared_runners_minutes_limit` | integer | no | 该组的管道分钟配额（包括在计划中）. 可以为`nil` （默认值；继承系统默认值）， `0` （无限制）或`> 0` |
| `extra_shared_runners_minutes_limit` | integer | no | 该组的额外管道分钟配额（在计划中包括的分钟之外购买）. |

**注意：**响应中的`projects`和`shared_projects`属性已弃用，并将[在 API v5 中删除](https://gitlab.com/gitlab-org/gitlab/-/issues/213797) . 要获取组内所有项目的详细信息，请使用[列出组的项目](#list-a-groups-projects)或[列出组的共享项目](#list-a-groups-shared-projects)端点.

```
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" 
```

该端点返回：

*   GitLab 12.5 和更早版本中的所有项目和共享项目.
*   [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/-/issues/31031)及更高版本中最多有 100 个项目和共享项目. 要获取组中所有项目的详细信息，请使用[列出组的项目端点](#list-a-groups-projects)的[列表](#list-a-groups-projects) .

响应示例：

```
{  "id":  5,  "name":  "Experimental",  "path":  "h5bp",  "description":  "foo",  "visibility":  "internal",  "avatar_url":  null,  "web_url":  "http://gitlab.example.com/groups/h5bp",  "request_access_enabled":  false,  "full_name":  "Foobar Group",  "full_path":  "foo-bar",  "file_template_project_id":  1,  "parent_id":  null,  "created_at":  "2020-01-15T12:36:29.590Z",  "projects":  [  //  Deprecated  and  will  be  removed  in  API  v5  {  "id":  9,  "description":  "foo",  "default_branch":  "master",  "tag_list":  [],  "public":  false,  "archived":  false,  "visibility":  "internal",  "ssh_url_to_repo":  "git@gitlab.example.com/html5-boilerplate.git",  "http_url_to_repo":  "http://gitlab.example.com/h5bp/html5-boilerplate.git",  "web_url":  "http://gitlab.example.com/h5bp/html5-boilerplate",  "name":  "Html5 Boilerplate",  "name_with_namespace":  "Experimental / Html5 Boilerplate",  "path":  "html5-boilerplate",  "path_with_namespace":  "h5bp/html5-boilerplate",  "issues_enabled":  true,  "merge_requests_enabled":  true,  "wiki_enabled":  true,  "jobs_enabled":  true,  "snippets_enabled":  true,  "created_at":  "2016-04-05T21:40:50.169Z",  "last_activity_at":  "2016-04-06T16:52:08.432Z",  "shared_runners_enabled":  true,  "creator_id":  1,  "namespace":  {  "id":  5,  "name":  "Experimental",  "path":  "h5bp",  "kind":  "group"  },  "avatar_url":  null,  "star_count":  1,  "forks_count":  0,  "open_issues_count":  3,  "public_jobs":  true,  "shared_with_groups":  [],  "request_access_enabled":  false  }  ]  } 
```

### Disabling the results limit[](#disabling-the-results-limit-1 "Permalink")

The 100 results limit can be disabled if it breaks integrations developed using GitLab 12.4 and earlier.

要在迁移到使用[列表的组项目](#list-a-groups-projects)终结点时禁用限制，请要求具有 Rails 控制台访问权限的 GitLab 管理员运行以下命令：

```
Feature.disable(:limit_projects_in_groups_api) 
```

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

仅对组所有者和管理员可用.

该端点：

*   删除组，并在后台作业中排队以删除该组中的所有项目.
*   从[GitLab 12.8 开始](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) ，在[Premium 或 Silver](https://about.gitlab.com/pricing/)或更高级别上，将一个组标记为删除. 默认情况下，删除将在 7 天后进行，但是可以在[实例设置中](../user/admin_area/settings/visibility_and_access_controls.html#default-deletion-adjourned-period-premium-only)进行更改.

```
DELETE /groups/:id 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |

如果用户具有授权，则响应将为`202 Accepted` .

## Restore group marked for deletion[](#restore-group-marked-for-deletion-premium "Permalink")

在 GitLab 12.8 中[引入](https://gitlab.com/gitlab-org/gitlab/-/issues/33257) .

恢复标记为删除的组.

```
POST /groups/:id/restore 
```

Parameters:

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |

## Search for group[](#search-for-group "Permalink")

获取名称或路径中与您的字符串匹配的所有组.

```
GET /groups?search=foobar 
```

```
[  {  "id":  1,  "name":  "Foobar Group",  "path":  "foo-bar",  "description":  "An interesting group"  }  ] 
```

## Hooks[](#hooks "Permalink")

也称为群组挂钩和 Webhooks. 这些不同于系统范围的[系统挂钩](system_hooks.html)和限于一个项目的[项目挂钩](projects.html#hooks) .

### List group hooks[](#list-group-hooks "Permalink")

获取组挂钩列表

```
GET /groups/:id/hooks 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |

### Get group hook[](#get-group-hook "Permalink")

获取组的特定挂钩.

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `hook_id` | integer | yes | 组挂钩的 ID |

```
GET /groups/:id/hooks/:hook_id 
```

```
{  "id":  1,  "url":  "http://example.com/hook",  "group_id":  3,  "push_events":  true,  "issues_events":  true,  "confidential_issues_events":  true,  "merge_requests_events":  true,  "tag_push_events":  true,  "note_events":  true,  "confidential_note_events":  true,  "job_events":  true,  "pipeline_events":  true,  "wiki_page_events":  true,  "enable_ssl_verification":  true,  "created_at":  "2012-10-12T17:04:47Z"  } 
```

### Add group hook[](#add-group-hook "Permalink")

将钩子添加到指定的组.

```
POST /groups/:id/hooks 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `url` | string | yes | 挂钩网址 |
| `push_events` | boolean | no | 在推送事件上触发钩子 |
| `issues_events` | boolean | no | 触发问题事件挂钩 |
| `confidential_issues_events` | boolean | no | 触发机密问题事件的钩子 |
| `merge_requests_events` | boolean | no | 触发合并请求事件的钩子 |
| `tag_push_events` | boolean | no | 触发标签推送事件的钩子 |
| `note_events` | boolean | no | 在音符事件上触发钩子 |
| `confidential_note_events` | boolean | no | 触发机密笔记事件的钩子 |
| `job_events` | boolean | no | 触发工作事件挂钩 |
| `pipeline_events` | boolean | no | 触发管道事件钩子 |
| `wiki_page_events` | boolean | no | 触发 Wiki 事件的钩子 |
| `enable_ssl_verification` | boolean | no | 触发挂钩时执行 SSL 验证 |
| `token` | string | no | 用于验证收到的有效载荷的秘密令牌； 这将不会在响应中返回 |

### Edit group hook[](#edit-group-hook "Permalink")

编辑指定组的挂钩.

```
PUT /groups/:id/hooks/:hook_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `hook_id` | integer | yes | 组挂钩的 ID |
| `url` | string | yes | 挂钩网址 |
| `push_events` | boolean | no | 在推送事件上触发钩子 |
| `issues_events` | boolean | no | 触发问题事件挂钩 |
| `confidential_issues_events` | boolean | no | 触发机密问题事件的钩子 |
| `merge_requests_events` | boolean | no | 触发合并请求事件的钩子 |
| `tag_push_events` | boolean | no | 触发标签推送事件的钩子 |
| `note_events` | boolean | no | 在音符事件上触发钩子 |
| `confidential_note_events` | boolean | no | 触发机密笔记事件的钩子 |
| `job_events` | boolean | no | 触发工作事件挂钩 |
| `pipeline_events` | boolean | no | 触发管道事件钩子 |
| `wiki_events` | boolean | no | 触发 Wiki 事件的钩子 |
| `enable_ssl_verification` | boolean | no | 触发挂钩时执行 SSL 验证 |
| `token` | string | no | 用于验证收到的有效载荷的秘密令牌； 这将不会在响应中返回 |

### Delete group hook[](#delete-group-hook "Permalink")

从组中删除钩子. 这是幂等方法，可以多次调用. 挂钩是否可用.

```
DELETE /groups/:id/hooks/:hook_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `hook_id` | integer | yes | 组挂钩的 ID. |

## Group Audit Events[](#group-audit-events-starter "Permalink")

可以通过" [组审核事件" API](audit_events.html#group-audit-events-starter)访问[组审核事件](audit_events.html#group-audit-events-starter)

## Sync group with LDAP[](#sync-group-with-ldap-starter "Permalink")

将组与其链接的 LDAP 组同步. 仅对组所有者和管理员可用.

```
POST /groups/:id/ldap_sync 
```

Parameters:

*   `id` （必填）-用户组的 ID 或路径

## Group members[](#group-members "Permalink")

请查阅[小组成员](members.html)文档.

## LDAP Group Links[](#ldap-group-links "Permalink")

列出，添加和删除 LDAP 组链接.

### List LDAP group links[](#list-ldap-group-links-starter "Permalink")

列出 LDAP 组链接.

```
GET /groups/:id/ldap_group_links 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |

### Add LDAP group link with CN or filter[](#add-ldap-group-link-with-cn-or-filter-starter "Permalink")

使用 CN 或过滤器添加 LDAP 组链接. 仅在高级级别和更高级别中，才支持通过过滤器添加组链接.

```
POST /groups/:id/ldap_group_links 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `cn` | string | no | LDAP 组的 CN |
| `filter` | string | no | 组的 LDAP 过滤器 |
| `group_access` | integer | yes | LDAP 组成员的最低[访问级别](members.html#valid-access-levels) |
| `provider` | string | yes | LDAP 组链接的 LDAP 提供程序 |

**注意：**要定义 LDAP 组链接，请提供`cn`或`filter` ，但不能同时提供两者.

### Delete LDAP group link[](#delete-ldap-group-link-starter "Permalink")

删除 LDAP 组链接. 不推荐使用. 在将来的版本中将被删除.

```
DELETE /groups/:id/ldap_group_links/:cn 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `cn` | string | yes | LDAP 组的 CN |

删除特定 LDAP 提供程序的 LDAP 组链接. 不推荐使用. 在将来的版本中将被删除.

```
DELETE /groups/:id/ldap_group_links/:provider/:cn 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `cn` | string | yes | LDAP 组的 CN |
| `provider` | string | yes | LDAP 组链接的 LDAP 提供程序 |

### Delete LDAP group link with CN or filter[](#delete-ldap-group-link-with-cn-or-filter-starter "Permalink")

使用 CN 或过滤器删除 LDAP 组链接. 仅高级级别和更高级别支持按过滤器删除.

```
DELETE /groups/:id/ldap_group_links 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `cn` | string | no | LDAP 组的 CN |
| `filter` | string | no | 组的 LDAP 过滤器 |
| `provider` | string | yes | LDAP 组链接的 LDAP 提供程序 |

**注意：**要删除 LDAP 组链接，请提供`cn`或`filter` ，但不能同时提供两者.

## Namespaces in groups[](#namespaces-in-groups "Permalink")

默认情况下，由于 API 结果是分页的，因此组一次只能获得 20 个名称空间.

要获得更多（最多 100 个），请将以下内容作为参数传递给 API 调用：

```
/groups?per_page=100 
```

并切换页面添加：

```
/groups?per_page=100&page=2 
```

## Group badges[](#group-badges "Permalink")

在[组徽章](group_badges.html)文档中了解更多信息.

## Group Import/Export[](#group-importexport "Permalink")

在[组导入/导出](group_import_export.html)文档中了解更多信息.

## Share Groups with Groups[](#share-groups-with-groups "Permalink")

这些端点创建和删除用于与另一个组共享一个组的链接. 有关更多信息，请参见[GitLab 组](../user/group/index.html#sharing-a-group-with-another-group)页面中的相关讨论.

### Create a link to share a group with another group[](#create-a-link-to-share-a-group-with-another-group "Permalink")

与另一个群组共享群组. 返回`200`和成功的[组详细信息](#details-of-a-group) .

```
POST /groups/:id/share 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `group_id` | integer | yes | 与之共享的组的 ID |
| `group_access` | integer | yes | 授予组的[访问级别](members.html#valid-access-levels) |
| `expires_at` | string | no | ISO 8601 格式的股份到期日：2016-09-26 |

### Delete link sharing group with another group[](#delete-link-sharing-group-with-another-group "Permalink")

取消与其他群组共享该群组. 返回`204` ，成功则不返回任何内容.

```
DELETE /groups/:id/share/:group_id 
```

| Attribute | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer/string | yes | 组的 ID 或[URL 编码的路径](README.html#namespaced-path-encoding) |
| `group_id` | integer | yes | 与之共享的组的 ID |