Skip to content
代码片段 群组 项目
提交 44d6ff04 编辑于 作者: Evan Read's avatar Evan Read
浏览文件

Make final refinements of Users API documentation

上级 8c8156ab
No related branches found
No related tags found
无相关合并请求
隐藏空白变更内容
行内 左右并排
doc/administration/admin_area.md
+ 1
− 1
浏览文件 @ 44d6ff04
......@@ -179,7 +179,7 @@ The following data is included in the export:
- Type
- Path
- Access level ([Project](../user/permissions.md#project-members-permissions) and [Group](../user/permissions.md#group-members-permissions))
- Date of last activity. For a list of activities that populate this column, see the [Users API documentation](../api/users.md#get-a-list-of-a-users-activity).
- Date of last activity. For a list of activities that populate this column, see the [Users API documentation](../api/users.md#list-a-users-activity).
Only the first 100,000 user accounts are exported.
......
doc/api/users.md
+ 204
− 204
浏览文件 @ 44d6ff04
......@@ -547,6 +547,149 @@ You can include the user's [custom attributes](custom_attributes.md) in the resp
GET /users/:id?with_custom_attributes=true
```
## Get the current user
Get the current user.
### As a regular user
Get your user details.
```plaintext
GET /user
```
Example response:
```json
{
"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",
}
```
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters.
### As an administrator
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed, GitLab Dedicated
> - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
Get your user details, or the details of another user.
```plaintext
GET /user
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:------------|
| `sudo` | integer | no | ID of a user to make the call in their place |
```json
{
"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
}
```
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see these
parameters:
- `shared_runners_minutes_limit`
- `extra_shared_runners_minutes_limit`
- `is_auditor`
- `provisioned_by_group_id`
- `using_license_seat`
## Create a user
DETAILS:
......@@ -604,7 +747,7 @@ Supported attributes:
| `note` | No | Administrator notes for this user |
| `organization` | No | Organization name |
| `password` | No | Password |
| `private_profile` | No | User's profile is private - true or false. The default value is determined by [this](../administration/settings/account_and_limit_settings.md#set-profiles-of-new-users-to-private-by-default) setting. |
| `private_profile` | No | User's profile is private - true or false. The default value is determined by [a setting](../administration/settings/account_and_limit_settings.md#set-profiles-of-new-users-to-private-by-default). |
| `projects_limit` | No | Number of projects user can create |
| `pronouns` | No | User's pronouns |
| `provider` | No | External provider name |
......@@ -684,29 +827,6 @@ If you update a user's password, they are forced to change it when they next sig
Returns a `404` error, even in cases where a `409` (Conflict) would be more appropriate.
For example, when renaming the email address to an existing one.
## Delete authentication identity from a user
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed, GitLab Dedicated
Delete a user's authentication identity using the provider name associated with that identity.
Prerequisites:
- You must be an administrator.
```plaintext
DELETE /users/:id/identities/:provider
```
Supported attributes:
| Attribute | Type | Required | Description |
|:-----------|:--------|:---------|:------------|
| `id` | integer | yes | ID of a user |
| `provider` | string | yes | External provider name |
## Delete a user
DETAILS:
......@@ -734,150 +854,7 @@ Supported attributes:
| Attribute | Type | Required | Description |
|:--------------|:--------|:---------|:------------|
| `id` | integer | yes | ID of a user |
| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User](../user/profile/account/delete_account.md#associated-records) are deleted instead, as well as groups owned solely by this user. |
## List the current user
Get the current user.
### As a regular user
Get your user details.
```plaintext
GET /user
```
Example response:
```json
{
"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",
}
```
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see the `shared_runners_minutes_limit`, `extra_shared_runners_minutes_limit` parameters.
### As an administrator
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed, GitLab Dedicated
> - The `created_by` field in the response was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/93092) in GitLab 15.6.
> - The `email_reset_offered_at` field in the response [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/137610) in GitLab 16.7.
Get your user details, or the details of another user.
```plaintext
GET /user
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:--------|:---------|:------------|
| `sudo` | integer | no | ID of a user to make the call in their place |
```json
{
"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
}
```
Users on [GitLab Premium or Ultimate](https://about.gitlab.com/pricing/) also see these
parameters:
- `shared_runners_minutes_limit`
- `extra_shared_runners_minutes_limit`
- `is_auditor`
- `provisioned_by_group_id`
- `using_license_seat`
| `hard_delete` | boolean | no | If true, contributions that would usually be [moved to Ghost User](../user/profile/account/delete_account.md#associated-records) are deleted instead, and also groups owned solely by this user. |
## Get your user status
......@@ -1039,6 +1016,52 @@ Supported attributes:
| `show_whitespace_in_diffs` | Yes | Flag indicating the user sees whitespace changes in diffs. |
| `pass_user_identities_to_ci_jwt` | Yes | Flag indicating the user passes their external identities as CI information. This attribute does not contain enough information to identify or authorize the user in an external system. The attribute is internal to GitLab, and must not be passed to third-party services. For more information and examples, see [Token Payload](../ci/secrets/id_token_authentication.md#token-payload). |
## Upload an avatar for yourself
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0.
Upload an avatar for yourself.
Prerequisites:
- You must be authenticated.
```plaintext
PUT /user/avatar
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `avatar` | string | Yes | The file to be uploaded. The ideal image size is 192 x 192 pixels. The maximum file size allowed is 200 KiB. |
To upload an avatar from your file system, use the `--form` argument. This causes
cURL to post data using the header `Content-Type: multipart/form-data`. The
`file=` parameter must point to an image file on your file system and be
preceded by `@`. For example:
Example request:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "avatar=@avatar.png" \
--url "https://gitlab.example.com/api/v4/user/avatar"
```
Example response:
```json
{
"avatar_url": "http://gdk.test:3000/uploads/-/system/user/avatar/76/avatar.png",
}
```
Returns:
- `200` if successful.
- `400 Bad Request` for file sizes greater than 200 KiB.
## Get a count of your assigned issues, merge requests, and reviews
Get a count of your assigned issues, merge requests, and reviews.
......@@ -1111,7 +1134,7 @@ Example response:
}
```
## Get a list of a user's activity
## List a user's activity
DETAILS:
**Tier:** Free, Premium, Ultimate
......@@ -1174,7 +1197,7 @@ Example response:
`last_activity_at` is deprecated. Use `last_activity_on` instead.
## Get a list of projects and groups that a user is a member of
## List projects and groups that a user is a member of
DETAILS:
**Tier:** Free, Premium, Ultimate
......@@ -1327,48 +1350,25 @@ Example response:
}
```
## Upload an avatar for yourself
## Delete authentication identity from a user
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/148130) in GitLab 17.0.
DETAILS:
**Tier:** Free, Premium, Ultimate
**Offering:** Self-managed, GitLab Dedicated
Upload an avatar for yourself.
Delete a user's authentication identity using the provider name associated with that identity.
Prerequisites:
- You must be authenticated.
- You must be an administrator.
```plaintext
PUT /user/avatar
DELETE /users/:id/identities/:provider
```
Supported attributes:
| Attribute | Type | Required | Description |
|:----------|:-------|:---------|:------------|
| `avatar` | string | Yes | The file to be uploaded. The ideal image size is 192 x 192 pixels. The maximum file size allowed is 200 KiB. |
To upload an avatar from your file system, use the `--form` argument. This causes
cURL to post data using the header `Content-Type: multipart/form-data`. The
`file=` parameter must point to an image file on your file system and be
preceded by `@`. For example:
Example request:
```shell
curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
--form "avatar=@avatar.png" \
--url "https://gitlab.example.com/api/v4/user/avatar"
```
Example response:
```json
{
"avatar_url": "http://gdk.test:3000/uploads/-/system/user/avatar/76/avatar.png",
}
```
Returns:
- `200` if successful.
- `400 Bad Request` for file sizes greater than 200 KiB.
| Attribute | Type | Required | Description |
|:-----------|:--------|:---------|:------------|
| `id` | integer | yes | ID of a user |
| `provider` | string | yes | External provider name |
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或