- 列出用户
- 获取单个用户
- 获取当前用户
- 创建用户
- 修改用户
- 删除用户
- 获取你的用户状态
- 获取用户状态
- 设置你的用户状态
- 获取你的用户偏好设置
- 更新您的用户偏好设置
- 为自己上传头像
- 获取您分配的议题、合并请求和评审的数量
- 获取用户的项目、群组、议题和合并请求的数量
- 列出用户的活动
- 列出用户所属的项目和群组
- 禁用用户的两因素身份验证
- 创建与用户关联的 Runner
- 从用户中删除身份验证身份
- 创建支持 PIN
- 获取支持 PIN 的详细信息
- 获取用户的支持 PIN
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: JihuLab.com, 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
你可以通过使用 REST API 来管理你的账户和管理其他用户。
列出用户
获取用户列表。
使用分页参数 page
和 per_page
来限制用户列表。
作为普通用户
{{< history >}}
- 在极狐GitLab 16.5 中引入了 Keyset 分页。
{{< /history >}}
GET /users
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
username |
string | 否 | 获取特定用户名的单个用户。 |
search |
string | 否 | 通过名称、用户名或公开邮箱搜索用户。 |
active |
boolean | 否 | 仅过滤活跃用户。默认值为 false 。 |
external |
boolean | 否 | 仅过滤外部用户。默认值为 false 。 |
blocked |
boolean | 否 | 仅过滤被封锁的用户。默认值为 false 。 |
humans |
boolean | 否 | 仅过滤不是机器人或内部用户的普通用户。默认值为 false 。 |
created_after |
DateTime | 否 | 返回指定时间后创建的用户。 |
created_before |
DateTime | 否 | 返回指定时间前创建的用户。 |
exclude_active |
boolean | 否 | 仅过滤非活跃用户。默认值为 false 。 |
exclude_external |
boolean | 否 | 仅过滤非外部用户。默认值为 false 。 |
exclude_humans |
boolean | 否 | 仅过滤机器人或内部用户。默认值为 false 。 |
exclude_internal |
boolean | 否 | 仅过滤非内部用户。默认值为 false 。 |
without_project_bots |
boolean | 否 | 过滤没有项目机器人的用户。默认值为 false 。 |
示例响应:
[
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"locked": false,
"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",
"locked": false,
"avatar_url": "http://gravatar.com/../e32131cd8.jpeg",
"web_url": "http://localhost:3000/jack_smith"
}
]
此端点支持keyset 分页。在极狐GitLab 17.0 及更高版本中,响应数量为 50,000 及以上时需要使用 keyset 分页。
你还可以使用 ?search=
来通过名称、用户名或公开邮箱搜索用户。例如,/users?search=John
。当你搜索:
- 公开邮箱时,必须使用完整的邮箱地址才能获得准确匹配。
- 名称或用户名时,不必获得准确匹配,因为这是模糊搜索。
此外,你可以通过用户名查找用户:
GET /users?username=:username
例如:
GET /users?username=jack_smith
{{< alert type=”note” >}}
用户名搜索不区分大小写。
{{< /alert >}}
此外,你可以根据状态 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
参数从用户列表中排除以下类型的内部用户:
- 警报机器人
- 支持机器人
GET /users?exclude_internal=true
此外,要从用户列表中排除外部用户,你可以使用参数 exclude_external=true
。
GET /users?exclude_external=true
要排除项目的机器人用户和群组的机器人用户,你可以使用参数 without_project_bots=true
。
GET /users?without_project_bots=true
作为管理员
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< history >}}
- 在极狐GitLab 15.6 中响应中的
created_by
字段被引入。 - 在极狐GitLab 16.1 中响应中的
scim_identities
字段被引入。 - 在极狐GitLab 16.2 中响应中的
auditors
字段被引入。 - 在极狐GitLab 16.7 中响应中的
email_reset_offered_at
字段被引入。
{{< /history >}}
GET /users
你可以使用所有为所有人提供的参数加上这些仅管理员可用的附加属性。
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
search |
string | 否 | 通过名称、用户名、公开邮箱或私人邮箱搜索用户。 |
extern_uid |
string | 否 | 获取具有特定外部认证提供者 UID 的单个用户。 |
provider |
string | 否 | 外部提供者。 |
order_by |
string | 否 | 按 id 、name 、username 、created_at 或 updated_at 字段排序返回用户。默认值为 id
|
sort |
string | 否 | 返回按 asc 或 desc 排序的用户。默认值为 desc
|
two_factor |
string | 否 | 按双因素认证过滤用户。过滤值为 enabled 或 disabled 。默认情况下返回所有用户 |
without_projects |
boolean | 否 | 过滤没有项目的用户。默认值为 false ,这意味着返回所有用户,包括有项目和没有项目的用户。 |
admins |
boolean | 否 | 仅返回管理员。默认值为 false
|
auditors |
boolean | 否 | 仅返回审计员用户。默认值为 false 。如果未包含,则返回所有用户。仅限专业版和旗舰版。 |
saml_provider_id |
number | 否 | 仅返回由指定的 SAML 提供者 ID 创建的用户。如果未包含,则返回所有用户。仅限专业版和旗舰版。 |
skip_ldap |
boolean | 否 | 跳过 LDAP 用户。仅限专业版和旗舰版。 |
示例响应:
[
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"locked": false,
"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,
"email_reset_offered_at": null
},
{
"id": 2,
"username": "jack_smith",
"email": "jack@example.com",
"name": "Jack Smith",
"state": "blocked",
"locked": false,
"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,
"email_reset_offered_at": 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
在极狐GitLab 专业版或旗舰版中的用户可以使用 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 | 是 | 用户的 ID |
示例响应:
{
"id": 1,
"username": "john_smith",
"name": "John Smith",
"state": "active",
"locked": false,
"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
}
作为管理员
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< history >}}
{{< /history >}}
作为管理员获取单个用户。
GET /users/:id
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | 是 | 用户的 ID |
示例响应:
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"locked": false,
"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,
"email_reset_offered_at": null
}
{{< alert type=”note” >}}
plan
和 trial
参数仅在极狐GitLab 企业版中可用。
{{< /alert >}}
在极狐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,
...
}
在JihuLab.com 专业版或旗舰版中的用户还可以看到 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
获取当前用户
获取当前用户。
作为普通用户
获取你的用户详细信息。
GET /user
示例响应:
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"locked": false,
"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
参数。
作为管理员
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< history >}}
{{< /history >}}
获取你的用户详细信息或其他用户的详细信息。
GET /user
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
sudo |
integer | 否 | 用户的 ID,用于替他们进行调用 |
{
"id": 1,
"username": "john_smith",
"email": "john@example.com",
"name": "John Smith",
"state": "active",
"locked": false,
"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,
"email_reset_offered_at": null,
"note": null
}
在极狐GitLab 专业版或旗舰版中的用户还可以看到这些参数:
shared_runners_minutes_limit
extra_shared_runners_minutes_limit
is_auditor
provisioned_by_group_id
using_license_seat
创建用户
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< history >}}
- 在极狐GitLab 15.3 中引入了创建审计员用户的能力。
{{< /history >}}
创建用户。
前提条件:
- 你必须是管理员。
当你创建用户时,必须至少指定以下之一:
password
reset_password
force_random_password
如果 reset_password
和 force_random_password
都为 false
,则 password
是必需的。
force_random_password
和 reset_password
优先于 password
。此外,reset_password
和 force_random_password
可以一起使用。
{{< alert type=”note” >}}
private_profile
默认为将新用户的个人资料默认设置为私有设置的值。bio
默认为 ""
而不是 null
。
{{< /alert >}}
POST /users
支持的属性:
属性 | 必需 | 描述 |
---|---|---|
admin |
否 | 用户是管理员。有效值为 true 或 false 。默认为 false。 |
auditor |
否 | 用户是审计员。有效值为 true 或 false 。默认为 false。在极狐GitLab 15.3 中引入。仅限专业版和旗舰版。 |
avatar |
否 | 用户头像的图像文件 |
bio |
否 | 用户的传记 |
can_create_group |
否 | 用户可以创建顶级群组 - true 或 false |
color_scheme_id |
否 | 用户的文件查看器配色方案(有关更多信息,请参阅用户偏好文档) |
commit_email |
否 | 用户的提交邮箱地址 |
email |
是 | 邮箱 |
extern_uid |
否 | 外部 UID |
external |
否 | 将用户标记为外部 - true 或 false(默认) |
extra_shared_runners_minutes_limit |
否 | 仅管理员可设置。为此用户设置的附加计算分钟数。仅限专业版和旗舰版。 |
force_random_password |
否 | 将用户密码设置为随机值 - true 或 false(默认) |
group_id_for_saml |
否 | 已配置 SAML 的群组 ID |
linkedin |
否 | |
location |
否 | 用户的位置 |
name |
是 | 名称 |
note |
否 | 管理员对该用户的备注 |
organization |
否 | 组织名称 |
password |
否 | 密码 |
private_profile |
否 | 用户的个人资料是私有的 - true 或 false。默认值由设置确定。 |
projects_limit |
否 | 用户可以创建的项目数 |
pronouns |
否 | 用户的代词 |
provider |
否 | 外部提供者名称 |
public_email |
否 | 用户的公开邮箱地址 |
reset_password |
否 | 发送用户密码重置链接 - true 或 false(默认) |
shared_runners_minutes_limit |
否 | 仅管理员可设置。为此用户设置的每月最大计算分钟数。可以为 nil (默认;继承系统默认值)、0 (无限制)或 > 0 。仅限专业版和旗舰版。 |
skip_confirmation |
否 | 跳过确认 - true 或 false(默认) |
skype |
否 | Skype ID |
theme_id |
否 | 用户的极狐GitLab 主题(有关更多信息,请参阅用户偏好文档) |
twitter |
否 | X(以前的 Twitter)账户 |
discord |
否 | Discord 账户 |
username |
是 | 用户名 |
view_diffs_file_by_file |
否 | 标记用户仅能看到每页一个文件的差异 |
website_url |
否 | 网站 URL |
修改用户
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
{{< history >}}
- 在极狐GitLab 15.3 中引入了修改审计员用户的能力。
{{< /history >}}
修改现有用户。
前提条件:
- 你必须是管理员。
email
字段是用户的主要邮箱地址。你只能将此字段更改为该用户已添加的次要邮箱地址。要向同一用户添加更多邮箱地址,请使用添加邮箱端点。
PUT /users/:id
支持的属性:
属性 | 必需 | 描述 |
---|---|---|
admin |
否 | 用户是管理员。有效值为 true 或 false 。默认为 false。 |
auditor |
否 | 用户是审计员。有效值为 true 或 false 。默认为 false。在极狐GitLab 15.3 中引入。(默认)仅限专业版和旗舰版。 |
avatar |
否 | 用户头像的图像文件 |
bio |
否 | 用户的传记 |
can_create_group |
否 | 用户可以创建群组 - true 或 false |
color_scheme_id |
否 | 用户的文件查看器配色方案(有关更多信息,请参阅用户偏好文档) |
commit_email |
否 | 用户的提交邮箱。设置为 _private 以使用私人提交邮箱。在极狐GitLab 15.5 中引入。 |
email |
否 | 邮箱 |
extern_uid |
否 | 外部 UID |
external |
否 | 将用户标记为外部 - true 或 false(默认) |
extra_shared_runners_minutes_limit |
否 | 仅管理员可设置。为此用户设置的附加计算分钟数。仅限专业版和旗舰版。 |
group_id_for_saml |
否 | 已配置 SAML 的群组 ID |
id |
是 | 用户的 ID |
linkedin |
否 | |
location |
否 | 用户的位置 |
name |
否 | 名称 |
note |
否 | 管理员对该用户的备注 |
organization |
否 | 组织名称 |
password |
否 | 密码 |
private_profile |
否 | 用户的个人资料是私有的 - true 或 false。 |
projects_limit |
否 | 每个用户可以创建的项目限制 |
pronouns |
否 | 代词 |
provider |
否 | 外部提供者名称 |
public_email |
否 | 用户的公开邮箱(必须已验证) |
shared_runners_minutes_limit |
否 | 仅管理员可设置。为此用户设置的每月最大计算分钟数。可以为 nil (默认;继承系统默认值)、0 (无限制)或 > 0 。仅限专业版和旗舰版。 |
skip_reconfirmation |
否 | 跳过重新确认 - true 或 false(默认) |
skype |
否 | Skype ID |
theme_id |
否 | 用户的极狐GitLab 主题(有关更多信息,请参阅用户偏好文档) |
twitter |
否 | X(以前的 Twitter)账户 |
discord |
否 | Discord 账户 |
username |
否 | 用户名 |
view_diffs_file_by_file |
否 | 标记用户仅能看到每页一个文件的差异 |
website_url |
否 | 网站 URL |
如果你更新用户的密码,他们将在下次登录时被迫更改密码。
返回 404
错误,即使在 409
(冲突)更合适的情况下也是如此。例如,将邮箱地址重命名为已存在的邮箱地址时。
删除用户
{{< details >}}
- Tier: Free, Premium, Ultimate
- Offering: 极狐GitLab 私有化部署, 极狐GitLab Dedicated
{{< /details >}}
删除用户。
前提条件:
- 你必须是管理员。
返回:
- 如果操作成功,返回
204 No Content
状态码。 - 如果未找到资源,返回
404
。 - 如果用户无法软删除,返回
409
。
DELETE /users/:id
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
integer | 是 | 用户的 ID |
hard_delete |
boolean | 否 | 如果为 true,则通常会被移动到幽灵用户的贡献将被删除,同时还包括仅由该用户拥有的群组。 |
获取你的用户状态
获取你的用户状态。
前提条件:
- 你必须经过身份验证。
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 | 是 | 要获取状态的用户的 ID 或用户名 |
示例请求:
curl "https://gitlab.example.com/users/<username>/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 | 否 | 用作状态的表情符号的名称。如果省略,则使用 speech_balloon 。表情符号名称可以是Gemojione 索引中指定的名称之一。 |
message |
string | 否 | 设置为状态的消息。它还可以包含表情符号代码。不能超过 100 个字符。 |
clear_status_after |
string | 否 | 在给定的时间间隔后自动清理状态,允许的值为: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 |
是 | 标志指示用户每页仅查看一个文件的差异。 |
show_whitespace_in_diffs |
是 | 标志指示用户在差异中查看空白更改。 |
pass_user_identities_to_ci_jwt |
是 | 标志指示用户将他们的外部身份传递为 CI 信息。此属性不包含足够的信息来识别或授权用户在外部系统中。该属性是极狐GitLab 内部的,不能传递给第三方服务。有关更多信息和示例,请参见令牌负载。 |
为自己上传头像
{{< history >}}
- 引入于极狐GitLab 17.0。
{{< /history >}}
为自己上传头像。
先决条件:
- 您必须经过身份验证。
PUT /user/avatar
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
avatar |
字符串 | 是 | 要上传的文件。理想的图像尺寸是 192 x 192 像素。允许的最大文件大小为 200 KiB。 |
要从您的文件系统上传头像,请使用 --form
参数。这会导致 cURL 使用标头 Content-Type: multipart/form-data
发布数据。 file=
参数必须指向您文件系统上的图像文件,并以 @
为前缀。例如:
请求示例:
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "avatar=@avatar.png" \
--url "https://gitlab.example.com/api/v4/user/avatar"
响应示例:
{
"avatar_url": "http://gdk.test:3000/uploads/-/system/user/avatar/76/avatar.png",
}
返回:
- 成功时返回
200
。 - 对于超过 200 KiB 的文件大小返回
400 Bad Request
。
获取您分配的议题、合并请求和评审的数量
获取您分配的议题、合并请求和评审的数量。
先决条件:
- 您必须经过身份验证。
支持的属性:
属性 | 类型 | 描述 |
---|---|---|
assigned_issues |
数字 | 打开并分配给当前用户的议题数量。 |
assigned_merge_requests |
数字 | 活跃并分配给当前用户的合并请求数量。 |
merge_requests |
数字 | 在极狐GitLab 13.8 中弃用。由 assigned_merge_requests 替代。 |
review_requested_merge_requests |
数字 | 当前用户被请求评审的合并请求数量。 |
todos |
数字 | 当前用户的待办事项数量。 |
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
}
获取用户的项目、群组、议题和合并请求的数量
获取用户的以下数量列表:
- 项目。
- 群组。
- 议题。
- 合并请求。
管理员可以查询任何用户,但非管理员只能查询自己。
GET /users/:id/associations_count
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数 | 是 | 用户的 ID |
响应示例:
{
"groups_count": 2,
"projects_count": 3,
"issues_count": 8,
"merge_requests_count": 5
}
列出用户的活动
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
先决条件:
- 您必须是管理员才能查看具有私人资料的用户的活动。
获取具有公共资料的用户的最后活动日期,从最旧到最新排序。
更新用户事件时间戳(last_activity_on
和 current_sign_in_at
)的活动是:
- Git HTTP/SSH 活动(如克隆、推送)
- 用户登录极狐GitLab
- 用户访问与仪表板、项目、议题和合并请求相关的页面
- 用户使用 API
- 用户使用 GraphQL API
默认情况下,它显示最近 6 个月内具有公共资料的用户的活动,但可以通过使用 from
参数进行修改。
GET /user/activities
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
from |
字符串 | 否 | 格式为 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
。
列出用户所属的项目和群组
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:私有化部署
{{< /details >}}
先决条件:
- 您必须是管理员。
列出用户所属的所有项目和群组。
返回成员关系的 source_id
、source_name
、source_type
和 access_level
。来源可以是 Namespace
类型(代表一个群组)或 Project
。响应仅代表直接成员关系。继承的成员关系,例如在子群组中,不包括在内。访问级别由整数值表示。有关详细信息,请阅读有关 访问级别值 的含义。
GET /users/:id/memberships
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数 | 是 | 指定用户的 ID |
type |
字符串 | 否 | 按类型过滤成员关系。可以是 Project 或 Namespace
|
请求示例:
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"
}
]
返回:
- 成功时返回
200 OK
。 - 如果找不到用户,返回
404 User Not Found
。 - 当请求者不是管理员时,返回
403 Forbidden
。 - 当请求的类型不受支持时,返回
400 Bad Request
。
禁用用户的两因素身份验证
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
{{< history >}}
- 引入于极狐GitLab 15.2。
{{< /history >}}
先决条件:
- 您必须是管理员。
为指定用户禁用两因素身份验证(2FA)。
管理员无法通过 API 禁用其自己的用户帐户或其他管理员的 2FA。相反,他们可以通过 使用 Rails 控制台 禁用管理员的 2FA。
PATCH /users/:id/disable_two_factor
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数 | 是 | 用户的 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
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:JihuLab.com,极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
创建与当前用户关联的 Runner。
先决条件:
- 您必须是管理员或具有目标命名空间或项目的所有者角色。
- 对于
instance_type
,您必须是极狐GitLab 实例的管理员。 - 对于具有所有者角色的
group_type
或project_type
,管理员不得启用 限制 Runner 注册。 - 具有
create_runner
范围的访问令牌。
请务必复制或保存响应中的 token
,该值无法再次检索。
POST /user/runners
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
runner_type |
字符串 | 是 | 指定 Runner 的范围;instance_type 、group_type 或 project_type 。 |
group_id |
整数 | 否 | Runner 创建所在群组的 ID。如果 runner_type 是 group_type ,则必需。 |
project_id |
整数 | 否 | Runner 创建所在项目的 ID。如果 runner_type 是 project_type ,则必需。 |
description |
字符串 | 否 | Runner 的描述。 |
paused |
布尔值 | 否 | 指定 Runner 是否应忽略新作业。 |
locked |
布尔值 | 否 | 指定 Runner 是否应锁定当前项目。 |
run_untagged |
布尔值 | 否 | 指定 Runner 是否应处理未标记的作业。 |
tag_list |
字符串数组 | 否 | Runner 标签列表。 |
access_level |
字符串 | 否 | Runner 的访问级别;not_protected 或 ref_protected 。 |
maximum_timeout |
整数 | 否 | 限制 Runner 可以运行作业的时间(以秒为单位)的最大超时。 |
maintenance_note |
字符串 | 否 | 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": "<access-token>",
"token_expires_at": null
}
从用户中删除身份验证身份
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:私有化部署
{{< /details >}}
使用与身份关联的提供者名称删除用户的身份验证身份。
先决条件:
- 您必须是管理员。
DELETE /users/:id/identities/:provider
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数 | 是 | 用户的 ID |
provider |
字符串 | 是 | 外部提供者名称 |
创建支持 PIN
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:JihuLab.com,极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
{{< history >}}
- 引入于极狐GitLab 17.8。
{{< /history >}}
为您的用户帐户创建支持 PIN。该 PIN 在创建后七天过期。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。
先决条件:
- 您必须经过身份验证。
POST /user/support_pin
请求示例:
curl --request POST |
--header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/user/support_pin"
响应示例:
{
"pin":"123456",
"expires_at":"2025-02-27T22:06:57Z"
}
获取支持 PIN 的详细信息
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:JihuLab.com,私有化部署
{{< /details >}}
{{< history >}}
- 引入于极狐GitLab 17.8。
{{< /history >}}
获取您的帐户的支持 PIN 的详细信息。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。
先决条件:
- 您必须经过身份验证。
GET /user/support_pin
请求示例:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/user/support_pin"
响应示例:
{
"pin":"123456",
"expires_at":"2025-02-27T22:06:57Z"
}
获取用户的支持 PIN
{{< details >}}
- 层级:基础版,专业版,旗舰版
- 提供:JihuLab.com,极狐GitLab 私有化部署,极狐GitLab 专属
{{< /details >}}
{{< history >}}
- 引入于极狐GitLab 17.8。
{{< /history >}}
获取指定用户的支持 PIN 的详细信息。极狐GitLab 支持可能会要求您提供此 PIN 来验证您的身份。
先决条件:
- 您必须是管理员。
GET /users/:id/support_pin
请求示例:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/1234/support_pin"
响应示例:
{
"pin":"123456",
"expires_at":"2025-02-27T22:06:57Z"
}
支持的属性:
属性 | 类型 | 必需 | 描述 |
---|---|---|---|
id |
整数 | 是 | 用户帐户的 ID |