用户 API

本文档包含有关用户 API 的 API 调用、参数和响应的信息。

有关更新用户事件时间戳的用户活动的信息，请参阅获取用户活动。

列出用户

获取用户列表。

此功能使用分页参数 page 和 per_page 限制用户列表。

对于非管理员用户 

GET /users
参数 类型 是否必需 描述
username string no 获取具有特定用户名的单个用户
extern_uid string no 获取具有特定外部身份验证提供商 UID 的单个用户
provider string no 外部供应商
search string no 搜索用户名
active boolean no 仅过滤活跃用户，默认值为 false
external boolean no 仅过滤外部用户，默认值为 false
exclude_external boolean no 仅过滤非外部用户，默认值为 false
blocked boolean no 仅过滤被屏蔽的用户，默认值为 false
created_after DateTime no 返回特定时间之后创建的用户
created_before DateTime no 返回特定时间之前创建的用户
exclude_internal boolean no 仅过滤非内部用户，默认值为 false
without_project_bots boolean no 过滤无项目机器人的用户，默认值为 false 
[
  {
    "id": 1,
    "username": "john_smith",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
    "web_url": "http://localhost:3000/john_smith"
  },
  {
    "id": 2,
    "username": "jack_smith",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
    "web_url": "http://localhost:3000/jack_smith"
  }
]

您还可以使用 ?search= 按姓名、用户名或公共电子邮件搜索用户。例如，/users?search=John。当您搜索：

  • 公共电子邮件，您必须使用完整的电子邮件地址才能完全匹配。搜索可能返回部分匹配。例如，如果您搜索电子邮件 on@example.com，则搜索可以同时返回 on@example.com 和 jon@example.com。
  • 姓名或用户名，您不必完全匹配，因为是模糊搜索。

此外，您可以通过用户名查找用户： 

GET /users?username=:username

例如： 

GET /users?username=jack_smith
note用户名称搜索区分大小写。

此外，您可以根据状态 blocked 和 active 过滤用户。 不支持 active=false 或 blocked=false。 

GET /users?active=true

GET /users?blocked=true

此外，您只能使用 external=true 搜索外部用户。 不支持external=false。 

GET /users?external=true

极狐GitLab 支持机器人用户，例如警报机器人或支持机器人。 您可以使用 exclude_internal=true 参数从用户列表中排除以下类型的内部用户（引入于 13.4）。

  • 警报机器人
  • 支持机器人

但是，此操作不排除项目的机器人用户或群组的机器人用户。 

GET /users?exclude_internal=true

此外，如果您要从用户列表中排除外部用户，您可以使用 exclude_external=true 参数。 

GET /users?exclude_external=true

为排除项目的机器人用户和群组的机器人用户，您可以使用 without_project_bots=true 参数。 

GET /users?without_project_bots=true

对于管理员

  • 响应中的 namespace_id 字段引入于极狐GitLab 14.10。
  • 响应中的 created_by 字段引入于极狐GitLab 15.6。
  • 响应中的 scim_identities 字段引入于极狐GitLab 16.1。 
GET /users

您可以使用所有适用于所有人的参数以及仅适用于管理员的附加参数。

参数 类型 是否必需 描述
order_by string no 返回按照 id、name、username、created_at 或 updated_at 字段排序的用户。 默认为 id
sort string no 返回按照 asc 或 desc 顺序排序的用户。默认为 desc
two_factor string no 根据双重身份验证过滤用户。过滤值为 enabled 或 disabled。默认返回所有用户
without_projects boolean no 过滤没有项目的用户。默认为 false，表明返回所有用户，不论其有没有项目
admins boolean no 仅返回管理员。默认为 false
saml_provider_id number no 仅返回使用特定 SAML 提供者 ID 创建的用户。如果未包括，则返回所有用户
skip_ldap boolean no 跳过 LDAP 用户 
[
  {
    "id": 1,
    "username": "john_smith",
    "email": "john@example.com",
    "name": "John Smith",
    "state": "active",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
    "web_url": "http://localhost:3000/john_smith",
    "created_at": "2012-05-23T08:00:58Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": "2012-06-01T11:41:01Z",
    "confirmed_at": "2012-05-23T09:05:22Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 2,
    "projects_limit": 100,
    "current_sign_in_at": "2012-06-02T06:36:55Z",
    "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
    ],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "196.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 1,
    "created_by": null
  },
  {
    "id": 2,
    "username": "jack_smith",
    "email": "jack@example.com",
    "name": "Jack Smith",
    "state": "blocked",
    "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg",
    "web_url": "http://localhost:3000/jack_smith",
    "created_at": "2012-05-23T08:01:01Z",
    "is_admin": false,
    "bio": "",
    "location": null,
    "skype": "",
    "linkedin": "",
    "twitter": "",
    "discord": "",
    "website_url": "",
    "organization": "",
    "job_title": "",
    "last_sign_in_at": null,
    "confirmed_at": "2012-05-30T16:53:06.148Z",
    "theme_id": 1,
    "last_activity_on": "2012-05-23",
    "color_scheme_id": 3,
    "projects_limit": 100,
    "current_sign_in_at": "2014-03-19T17:54:13Z",
    "identities": [],
    "can_create_group": true,
    "can_create_project": true,
    "two_factor_enabled": true,
    "external": false,
    "private_profile": false,
    "current_sign_in_ip": "10.165.1.102",
    "last_sign_in_ip": "172.127.2.22",
    "namespace_id": 2,
    "created_by": null
  }
]

极狐GitLab 专业版及旗舰版的用户也能看见 shared_runners_minutes_limit、extra_shared_runners_minutes_limit、is_auditor 和 using_license_seat 参数。 

[
  {
    "id": 1,
    ...
    "shared_runners_minutes_limit": 133,
    "extra_shared_runners_minutes_limit": 133,
    "is_auditor": false,
    "using_license_seat": true
    ...
  }
]

极狐GitLab 专业版及旗舰版的用户也能看见 group_saml 提供者选项和 provisioned_by_group_id 参数： 

[
  {
    "id": 1,
    ...
    "identities": [
      {"provider": "github", "extern_uid": "2435223452345"},
      {"provider": "bitbucket", "extern_uid": "john.smith"},
      {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
      {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
    ],
    "provisioned_by_group_id": 123789
    ...
  }
]

您还可以使用 ?search= 按姓名、用户名或电子邮件搜索用户。例如，/users?search=John。当您搜索：

  • 电子邮件，您必须使用完整的电子邮件地址才能进行完全匹配。作为管理员，您可以搜索公共和私人电子邮件地址。
  • 姓名或用户名，您不必完全匹配，因为是模糊搜索。

您可以使用外部 UID 和提供者查找用户： 

GET /users?extern_uid=:extern_uid&provider=:provider

例如： 

GET /users?extern_uid=1234567&provider=github

对于专业版或旗舰版的用户，scim 供应商可用。 

GET /users?extern_uid=1234567&provider=scim

您可以使用创建日期时间范围查找用户： 

GET /users?created_before=2001-01-02T00:00:00.060Z&created_after=1999-01-02T00:00:00.060

您可以使用 /users?without_projects=true 搜索没有项目的用户：

您可以使用以下内容通过自定义属性进行过滤： 

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

您可以使用以下内容在响应中包括用户的自定义属性： 

GET /users?with_custom_attributes=true

您可以使用 created_by 参数来查看是否创建了用户帐户：

如果返回值为 null，则该帐户是由自己注册帐户的用户创建的。

单个用户

获取单个用户。

对于用户 

GET /users/:id

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID 
{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "bot": false,
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "is_followed": false
}

对于管理员

  • 响应中的 namespace_id 字段引入于极狐GitLab 14.10。
  • 响应中的 created_by 字段引入于极狐GitLab 15.6。 
GET /users/:id

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID

响应示例： 

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": false,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "Operations Specialist",
  "pronouns": "he/him",
  "work_information": null,
  "followers": 1,
  "following": 1,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "note": "DMCA Request: 2018-11-05 | DMCA Violation | Abuse | https://gitlab.zendesk.com/agent/tickets/123",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "plan": "gold",
  "trial": true,
  "sign_in_count": 1337,
  "namespace_id": 1,
  "created_by": null
}
noteplan 和 trial 参数仅在收费版本中可用。

极狐GitLab 专业版及旗舰版的用户也能看见 shared_runners_minutes_limit、is_auditor 和 extra_shared_runners_minutes_limit 参数。 

{
  "id": 1,
  "username": "john_smith",
  "is_auditor": false,
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  ...
}

极狐GitLab 专业版及旗舰版的用户也能看见 group_saml 选项和 provisioned_by_group_id 参数： 

{
  "id": 1,
  "username": "john_smith",
  "shared_runners_minutes_limit": 133,
  "extra_shared_runners_minutes_limit": 133,
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john.smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"},
    {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10}
  ],
  "provisioned_by_group_id": 123789
  ...
}

JiHuLab.com 专业版或旗舰版的用户也可以查看 scim_identities 参数： 

{
  ...
  "extra_shared_runners_minutes_limit": null,
  "scim_identities": [
      {"extern_uid": "2435223452345", "group_id": "3", "active": true},
      {"extern_uid": "john.smith", "group_id": "42", "active": false}
    ]
  ...
}

管理员可以使用 created_by 参数查看是否创建了用户帐户：

如果返回值为 null，则该帐户是由自己注册帐户的用户创建的。

您可以使用以下内容在响应中包括用户的自定义属性： 

GET /users/:id?with_custom_attributes=true

用户创建

  • 响应中的 namespace_id 字段引入于极狐GitLab 14.10。
  • 创建审计员用户功能引入于极狐GitLab 15.3。

创建新用户。请注意，只有管理员可以创建新用户。 必须指定 password、reset_password 或 force_random_password。 如果 reset_password 和 force_random_password 都是 false，那么 password 是必需的。

force_random_password 和 reset_password 优先级高于 password。此外，reset_password 和 force_random_password 可以一起使用。

note从 12.1 起，private_profile 默认为 false。 从 15.8 起，private_profile 默认为此设置确定的值。
note从 13.2 起，bio 默认为 ""，而不是 null。
POST /users

参数：

参数 是否必需 描述
admin No 用户为管理员。有效值为 true 或 false，默认为 false
auditor No 用户是审计员。有效值为 true 或 false，默认为 false。引入于 15.3
avatar No 用户头像的图片文件
bio No 用户介绍
can_create_group No 用户可以创建顶级群组 - true 或 false
color_scheme_id No 用户的文件查看器的色彩方案（更多信息，请参见用户个人设置文档）
email Yes 电子邮件
extern_uid No 外部 UID
external No 将用户标记为外部 - 真或假（默认）
extra_shared_runners_minutes_limit No 仅可由管理员设置。此用户的额外计算分钟数
force_random_password No 将用户密码设置为任意值 - 真或假（默认）
group_id_for_saml No 配置 SAML 的群组的 ID
linkedin No 领英
location No 用户位置
name Yes 名称
note No 该用户的管理员备注
organization No 机构名称
password No 密码
private_profile No 用户的配置文件是私有的 - 真或假，默认值由此设置决定
projects_limit No 用户可以创建的项目数量
provider No 外部提供者名称
reset_password No 发送用户密码重置链接 - 真或假（默认）
shared_runners_minutes_limit No 仅可由管理员设置。该用户的最大月度计算分钟数。可以是 nil（默认；继承系统默认）、0（无限制）或 > 0
skip_confirmation No 跳过确认 - 真或假（默认）
skype No Skype ID
theme_id No 用户的极狐GitLab 主题（详情信息，请参见用户个人设置文档）
twitter No Twitter 账户
discord No Discord 账户
username Yes 用户名称
view_diffs_file_by_file No 表明用户每页只能看见一个文件差异的标志
website_url No 网页 URL

用户修改

  • 响应中的 namespace_id 字段引入于极狐GitLab 14.10。
  • 修改审计员用户功能引入于极狐GitLab 15.3。

修改现存用户。只有管理员可以修改用户的属性。

email 字段是用户的主要电子邮件地址。您只能将此字段更改为已为该用户添加的次要电子邮件地址。要为同一用户添加更多电子邮件地址，请使用添加电子邮件功能。 

PUT /users/:id

参数：

参数 是否必需 描述
admin No 用户为管理员，有效值为 true 或 false，默认为 false
auditor No 用户为审计员，有效值为 true 或 false，默认为 false。引入于 15.3（默认）
avatar No 用户头像的图片文件
bio No 用户介绍
can_create_group No 用户可以创建群组 - 真或假
color_scheme_id No 用户的文件查看器的色彩方案（详细信息，请参见用户个人设置文档）
commit_email No 用户的提交电子邮件。设置为 _private 以使用私人提交电子邮件。引入于 15.5
email No 电子邮件
extern_uid No 外部 UID
external No 将用户标记为外部 - 真或假（默认）
extra_shared_runners_minutes_limit No 仅可由管理员设置。此用户的额外计算分钟数
group_id_for_saml No 配置 SAML 的群组的 ID
id Yes 用户 ID
linkedin No 领英
location No 用户位置
name No 名称
note No 该用户的管理员备注
organization No 机构名称
password No 密码
private_profile No 用户的配置文件是私有的 - 真或假
projects_limit No 限制每个用户可以创建的项目
pronouns No 代词
provider No 外部供应者名称
public_email No 用户的公共电子邮件（必须已经过验证）
shared_runners_minutes_limit No 仅可由管理员设置。该用户的最大月度计算分钟数。可以是 nil（默认；继承系统默认）、0（无限制）或 > 0
skip_reconfirmation No 跳过重新确认 - 真或假（默认）
skype No Skype ID
theme_id No 用户的极狐GitLab 主题（参见用户个人设置文档）
twitter No Twitter 账户
discord No Discord 账户
username No 用户名
view_diffs_file_by_file No 表明用户每页只能看见一个文件差异的标志
website_url No 网址 URL

在密码更新时，用户必须在下次登录时更改密码。 注意，目前这个方法只返回一个 404 错误，即使在 409 （冲突）更合适的情况下。 例如，将电子邮件地址重命名为某个现有地址时。

删除用户的鉴权身份

使用与该身份关联的提供者名称删除用户的鉴权身份。仅管理员可用。 

DELETE /users/:id/identities/:provider

参数

参数 类型 是否必需 描述
id integer yes 用户 ID
provider string yes 外部提供者名称

用户删除

删除用户。仅管理员可用。 如果操作成功，则返回 204 No Content 状态码，如果找不到资源，则返回 404；如果无法软删除用户，则返回 409。 

DELETE /users/:id

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID
hard_delete boolean no 如果为真，则通常移至 Ghost 用户的贡献以及由该用户单独拥有的群组将被删除

列出当前用户

获取当前用户。

对于非管理员用户

获取经过身份验证的用户。 

GET /user

{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "pronouns": "he/him",
  "bot": false,
  "work_information": null,
  "followers": 0,
  "following": 0,
  "local_time": "3:38 PM",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "admin@example.com",
}

极狐GitLab 专业版及旗舰版的用户也能查看到 shared_runners_minutes_limit 和 extra_shared_runners_minutes_limit 参数。

对于管理员

  • 响应中的 namespace_id 字段引入于极狐GitLab 14.10。
  • 响应中的 created_by 字段引入于极狐GitLab 15.6。 
GET /user

参数：

参数 类型 是否必需 描述
sudo integer no 在其位置上进行调用的用户的 ID 
{
  "id": 1,
  "username": "john_smith",
  "email": "john@example.com",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg",
  "web_url": "http://localhost:3000/john_smith",
  "created_at": "2012-05-23T08:00:58Z",
  "is_admin": true,
  "bio": "",
  "location": null,
  "public_email": "john@example.com",
  "skype": "",
  "linkedin": "",
  "twitter": "",
  "discord": "",
  "website_url": "",
  "organization": "",
  "job_title": "",
  "last_sign_in_at": "2012-06-01T11:41:01Z",
  "confirmed_at": "2012-05-23T09:05:22Z",
  "theme_id": 1,
  "last_activity_on": "2012-05-23",
  "color_scheme_id": 2,
  "projects_limit": 100,
  "current_sign_in_at": "2012-06-02T06:36:55Z",
  "identities": [
    {"provider": "github", "extern_uid": "2435223452345"},
    {"provider": "bitbucket", "extern_uid": "john_smith"},
    {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}
  ],
  "can_create_group": true,
  "can_create_project": true,
  "two_factor_enabled": true,
  "external": false,
  "private_profile": false,
  "commit_email": "john-codes@example.com",
  "current_sign_in_ip": "196.165.1.102",
  "last_sign_in_ip": "172.127.2.22",
  "namespace_id": 1,
  "created_by": null,
  "note": null
}

极狐GitLab 专业版及旗舰版的用户也能看见以下参数：

  • shared_runners_minutes_limit
  • extra_shared_runners_minutes_limit
  • is_auditor
  • provisioned_by_group_id
  • using_license_seat

用户状态

获取经过身份验证的用户的状态。 

GET /user/status

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/status"

响应示例： 

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

获取用户状态

获取用户状态。此端点可无鉴权访问。 

GET /users/:id_or_username/status
参数 类型 是否必需 描述
id_or_username string yes 要获取状态的用户的 ID 或名称 
curl "https://gitlab.example.com/users/janedoe/status"

响应示例： 

{
  "emoji":"coffee",
  "availability":"busy",
  "message":"I crave coffee :coffee:",
  "message_html": "I crave coffee <gl-emoji title=\"hot beverage\" data-name=\"coffee\" data-unicode-version=\"4.0\">☕</gl-emoji>",
  "clear_status_at": null
}

设置用户状态

设置当前用户的状态。 

PUT /user/status
PATCH /user/status
参数 类型 是否必需 描述
emoji string no 用作状态的表情符号的名称。如果省略，则使用 speech_balloon。表情符号名称可以是 Gemojione index 中指定的名称
message string no 设置为状态的消息。也可以包含表情符号代码，不能超过 100 个字符
clear_status_after string no 一段时间后自动清理状态。允许的值为：30_minutes、3_hours、8_hours、1_day、3_days、7_days 和 30_days

PUT 和 PATCH 的区别。

使用 PUT 时，任何未传递的参数都将设置为 null 并因此被清除。使用 PATCH 时，任何未传递的参数都将被忽略。显式传递 null 以清除字段。 

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" --data "clear_status_after=1_day" --data "emoji=coffee" \
     --data "message=I crave coffee" "https://gitlab.example.com/api/v4/user/status"

响应示例： 

{
  "emoji":"coffee",
  "message":"I crave coffee",
  "message_html": "I crave coffee",
  "clear_status_at":"2021-02-15T10:49:01.311Z"
}

获取用户设置

获取经过身份验证的用户的个人设置列表。 

GET /user/preferences

响应示例： 

{
  "id": 1,
  "user_id": 1
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

参数：

  • 无

用户设置修改

更新当前用户的设置。 

PUT /user/preferences

{
  "id": 1,
  "user_id": 1
  "view_diffs_file_by_file": true,
  "show_whitespace_in_diffs": false,
  "pass_user_identities_to_ci_jwt": false
}

参数：

参数 是否必需 描述
view_diffs_file_by_file Yes 表明用户每页只能看见一处文件差异的标志
show_whitespace_in_diffs Yes 表明用户在差异中看见空白更改的标志
pass_user_identities_to_ci_jwt Yes 指示用户将其外部身份作为 CI 信息传递的标志。此参数不包含足够的信息来识别或授权外部系统中的用户。该参数是极狐GitLab 内部的，不得传递给第三方服务

用户关注

关注和取消关注用户

关注用户。 

POST /users/:id/follow

取消关注用户。 

POST /users/:id/unfollow
参数 类型 是否必需 描述
id integer yes 要关注的用户的 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/users/3/follow"

响应示例： 

{
  "id": 1,
  "username": "john_smith",
  "name": "John Smith",
  "state": "active",
  "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg",
  "web_url": "http://localhost:3000/john_smith"
}

粉丝和关注

获取用户粉丝。 

GET /users/:id/followers

获取被关注的用户的列表。 

GET /users/:id/following
参数 类型 是否必需 描述
id integer yes 要关注的用户的 ID 
curl --request GET --header "PRIVATE-TOKEN: <your_access_token>"  "https://gitlab.example.com/users/3/followers"

响应示例： 

[
  {
    "id": 2,
    "name": "Lennie Donnelly",
    "username": "evette.kilback",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/7955171a55ac4997ed81e5976287890a?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/evette.kilback"
  },
  {
    "id": 4,
    "name": "Serena Bradtke",
    "username": "cammy",
    "state": "active",
    "avatar_url": "https://www.gravatar.com/avatar/a2daad869a7b60d3090b7b9bef4baf57?s=80&d=identicon",
    "web_url": "http://127.0.0.1:3000/cammy"
  }
]

用户数量

获取经过身份验证的用户的数量（和右上角菜单中的一样）。

参数 类型 描述
assigned_issues number 开放并分配到当前用户的议题数量。添加于 14.2
assigned_merge_requests number 生效且分配到当前用户的合并请求的数量。添加于 13.8
merge_requests number 废弃于 13.8。相当于 assigned_merge_requests 并被其代替
review_requested_merge_requests number 当前用户被请求评审的合并请求的数量。添加于 13.8
todos number 当前用户的待办事项数量。添加于 14.2 
GET /user_counts

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/user_counts"

响应示例： 

{
  "merge_requests": 4,
  "assigned_issues": 15,
  "assigned_merge_requests": 11,
  "review_requested_merge_requests": 0,
  "todos": 1
}

创建服务账户用户

创建服务账户的功能引入于极狐GitLab 16.1。

使用自动生成的电子邮件地址和用户名创建服务账户用户。 

POST /service_accounts

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/service_accounts"

列出用户项目

请参见用户项目列表。

列出用户的关联数量

获取指定用户以下方面的数量列表

  • 项目
  • 群组
  • 议题
  • 合并请求

管理员可以查询任何用户的数据，非管理员只能查询自己的数据。 

GET /users/:id/associations_count

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID

响应示例： 

{
  "groups_count": 2,
  "projects_count": 3,
  "issues_count": 8,
  "merge_requests_count": 5
}

列出 SSH 密钥

获取经过身份验证的用户的 SSH 密钥列表。

该函数采用分页参数 page 和 per_page 来限制 key 列表。 

GET /user/keys

[
  {
    "id": 1,
    "title": "Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
  },
  {
    "id": 3,
    "title": "Another Public key",
    "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
    "created_at": "2014-08-01T14:47:39.080Z"
  }
]

参数：

  • 无

列出用户的 SSH 密钥

获取特定用户的 SSH 密钥列表。 

GET /users/:id_or_username/keys
参数 类型 是否必需 描述
id_or_username string yes 要为其获取 SSH 密钥的用户的 ID 或用户名

单个 SSH 密钥

获取单个密钥。 

GET /user/keys/:key_id

参数：

参数 类型 是否必需 描述
key_id string yes SSH 密钥 ID 
{
  "id": 1,
  "title": "Public key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
}

特定用户的单个 SSH 密钥

引入于极狐GitLab 14.9。

获取特定用户的单个密钥。 

GET /users/:id/keys/:key_id

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID
key_id integer yes SSH 密钥 ID 
{
  "id": 1,
  "title": "Public key",
  "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt4596k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=",
  "created_at": "2014-08-01T14:47:39.080Z"
}

添加 SSH 密钥

usage_type 参数引入于极狐GitLab 15.7。

创建经过身份验证的用户拥有的新密钥。 

POST /user/keys

参数：

参数 类型 是否必需 描述
title string yes 新 SSH 密钥的标题
key string yes 新 SSH 密钥
expires_at string no SSH 密钥的过期日期，格式为 ISO 8601（YYYY-MM-DDTHH:MM:SSZ）
usage_type string no SSH 密钥的使用范围：auth、signing 或 auth_and_signing。默认值：auth_and_signing 
{
  "title": "ABC",
  "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
  "expires_at": "2016-01-21T00:00:00.000Z",
  "usage_type": "auth"
}

成功时返回状态为 201 Created 的创建密钥。如果发生错误时会返回 400 Bad Request，并带有错误消息： 

{
  "message": {
    "fingerprint": [
      "has already been taken"
    ],
    "key": [
      "has already been taken"
    ]
  }
}

为用户添加 SSH 密钥

usage_type 参数引入于极狐GitLab 15.7。

创建特定用户拥有的新密钥。仅管理员可用。 

POST /users/:id/keys

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID
title string yes 新 SSH 密钥的标题
key string yes 新 SSH 密钥
expires_at string no SSH 密钥的过期日期，格式为 ISO 8601（YYYY-MM-DDTHH:MM:SSZ）
usage_type string no SSH 密钥的使用范围：auth、signing 或 auth_and_signing。默认值：auth_and_signing 
{
  "title": "ABC",
  "key": "ssh-dss AAAAB3NzaC1kc3MAAACBAMLrhYgI3atfrSD6KDas1b/3n6R/HP+bLaHHX6oh+L1vg31mdUqK0Ac/NjZoQunavoyzqdPYhFz9zzOezCrZKjuJDS3NRK9rspvjgM0xYR4d47oNZbdZbwkI4cTv/gcMlquRy0OvpfIvJtjtaJWMwTLtM5VhRusRuUlpH99UUVeXAAAAFQCVyX+92hBEjInEKL0v13c/egDCTQAAAIEAvFdWGq0ccOPbw4f/F8LpZqvWDydAcpXHV3thwb7WkFfppvm4SZte0zds1FJ+Hr8Xzzc5zMHe6J4Nlay/rP4ewmIW7iFKNBEYb/yWa+ceLrs+TfR672TaAgO6o7iSRofEq5YLdwgrwkMmIawa21FrZ2D9SPao/IwvENzk/xcHu7YAAACAQFXQH6HQnxOrw4dqf0NqeKy1tfIPxYYUZhPJfo9O0AmBW2S36pD2l14kS89fvz6Y1g8gN/FwFnRncMzlLY/hX70FSc/3hKBSbH6C6j8hwlgFKfizav21eS358JJz93leOakJZnGb8XlWvz1UJbwCsnR2VEY8Dz90uIk1l/UqHkA= loic@call",
  "expires_at": "2016-01-21T00:00:00.000Z",
  "usage_type": "auth"
}

成功时返回状态为 201 Created 的已创建密钥。 如果发生错误，则返回 400 Bad Request，并附有解释错误的消息： 

{
  "message": {
    "fingerprint": [
      "has already been taken"
    ],
    "key": [
      "has already been taken"
    ]
  }
}
note也会添加审计实例事件中描述的审计事件。

删除当前用户的 SSH 密钥

删除经过身份验证的用户拥有的密钥。 如果成功，返回 204 No Content 状态码；如未找到资源，返回 404。 

DELETE /user/keys/:key_id

参数：

参数 类型 是否必需 描述
key_id integer yes SSH 密钥 ID

删除特定用户的 SSH 密钥

删除特定用户拥有的密钥。仅管理员可用。 

DELETE /users/:id/keys/:key_id

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID
key_id integer yes SSH 密钥 ID

列出所有 GPG 密钥

获取经过身份验证的用户的 GPG 密钥的列表。 

GET /user/gpg_keys

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys"

响应示例： 

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

获取特定 GPG 密钥

获取经过身份验证的用户的特定 GPG 密钥。 

GET /user/gpg_keys/:key_id

参数：

参数 类型 是否必需 描述
key_id integer yes GPG 密钥 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"

响应示例： 

  {
      "id": 1,
      "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
      "created_at": "2017-09-05T09:17:46.264Z"
  }

添加 GPG 密钥

创建经过身份验证的用户拥有的新 GPG 密钥。 

POST /user/gpg_keys

参数：

参数 类型 是否必需 描述
key string yes 新的 GPG 密钥 

export KEY="$( gpg --armor --export <your_gpg_key_id>)"

curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK-----
> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj
> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O
> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa
> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO
> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57
> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp
> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV
> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/
> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5
> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4
> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn
> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp
> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=
> =XQoy
> -----END PGP PUBLIC KEY BLOCK-----" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys"

响应示例： 

[
  {
    "id": 1,
    "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----",
    "created_at": "2017-09-05T09:17:46.264Z"
  }
]

删除 GPG 密钥

删除当前经过身份验证的用户拥有的 GPG 密钥。 

DELETE /user/gpg_keys/:key_id

参数：

参数 类型 是否必需 描述
key_id integer yes GPG 密钥 ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/gpg_keys/1"

如果成功，则返回 204 No Content；如果无法找到密钥，则返回 404 Not Found。

列出特定用户的所有 GPG 密钥

获取特定用户的 GPG 密钥的列表。此端点可以未授权访问。 

GET /users/:id/gpg_keys

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys"

响应示例： 

[
    {
        "id": 1,
        "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
        "created_at": "2017-09-05T09:17:46.264Z"
    }
]

获取特定用户的特定 GPG 密钥

获取特定用户的特定 GPG 密钥。引入于 13.5。此端点可以无管理员授权即可访问。 

GET /users/:id/gpg_keys/:key_id

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID
key_id integer yes GPG 密钥 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"

响应示例： 

  {
      "id": 1,
      "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\r\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\r\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\r\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\r\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\r\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\r\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\r\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\r\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\r\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\r\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\r\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\r\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\r\n=XQoy\r\n-----END PGP PUBLIC KEY BLOCK-----",
      "created_at": "2017-09-05T09:17:46.264Z"
  }

为特定用户添加 GPG 密钥

创建特定用户拥有的新 GPG 密钥。仅管理员可用。 

POST /users/:id/gpg_keys

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID
key_id integer yes GPG 密钥 ID 
curl --data-urlencode "key=-----BEGIN PGP PUBLIC KEY BLOCK-----
> xsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj
> t1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O
> CfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa
> qKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO
> VaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57
> vilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp
> IDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV
> CAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/
> oO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5
> crfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4
> bjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn
> iE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp
> o4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=
> =XQoy
> -----END PGP PUBLIC KEY BLOCK-----" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys"

响应示例： 

[
  {
    "id": 1,
    "key": "-----BEGIN PGP PUBLIC KEY BLOCK-----\nxsBNBFVjnlIBCACibzXOLCiZiL2oyzYUaTOCkYnSUhymg3pdbfKtd4mpBa58xKBj\nt1pTHVpw3Sk03wmzhM/Ndlt1AV2YhLv++83WKr+gAHFYFiCV/tnY8bx3HqvVoy8O\nCfxWhw4QZK7+oYzVmJj8ZJm3ZjOC4pzuegNWlNLCUdZDx9OKlHVXLCX1iUbjdYWa\nqKV6tdV8hZolkbyjedQgrpvoWyeSHHpwHF7yk4gNJWMMI5rpcssL7i6mMXb/sDzO\nVaAtU5wiVducsOa01InRFf7QSTxoAm6Xy0PGv/k48M6xCALa9nY+BzlOv47jUT57\nvilf4Szy9dKD0v9S0mQ+IHB+gNukWrnwtXx5ABEBAAHNFm5hbWUgKGNvbW1lbnQp\nIDxlbUBpbD7CwHUEEwECACkFAlVjnlIJEINgJNgv009/AhsDAhkBBgsJCAcDAgYV\nCAIJCgsEFgIDAQAAxqMIAFBHuBA8P1v8DtHonIK8Lx2qU23t8Mh68HBIkSjk2H7/\noO2cDWCw50jZ9D91PXOOyMPvBWV2IE3tARzCvnNGtzEFRtpIEtZ0cuctxeIF1id5\ncrfzdMDsmZyRHAOoZ9VtuD6mzj0ybQWMACb7eIHjZDCee3Slh3TVrLy06YRdq2I4\nbjMOPePtK5xnIpHGpAXkB3IONxyITpSLKsA4hCeP7gVvm7r7TuQg1ygiUBlWbBYn\niE5ROzqZjG1s7dQNZK/riiU2umGqGuwAb2IPvNiyuGR3cIgRE4llXH/rLuUlspAp\no4nlxaz65VucmNbN1aMbDXLJVSqR1DuE00vEsL1AItI=\n=XQoy\n-----END PGP PUBLIC KEY BLOCK-----",
    "created_at": "2017-09-05T09:17:46.264Z"
  }
]

删除特定用户的 GPG 密钥

删除特定用户的 GPG 密钥。仅对管理员可用。 

DELETE /users/:id/gpg_keys/:key_id

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID
key_id integer yes GPG 密钥 ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/2/gpg_keys/1"

列出电子邮件

获取经过身份验证的用户电子邮件的列表。

note此端点当前不返回主要电子邮件地址。
GET /user/emails

[
  {
    "id": 1,
    "email": "email@example.com",
    "confirmed_at" : "2021-03-26T19:07:56.248Z"
  },
  {
    "id": 3,
    "email": "email2@example.com",
    "confirmed_at" : null
  }
]

参数：

  • 无

列出用户的电子邮件

获取特定用户电子邮件的列表。仅管理员可用。

note此端点不返回主要电子邮件地址。
GET /users/:id/emails

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID

单个电子邮件

获取单个电子邮件。 

GET /user/emails/:email_id

参数：

参数 类型 是否必需 描述
email_id integer yes 电子邮件 ID 
{
  "id": 1,
  "email": "email@example.com",
  "confirmed_at" : "2021-03-26T19:07:56.248Z"
}

”

添加电子邮件

创建经过身份验证的用户拥有的新电子邮件。 

POST /user/emails

参数：

参数 类型 是否必需 描述
email string yes 电子邮件地址 
{
  "id": 4,
  "email": "email@example.com",
  "confirmed_at" : "2021-03-26T19:07:56.248Z"
}

如果成功，则返回创建的电子邮件，并带有状态码 201 Created。如果出现错误，则返回 400 Bad Request 和带有错误原因的消息： 

{
  "message": {
    "email": [
      "has already been taken"
    ]
  }
}

为用户添加电子邮件

创建特定用户拥有的新电子邮件。仅管理员可用。 

POST /users/:id/emails

参数：

参数 类型 是否必需 描述
id string yes 特定用户的 ID
email string yes 电子邮件地址
skip_confirmation boolean no 跳过确认并假设电子邮件已经过验证 - 真或假（默认）

删除当前用户的电子邮件地址

删除经过身份验证的用户拥有的电子邮件地址。

如果成功，则返回 204 No Content 状态码；如果未找到资源，则返回 404。

无法删除主要电子邮件地址。 

DELETE /user/emails/:email_id

参数：

参数 类型 是否必需 描述
email_id integer yes 电子邮件 ID

删除特定用户的电子邮件

先决条件：

  • 您必须是私有化部署的极狐GitLab 实例的管理员。

删除特定用户拥有的电子邮件地址。无法删除主要电子邮件地址。 

DELETE /users/:id/emails/:email_id

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID
email_id integer yes 电子邮件 ID

禁用用户

禁用特定用户。仅管理员可用。 

POST /users/:id/block

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID

返回：

  • 成功：201 OK
  • 无法找到用户：404 User Not Found
  • 禁用用户：403 Forbidden
    • 用户通过 LDAP 被禁用
    • 内部用户

取消禁用用户

取消禁用特定用户。仅管理员可用。 

POST /users/:id/unblock

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID

如果成功，则返回 201 OK；如果无法找到用户，则返回 404 User Not Found；如果取消禁用通过 LDAP 同步禁用的用户，则返回 403 Forbidden。

冻结用户

引入于极狐GitLab 12.4。

冻结特定用户。仅管理员可用。 

POST /users/:id/deactivate

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID

返回：

  • 成功：201 OK
  • 无法找到用户：404 User Not Found
  • 冻结以下用户：403 Forbidden：
    • 被管理员或被 LDAP 同步禁用的用户
    • 非休眠的用户
    • 内部的用户

激活用户

引入于极狐GitLab 12.4。

激活特定用户。仅管理员可用。 

POST /users/:id/activate

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID

返回：

  • 成功：201 OK
  • 无法找到用户：404 User Not Found
  • 用户因为被管理员或 LDAP 同步禁用而无法激活：403 Forbidden

封禁用户

引入于极狐GitLab 14.3。

封禁特定用户。仅管理员可用。 

POST /users/:id/ban

参数：

  • id （必需）- 特定用户的 ID

返回：

  • 成功：201 OK
  • 无法找到用户：404 User Not Found
  • 试图封禁未激活的用户：403 Forbidden

解禁用户

引入于极狐GitLab 14.3。

解禁特定用户。仅管理员可用。 

POST /users/:id/unban

参数：

  • id（必需）- 特定用户的 ID

返回：

  • 成功：201 OK
  • 无法找到用户：404 User Not Found
  • 试图解禁未封禁的用户：403 Forbidden

获取用户贡献事件

详情请参见事件 API 文档。

获取用户的所有模拟令牌

需要管理员访问权限。

检索用户的每个模拟令牌。使用分页参数 page 和 per_page 来限制模拟令牌列表。 

GET /users/:user_id/impersonation_tokens

参数：

参数 类型 是否必需 描述
user_id integer yes 用户 ID
state string no 根据状态过滤令牌（all、active、inactive） 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

响应示例： 

[
   {
      "active" : true,
      "user_id" : 2,
      "scopes" : [
         "api"
      ],
      "revoked" : false,
      "name" : "mytoken",
      "id" : 2,
      "created_at" : "2017-03-17T17:18:09.283Z",
      "impersonation" : true,
      "expires_at" : "2017-04-04"
   },
   {
      "active" : false,
      "user_id" : 2,
      "scopes" : [
         "read_user"
      ],
      "revoked" : true,
      "name" : "mytoken2",
      "created_at" : "2017-03-17T17:19:28.697Z",
      "id" : 3,
      "impersonation" : true,
      "expires_at" : "2017-04-14"
   }
]

批准用户

引入于极狐GitLab 13.7。

批注特定用户。仅管理员可用。 

POST /users/:id/approve

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/approve"

返回：

  • 成功：201 Created
  • 无法找到用户：404 User Not Found
  • 用户因为被管理员或 LDAP 同步禁用而无法获得批准：403 Forbidden
  • 用户被冻结：409 Conflict

响应示例： 

{ "message": "Success" }

{ "message": "404 User Not Found" }

{ "message": "The user you are trying to approve is not pending approval" }

拒绝用户

引入于极狐GitLab 14.3。

拒绝待批准的特定用户。仅管理员可用。 

POST /users/:id/reject

参数：

  • id（必需）- 特定用户的 ID 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/reject"

返回：

  • 成功：200 OK
  • 未鉴权为管理员：403 Forbidden
  • 无法找到用户：404 User Not Found
  • 用户未待批准：409 Conflict

响应示例： 

{ "message": "Success" }

{ "message": "404 User Not Found" }

{ "message": "User does not have a pending request" }

获取用户的模拟令牌

需要管理员权限。

显示用户的模拟令牌。 

GET /users/:user_id/impersonation_tokens/:impersonation_token_id

参数：

参数 类型 是否必需 描述
user_id integer yes 用户 ID
impersonation_token_id integer yes 模拟令牌 ID 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2"

响应示例： 

{
   "active" : true,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "revoked" : false,
   "name" : "mytoken",
   "id" : 2,
   "created_at" : "2017-03-17T17:18:09.283Z",
   "impersonation" : true,
   "expires_at" : "2017-04-04"
}

创建模拟令牌

需要管理员访问权限。令牌值仅返回一次，请正确保存，因为只能获取一次。

创建新的模拟令牌。仅管理员可用。 您只能创建模拟令牌来模拟用户并执行 API 调用和 Git 读写。用户在他们的个人资料设置页面中看不到这些令牌。 

POST /users/:user_id/impersonation_tokens
参数 类型 是否必需 描述
user_id integer yes 用户 ID
name string yes 模拟令牌的名称
expires_at date no 模拟令牌的过期日期，格式为 ISO（YYYY-MM-DD）
scopes array yes 模拟令牌的范围数组（api、read_user） 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens"

响应示例： 

{
   "id" : 2,
   "revoked" : false,
   "user_id" : 2,
   "scopes" : [
      "api"
   ],
   "token" : "EsMo-vhKfXGwX9RKrwiy",
   "active" : true,
   "impersonation" : true,
   "name" : "mytoken",
   "created_at" : "2017-03-17T17:18:09.283Z",
   "expires_at" : "2017-04-04"
}

撤回模拟令牌

需要管理员访问权限。

撤回模拟令牌。 

DELETE /users/:user_id/impersonation_tokens/:impersonation_token_id

参数：

参数 类型 是否必需 描述
user_id integer yes 用户 ID
impersonation_token_id integer yes 模拟令牌 ID 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/42/impersonation_tokens/1"

创建个人访问令牌

  • 引入于极狐GitLab 13.6。
  • 功能标志移动于极狐GitLab 13.8。

使用此 API 创建新的个人访问令牌。令牌值仅返回一次，请正确保存，因为只能获取一次。此 API 仅供极狐GitLab 管理员使用。 

POST /users/:user_id/personal_access_tokens
参数 类型 是否必需 描述
user_id integer yes 用户 ID
name string yes 个人访问令牌名称
expires_at date no 访问令牌的过期日期，格式为 ISO（YYYY-MM-DD）。如果未设置日期，则到期时间将设置为访问令牌的最大允许生命周期
scopes array yes 个人访问令牌的范围数组。可能的值请参见个人访问令牌范围 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" \
     --data "scopes[]=api" "https://gitlab.example.com/api/v4/users/42/personal_access_tokens"

响应示例： 

{
    "id": 3,
    "name": "mytoken",
    "revoked": false,
    "created_at": "2020-10-14T11:58:53.526Z",
    "scopes": [
        "api"
    ],
    "user_id": 42,
    "active": true,
    "expires_at": "2020-12-31",
    "token": "ggbfKkC4n-Lujy8jwCR2"
}

获取用户活动

先决条件：

  • 您必须是管理员。

获取所有用户的最后活动日期，从最旧到最新排序。

更新用户事件时间戳的活动（last_activity_on 和 current_sign_in_at）是：

  • Git HTTP/SSH 活动（例如克隆、推送）
  • 用户登录极狐GitLab
  • 用户访问与仪表板、项目、议题和合并请求相关的页面（引入于 11.8）
  • 使用 API 的用户
  • 使用 GraphQL API 的用户

默认情况下，显示过去 6 个月内所有用户的活动，但可以使用 from 参数进行修改。 

GET /user/activities

参数：

参数 类型 是否必需 描述
from string no 日期字符串，格式为：YEAR-MM-DD。例如：2016-03-11。默认为 6 个月前 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/activities"

响应示例： 

[
  {
    "username": "user1",
    "last_activity_on": "2015-12-14",
    "last_activity_at": "2015-12-14"
  },
  {
    "username": "user2",
    "last_activity_on": "2015-12-15",
    "last_activity_at": "2015-12-15"
  },
  {
    "username": "user3",
    "last_activity_on": "2015-12-16",
    "last_activity_at": "2015-12-16"
  }
]

last_activity_at 已废弃，使用 last_activity_on 代替。

用户成员资格

引入于极狐GitLab 12.8。

先决条件：

  • 您必须是管理员。

列出用户所属的所有项目和群组。 返回成员资格的 source_id、source_name、source_type 和 access_level。 源可以是 Namespace（代表一个群组）或 Project 类型。响应仅代表直接成员资格。不包括继承的成员资格，例如子群组中的成员资格。 访问级别由整数值表示。有关更多详细信息，请阅读访问级别值。 

GET /users/:id/memberships

参数：

参数 类型 是否必需 描述
id integer yes 特定用户的 ID
type string no 按照类型过滤成员资格。可以是 Project 或 Namespace

返回：

  • 成功：200 OK
  • 无法找到用户：404 User Not Found
  • 不被管理员请求：403 Forbidden
  • 不支持请求类型：400 Bad Request 
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/:user_id/memberships"

响应示例： 

[
  {
    "source_id": 1,
    "source_name": "Project one",
    "source_type": "Project",
    "access_level": "20"
  },
  {
    "source_id": 3,
    "source_name": "Group three",
    "source_type": "Namespace",
    "access_level": "20"
  }
]

禁用双重身份验证

引入于极狐GitLab 15.2。

先决条件：

  • 您必须是管理员。

为指定用户禁用双重身份验证 (2FA)。

管理员不能为自己的用户帐户或使用 API 的其他管理员禁用 2FA。 

PATCH /users/:id/disable_two_factor

参数：

参数 类型 是否必需 描述
id integer yes 用户 ID 
curl --request PATCH --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1/disable_two_factor"

返回：

  • 204 No content：成功
  • 400 Bad request：特定用户未开启双重身份验证
  • 403 Forbidden：未鉴权为管理员
  • 404 User Not Found：无法找到用户

创建 Runner

创建链接到当前用户的 Runner。

先决条件：

  • 您必须是管理员或具有目标命名空间或项目的所有者角色。
  • 对于 instance_type，您必须是极狐GitLab 实例的管理员。
  • 具有 create_runner 范围的访问令牌。

请务必复制或保存响应中的 token，因为该值无法再次检索。 

POST /user/runners
参数 类型 是否必需 描述
runner_type string yes 指定 Runner 的范围； instance_type、group_type 或 project_type
group_id integer no 在其中创建 Runner 的群组的 ID。如果 runner_type 为 group_type，则必填
project_id integer no 在其中创建 Runner 的项目的 ID。如果 runner_type 为 project_type，则必填
description string no Runner 描述
paused boolean no 指定 Runner 是否应该忽略新作业
locked boolean no 指定是否应为当前项目锁定 Runner
run_untagged boolean no 指定 Runner 是否应处理未打标签的作业
tag_list string array no Runner 标签列表
access_level string no Runner 的访问级别：not_protected 或 ref_protected
maximum_timeout integer no 限制 Runner 可以运行作业的时间量（以秒为单位）的最大超时时间
maintenance_note string no Runner 的自由格式的维护说明（1024 个字符） 
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "runner_type=instance_type" \
     "https://gitlab.example.com/api/v4/user/runners"

响应示例： 

{
    "id": 9171,
    "token": "glrt-kyahzxLaj4Dc1jQf4xjX",
    "token_expires_at": null
}