Groups API · Gitlab 中文文檔

# 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 |