用户 API

您可以通过使用 REST API 来管理您的账号和管理其他用户。

列出用户

获取用户列表。

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

常规用户

  • Keyset 分页引入于极狐GitLab 16.5。
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
humans boolean no 仅过滤非机器人或内部用户。默认为 false
created_after DateTime no 返回特定时间之后创建的用户
created_before DateTime no 返回特定时间之前创建的用户
exclude_humans boolean no 仅过滤机器人或内部用户。默认为 false
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

对于管理员

  • 响应中的 created_by 字段引入于极狐GitLab 15.6。
  • 响应中的 scim_identities 引入于极狐GitLab 16.1。
  • 响应中的 auditors 引入于极狐GitLab 16.2。
  • 响应中的 email_reset_offered_at 引入于极狐GitLab 16.7。
GET /users

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

参数 类型 是否必需 描述
extern_uid string no 获取具有特定外部认证提供商 ID 的单个用户。
provider string no 外部提供商
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
auditors 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
}

管理员

  • 响应中的 created_by 字段引入于极狐GitLab 15.6。
  • 响应中的 email_reset_offered_at 字段引入于极狐GitLab 16.7。

以管理员获取单个用户：

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
}
note plan 和 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

获取当前用户

获取当前用户。

常规用户

获取您的用户详情。

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 参数。

管理员

  • 响应中的 created_by 字段引入于极狐GitLab 15.6。
  • 响应中的 email_reset_offered_at 字段引入于极狐GitLab 16.7。

获取您的用户详情，或获取其他用户的详情。

GET /user

支持的参数：

属性 类型 是否必需 描述
sudo integer no 代其发起调用的用户 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

用户创建

  • 创建审计员用户功能引入于极狐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 private_profile 默认为默认设置新用户的个人资料 设置的值。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 用户可以创建的项目数量
pronouns No Pronouns
provider No 外部提供者名称
public_email No 用户的公共邮箱（必须是已经验证过的）
reset_password No 发送用户密码重置链接 - 真或假（默认）
shared_runners_minutes_limit No 仅可由管理员设置。该用户的最大月度计算分钟数。可以是 nil（默认；继承系统默认）、0（无限制）或 > 0
skip_confirmation No 跳过确认 - 真或假（默认）
skype No Skype ID
theme_id No 用户的极狐GitLab 主题（详情信息，请参见用户个人设置文档）
username Yes 用户名称
view_diffs_file_by_file No 表明用户每页只能看见一个文件差异的标志
website_url No 网页 URL

用户修改

  • 修改审计员用户功能引入于极狐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 主题（参见用户个人设置文档）
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 内部的，不得传递给第三方服务

上传您的头像

  • 引入于极狐GitLab 17.0。

上传您的头像。

先决条件：

  • 您必须是认证过的。
PUT /user/avatar

支持的参数：

属性 类型 是否必需 描述
avatar string Yes 上传的文件。理想的尺寸是 192 x 192 pixels。允许的最大文件为 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：如果成功。
  • 400 Bad Request：如果文件尺寸超过 200 KiB。

获取您分配的议题、合并请求和审核的数量

获取您分配的议题、合并请求和审核的数量

先决条件：

  • 您必须是认证过的。

支持的参数：

Attribute Type Description
assigned_issues number 开放且被分配给当前用户的议题数量。
assigned_merge_requests number 活跃且被分配给当前用户的合并请求数量。
merge_requests number 在极狐GitLab 13.8 中弃用。等同于 assigned_merge_requests。
review_requested_merge_requests number 要求当前用户审核的合并请求数量。
todos number 当前用户等待的待办事项数量。 
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 integer yes 用户 ID

示例响应：

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

获取用户活动

先决条件：

  • 您必须是管理员。

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

更新用户事件时间戳的活动（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 代替。

列出用户作为成员的项目和群组

先决条件：

  • 您必须是管理员。

列出用户作为成员的所有项目和群组。

返回成员关系的 source_id、source_name、source_type 和 access_level。源可以是 Namespace（表示群组）或 Project。响应仅表示直接关系。例如，在子群组中的继承关系不包括在内。

访问级别表示为整数。有关访问级别值的含义，请参阅访问请求。

GET /users/:id/memberships

支持的参数：

属性 类型 是否必需 描述
id integer yes 指定的用户 ID
type string no 通过类型过滤成员关系。可以是 Project 或 Namespace

示例请求：

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/users/:user_id/memberships"

Example response:

[
  {
    "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：当请求的类型不支持时。

禁用用户的双因素认证

  • 引入于极狐GitLab 15.2。

先决条件：

  • 您必须是管理员。

为指定用户禁用双因素认证（2FA）。

管理员无法通过使用 API 来禁用自己账号或其他管理员账号的 2FA。相反地，他们可以使用 Rails 控制台来禁用管理员的 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 实例的管理员。
  • 对于拥有 Owner 角色的 group_type 或 project_type，管理员不能启用 限制所有用户注册 runner。
  • 一个带有 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": "<access-token>",
    "token_expires_at": null
}

删除用户的认证身份识别

使用与用户身份验证标识关联的提供方名称来删除该用户的身份验证标识。

先决条件：

  • 您必须是管理员。
DELETE /users/:id/identities/:provider

支持的属性：

属性 类型 是否必需 描述
id integer yes 用户 ID
provider string yes 外部的提供商名称