类别：

Information Schema、表函数

LOGIN_HISTORY、LOGIN_HISTORY_BY_USER

LOGIN_HISTORY 表函数系列可用于查询 Snowflake 用户在不同维度的登录尝试：

  • LOGIN_HISTORY 返回指定时间范围内的登录事件。

  • LOGIN_HISTORY_BY_USER 返回指定用户在指定时间范围内的登录事件。

每个函数都针对沿指定维度的查询进行了优化。可以使用 SQL 谓词进一步筛选结果。

备注

这些函数返回过去 7 天内的登录事件。

语法

LOGIN_HISTORY(
      [  TIME_RANGE_START => <constant_expr> ]
      [, TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ] )

LOGIN_HISTORY_BY_USER(
      [  USER_NAME => '<string>' ]
      [, TIME_RANGE_START => <constant_expr> ]
      [, TIME_RANGE_END => <constant_expr> ]
      [, RESULT_LIMIT => <num> ] )
Copy

实参

所有实参均为可选。

TIME_RANGE_START => constant_expr、. TIME_RANGE_END => constant_expr

过去 7 天内发生登录事件的时间范围（TIMESTAMP_LTZ 格式）。

如果 TIME_RANGE_END 未指定，该函数将返回最近的登录事件。

如果时间范围不在过去 7 天内，则会返回错误。

USER_NAME => 'string'

仅适用于 LOGIN_HISTORY_BY_USER

指定用户名或 CURRENT_USER 的字符串。仅返回指定用户的登录事件。请注意，登录名称必须放在单引号内。此外，如果登录名称包含任何空格、混合大小写字符或特殊字符，则名称必须在单引号内使用双引号（例如 '"User 1"' 和 'user1'）。

默认：CURRENT_USER

RESULT_LIMIT => num

用于指定函数返回的行数上限的数字。

如果匹配的行数大于此限制，则返回具有最新时间戳的登录事件，直至达到指定的限制。

范围：1 至 10000

默认：100。

使用说明

  • 当调用 Information Schema 表函数时，会话必须具有正在使用的 INFORMATION_SCHEMA 架构，或者 函数名称必须受到完全限定。有关更多详细信息，请参阅 Snowflake Information Schema。

输出

该函数返回以下列：

列名称

数据类型

描述

EVENT_TIMESTAMP

TIMESTAMP_LTZ

事件发生的时间。

EVENT_ID

NUMBER

事件的唯一 ID。

EVENT_TYPE

TEXT

事件类型，例如身份验证事件 LOGIN。

USER_NAME

TEXT

与此事件关联的用户。

CLIENT_IP

TEXT

请求的来源 IP 地址。

REPORTED_CLIENT_TYPE

TEXT

报告的客户端软件类型，如 JDBC_DRIVER、ODBC_DRIVER 等。此信息未经身份验证。

REPORTED_CLIENT_VERSION

TEXT

客户端软件的报告版本。此信息未经身份验证。

FIRST_AUTHENTICATION_FACTOR

TEXT

用于对用户进行身份验证的方法（如果使用多重身份验证，则为第一个因素）。

SECOND_AUTHENTICATION_FACTOR

TEXT

第二个因素（如果使用多重身份验证或 NULL）。

IS_SUCCESS

TEXT

用户的请求是否成功。

ERROR_CODE

NUMBER

如果请求不成功，则为错误代码。

ERROR_MESSAGE

TEXT

如果请求不成功，则向用户返回错误消息。

RELATED_EVENT_ID

NUMBER

保留以供将来使用。

CONNECTION

TEXT

客户端使用的连接名称，如果客户端未使用连接 URL，则为 NULL。Connection 是一个 Snowflake 对象，它是 Client Redirect 的一部分。它表示连接 URL，可以跨账户进行故障转移以实现业务连续性和灾难恢复。. , NOTE：如果客户端通过配置了账户 URL （而不是连接 URL）的身份提供商 (IdP) 进行身份验证，则 IdP 会在身份验证完成后将客户端定向到账户 URL。此登录事件的 CONNECTION 列为 NULL。请参阅 身份验证和 Client Redirect。

CLIENT_PRIVATE_LINK_ID

TEXT

如果用户通过 专用连接 登录，则指定请求源自的端点的标识符。

如需详细了解由于 SAML 响应无效而失败的登录尝试的错误代码/消息，请参阅 联合身份验证和 SSO 故障排除。

示例

检索当前用户的最近 100 个登录事件：

select *
from table(information_schema.login_history_by_user())
order by event_timestamp;
Copy

检索指定用户的最近 1000 个登录事件：

select *
from table(information_schema.login_history_by_user(USER_NAME => 'USER1', result_limit => 1000))
order by event_timestamp;
Copy

例如，检索过去 1 小时内允许当前角色监控的每个用户的最多 100 个登录事件：

select *
from table(information_schema.login_history(TIME_RANGE_START => dateadd('hours',-1,current_timestamp()),current_timestamp()))
order by event_timestamp;
Copy
语言: 中文