[comment]: # translation:outdated

[comment]: # ({19701d17-19701d17})
# 登录用户

[comment]: # ({/19701d17-19701d17})

[comment]: # ({c647dda4-c647dda4})
### 描述

`string/object user.login(object parameters)`

此方法用于登录到API并生成身份验证令牌.

::: notewarning
使用此方法, 你同时需要使用
[注销](/manual/api/reference/user/logout) 方法, 防止产生大量未关闭的会话记录.
:::

::: noteimportant
此方法仅适用于未认证用户，同时在JSON-RPC请求中不能带有`auth`参数.
:::

[comment]: # ({/c647dda4-c647dda4})

[comment]: # ({6bb44626-68f0a066})
### 参数

`(object)` 包含用户名和密码的参数。

该方法接受以下参数。

|参数|[类型](/manual/api/reference_commentary#data_types)|描述|
|--|--|------|
|**password**<br>（必填）|字符串|用户密码。|
|**username**<br>（必填）|字符串|用户名。|
|userData|flag|返回关于认证用户的信息。|
|user<br>(已废弃)|字符串|此参数已弃用，请改用“username”。<br>用户名。|

[comment]: # ({/6bb44626-68f0a066})

[comment]: # ({0c2cbc1a-bc924c62})
### 返回值

`(string/object)` 如果使用 `userData` 参数, 返回一个包含认证成功用户信息的对象.

除了 [用户标准信息](object#user), 其他返回信息如下:

|属性|[类](/manual/api/reference_commentary#data_types)|描述|
|--------|---------------------------------------------------|-----------|
|debug\_mode|boolean|用户是否启用了调试模式.|
|gui\_access|integer|前端认证使用的用户身份验证方法.<br><br>可能值的列表,请参阅 [用户组](/manual/api/reference/usergroup/object#user_group) 的 `gui_access` 属性.|
|sessionid|string|身份验证令牌，必须在下列API请求中使用.|
|userip|string|用户的IP地址.|

::: notetip
如果一个用户在一次或多次失败的尝试之后成功地进行了身份验证, 该方法将返回`attempt_clock`、`attempt_failed`和`attempt_ip`属性的当前值，然后重新设置它们.
:::

如果不使用`userData`参数，该方法将返回身份验证令牌.

::: notetip
所生成的认证令牌必须存储, 并在以下JSON-RPC请求的`auth`参数中使用. 在使用HTTP认证时也需要它.
:::

[comment]: # ({/0c2cbc1a-bc924c62})

[comment]: # ({b41637d2-b41637d2})
### 示例

[comment]: # ({/b41637d2-b41637d2})

[comment]: # ({a4a6aed2-46abbe5a})
#### 单用户认证

单用户认证.

请求:

```json
{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "username": "Admin",
        "password": "zabbix"
    },
    "id": 1
}
```

返回:

```json
{
    "jsonrpc": "2.0",
    "result": "0424bd59b807674191e7d77572075f33",
    "id": 1
}
```

[comment]: # ({/a4a6aed2-46abbe5a})

[comment]: # ({e1c3c0b4-8448c8ab})
#### 请求已验证用户的信息

验证并返回有关用户的附加信息.

请求:

```json
{
    "jsonrpc": "2.0",
    "method": "user.login",
    "params": {
        "username": "Admin",
        "password": "zabbix",
        "userData": true
    },
    "id": 1
}
```

返回:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "userid": "1",
        "username": "Admin",
        "name": "Zabbix",
        "surname": "Administrator",
        "url": "",
        "autologin": "1",
        "autologout": "0",
        "lang": "ru_RU",
        "refresh": "0",
        "theme": "default",
        "attempt_failed": "0",
        "attempt_ip": "127.0.0.1",
        "attempt_clock": "1355919038",
        "rows_per_page": "50",
        "timezone": "Europe/Riga",
        "roleid": "3",
        "type": 3,
        "debug_mode": 0,
        "userip": "127.0.0.1",
        "gui_access": "0",
        "sessionid": "5b56eee8be445e98f0bd42b435736e42"
    },
    "id": 1
}
```

[comment]: # ({/e1c3c0b4-8448c8ab})

[comment]: # ({22a14fca-22a14fca})
### 参考

-   [注销](logout)

[comment]: # ({/22a14fca-22a14fca})

[comment]: # ({7fd9f53c-7fd9f53c})
### 来源

CUser::login() in *ui/include/classes/api/services/CUser.php*.

[comment]: # ({/7fd9f53c-7fd9f53c})