DataHub Audit Events Search API V1 实战指南用 /openapi/v1/events/audit/search 检索审计事件【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub本篇指南围绕 DataHub 审计事件搜索 APIAudit Events Search API V1端点/openapi/v1/events/audit/search展开讲解如何通过 POST 请求按事件类型、实体类型、Aspect 类型与操作者 URN 检索平台内发生的元数据变更、用户行为与系统活动历史。读完本文你将掌握该 API 的请求/响应结构与过滤语义、各类审计事件的数据形态并能结合分页、时间范围等最佳实践将其用于安全审计与平台使用情况追踪。概览DataHub 的审计事件能力审计事件Audit Event记录 DataHub 实例中由用户和系统执行的各种动作形成完整的活动与变更历史。该 API 允许你搜索这些事件典型用途包括调查元数据变更谁在什么时间改动了哪个实体的哪个 Aspect追踪用户活动用户的登录、登出、Token 创建与吊销等行为安全审计基于操作者 URN 过滤定位特定账号的全部操作平台使用历史分析结合时间窗口统计各类事件的发生情况。从实现层面看该端点由 ExternalEventsController 暴露委托 DataHubUsageService 在 DataHub Usage 事件索引即datahub_usage_event_v1这类索引见DATAHUB_USAGE_EVENT_INDEX常量上执行 OpenSearch 查询——审计搜索本质上是针对该索引的过滤与排序检索而不是面向通用元数据索引的搜索。端点与请求结构EndpointPOST /openapi/v1/events/audit/search该 API 接受 POST 请求携带可选的查询参数与必填的JSON 请求体。查询参数Query Parameters名称类型说明必填默认值startTimeint64搜索起始时间戳毫秒默认回溯一天否-1endTimeint64搜索结束时间戳毫秒默认当前时间否-1sizeint32单次响应最多返回的事件条数否10scrollIdstring用于获取后续结果的分页 scroll ID否nullincludeRawboolean响应中是否包含原始事件数据否true这些参数在源码中作为查询参数注入请求对象见 ExternalAuditEventsSearchRequeststartTime、endTime、size、scrollId、includeRaw字段均标注JsonIgnore不进入 JSON body由控制器层以RequestParam解析后回填。控制器对默认值的处理逻辑是endTime缺省为 -1startTime缺省为 -1size缺省为 10includeRaw缺省为true。请求体Request Body请求体必须是如下结构的 JSON 对象{ eventTypes: [string], entityTypes: [string], aspectTypes: [string], actorUrns: [string] }字段类型说明必填eventTypesstring[]要过滤的事件类型列表空表示所有事件类型否entityTypesstring[]要过滤的实体类型列表空表示所有实体否aspectTypesstring[]要过滤的 Aspect 类型列表空表示所有 Aspect否actorUrnsstring[]要过滤的操作者 URN 列表空表示所有操作者否四个字段在 ExternalAuditEventsSearchRequest 中一一对应且全部为可选requiredMode NOT_REQUIRED任一字段缺失或为空数组都视为不过滤。过滤语义AND 与 OR这些过滤器在彼此之间是 AND 关系在列表内部是 OR 关系。例如{ eventTypes: [CreateAccessTokenEvent, RevokeAccessTokenEvent], actorUrns: [urn:li:corpuser:datahub] }含义为匹配要么是CreateAccessTokenEvent、要么是RevokeAccessTokenEvent并且操作者为urn:li:corpuser:datahub的事件。从底层看DataHubUsageServiceImpl 使用 OpenSearchBoolQueryBuilder的filter(...)为每个非空过滤条件追加一个子查询事件类型/实体类型/Aspect/操作者分别通过termsQuery即列表内任一命中实现 OR 语义多个filter子句之间天然是 AND 语义。响应结构API 返回如下结构的 JSON 对象{ nextScrollId: string, count: 0, total: 0, usageEvents: [ { // Event data varies based on event type } ] }字段类型说明nextScrollIdstring用于获取下一页结果的 ID若有更多结果countint32本响应实际返回的事件条数totalint32匹配事件的总数最多计算到 10,000usageEventsarray匹配搜索条件的事件数组对应模型定义见 ExternalAuditEventsSearchResponse。注意两个值得留意的实现细节total的上限是 10,000Schema 描述为Total count of hits. Only calculated up to 10,000当命中数超过该值时应依赖分页而非total判断是否还有更多数据count是当前页实际返回条数即size内实际命中的数量与usageEvents.length一致。在 DataHubUsageServiceImpl 中count取searchHits.getHits().lengthtotal取searchHits.getTotalHits().valuenextScrollId则由SearchAfterWrapper.nextScrollId(...)基于本页命中与size计算生成。事件类型Event TypesAPI 支持多种事件类型每种类型拥有各自的具体结构但都继承自UsageEventResult基类所定义的公共字段。源码中通过 Jackson 多态序列化JsonTypeInfo依据eventType字段反序列化为对应子类JsonSubTypes注册了 14 种子类型实现这一设计见 UsageEventResult。公共字段UsageEventResult所有事件类型都包含以下基础字段字段类型说明eventTypestring事件类型timestampint64事件发生时间戳毫秒actorUrnstring执行该动作的操作者 URNsourceIPstring执行该动作的来源 IPeventSourceenum事件的来源 APIRESTLI、OPENAPI、GRAPHQL、SSO_SCIMuserAgentstring来自 HTTP 请求的 User-Agent 字符串如适用telemetryTraceIdstring来自系统遥测的 Trace IDrawUsageEventobject完整的原始事件内容当includeRawtrue时返回其中eventSource与rawUsageEvent分别由 EventSource 枚举和mapUsageEventResult方法从 OpenSearch 命中的原始_source中提取字段负责解析与组装。EntityEvent追踪一般的实体操作在公共字段之上额外包含实体相关字段{ eventType: EntityEvent, timestamp: 1649953100653, actorUrn: urn:li:corpuser:jdoe, sourceIP: 192.168.1.1, eventSource: GRAPHQL, userAgent: Mozilla/5.0..., telemetryTraceId: abc123, entityUrn: urn:li:dataset:abc, entityType: dataset, aspectName: ownership }模型定义见 EntityEvent其子类特有的三个字段entityUrn、entityType、aspectName与文档示例一一对应。Create / Update / Delete 系列事件多个事件类型分别追踪特定的创建、更新与删除动作CreateUserEvent追踪用户创建UpdateUserEvent追踪用户更新CreateAccessTokenEvent追踪访问令牌Access Token创建RevokeAccessTokenEvent追踪访问令牌吊销CreatePolicyEvent追踪策略创建UpdatePolicyEvent追踪策略更新DeletePolicyEvent追踪策略删除CreateIngestionSourceEvent追踪摄取源Ingestion Source创建UpdateIngestionSourceEvent追踪摄取源更新DeleteEntityEvent追踪实体删除UpdateAspectEvent追踪 Aspect 更新这些事件类型共享相同的结构公共字段 实体操作字段{ eventType: [Event Type Name], timestamp: 1649953100653, actorUrn: urn:li:corpuser:jdoe, sourceIP: 192.168.1.1, eventSource: GRAPHQL, userAgent: Mozilla/5.0..., telemetryTraceId: abc123, entityUrn: urn:li:dataset:abc, entityType: dataset, aspectName: ownership }LogInEvent 与 FailedLogInEvent追踪用户登录事件并带有特定的登录来源字段{ eventType: LogInEvent, timestamp: 1649953100653, actorUrn: urn:li:corpuser:jdoe, sourceIP: 192.168.1.1, eventSource: GRAPHQL, userAgent: Mozilla/5.0..., telemetryTraceId: abc123, loginSource: PASSWORD_LOGIN }loginSource的取值包括PASSWORD_RESETPASSWORD_LOGINFALLBACK_LOGINSIGN_UP_LINK_LOGINGUEST_LOGINSSO_LOGINOIDC_IMPLICIT_LOGIN从源码看LoginSource 枚举当前定义了六种来源PASSWORD_RESET、PASSWORD_LOGIN、FALLBACK_LOGIN、SIGN_UP_LINK_LOGIN、GUEST_LOGIN、SSO_LOGIN并支持同时匹配驼峰 wire 值如passwordLogin与枚举常量名如PASSWORD_LOGIN匹配时大小写不敏感。LogInEvent 与FailedLogInEvent均以此枚举作为loginSource字段的类型。使用示例基本搜索检索全部事件使用默认参数搜索所有审计事件// POST /openapi/v1/events/audit/search { eventTypes: [], entityTypes: [], aspectTypes: [], actorUrns: [] }按用户检索事件搜索某个特定用户执行的全部事件// POST /openapi/v1/events/audit/search { eventTypes: [], entityTypes: [], aspectTypes: [], actorUrns: [urn:li:corpuser:jdoe] }按事件类型与时间范围检索在指定时间窗口内搜索特定事件类型// POST /openapi/v1/events/audit/search?startTime1649953000000endTime1649954000000 { eventTypes: [LogInEvent, CreateUserEvent], entityTypes: [], aspectTypes: [], actorUrns: [] }按实体类型检索事件搜索与特定实体类型相关的事件// POST /openapi/v1/events/audit/search { eventTypes: [], entityTypes: [dataset, dashboard], aspectTypes: [], actorUrns: [] }分页遍历结果获取第一页结果// POST /openapi/v1/events/audit/search?size25 { eventTypes: [], entityTypes: [], aspectTypes: [], actorUrns: [] }获取后续页时将上一页响应中的nextScrollId传入scrollId参数// POST /openapi/v1/events/audit/search?scrollIdabcdef123456size25 { eventTypes: [], entityTypes: [], aspectTypes: [], actorUrns: [] }底层实现与工作原理理解该 API 的底层实现有助于更准确地预期其行为、排查问题权限控制控制器在处理请求前会校验调用者对ApiGroup.ANALYTICS组是否拥有READ权限未授权将抛出UnauthorizedException见 ExternalEventsController。也就是说该审计搜索能力是受平台授权策略保护的。索引与查询构造DataHubUsageServiceImpl 通过IndexConvention解析出 Usage 事件索引名如datahub_usage_event_v1然后用BoolQueryBuilder组合以下过滤器时间范围rangeQuery于timestamp字段startTime 0时回退为当前时间减 1 天endTime 0时回退为当前时间范围语义为gte(start).lt(end)含起始、不含结束事件类型 / Aspect / 实体类型 / 操作者 URN各自通过termsQuery过滤Aspect、实体类型、操作者使用.keyword子字段精确匹配仅后端事件恒定的termQuery过滤usageSource为BACKEND_SOURCE的事件即仅返回由平台后端记录的审计事件前端埋点类 usage 事件不在此搜索范围内。排序结果按timestamp降序、eventType升序、actorUrnkeyword升序三级排序保证分页顺序稳定。分页机制滚动分页基于 OpenSearch 的searchAfter实现——scrollId由 SearchAfterWrapper 编码了上一页最后一条命中记录的排序值而非 Elasticsearch 传统的有状态 scroll 游标。成本分类在 usage_operations.yaml 中POST /openapi/v1/events/audit/search被归类为search_query操作activity_class: read默认成本单位 1说明审计搜索按平台用量统计中的搜索类查询计量。测试验证仓库配套的 DataHubUsageServiceTest 覆盖了空结果、有结果与滚动分页三种场景验证了过滤器组合、响应字段映射包括LogInEvent的loginSource、UpdatePolicyEvent的entityUrn等以及nextScrollId的生成逻辑控制器层的集成测试见 ExternalEventsControllerTest。最佳实践始终指定时间范围检索事件时尽量显式给出startTime与endTime以缩小结果集并提升查询性能不指定时默认只回溯最近一天startTime-1会由后端换算为 24 小时窗口。合理使用过滤器善用eventTypes、entityTypes、aspectTypes、actorUrns将搜索范围收窄到真正关心的事件减少无关数据与解析开销。分页处理大结果集使用size与scrollId逐页拉取不要试图一次取回全部事件同时注意total最多计算到 10,000超过该量级后应依赖分页持续翻页直至nextScrollId为空。监控用户活动借助actorUrns过滤器跟踪特定用户的操作轨迹这对安全审计尤为重要结合LogInEvent/FailedLogInEvent的loginSource字段可以进一步分析登录入口的分布与异常登录行为。结合includeRaw使用需要完整审计上下文如原始请求的完整载荷时保持includeRawtrue若仅需结构化字段做聚合分析可将其设为false以减小响应体积。相关资源API 文档原文docs/actions/events/audit-events-search-guide.md控制器实现ExternalEventsController.java请求 / 响应模型ExternalAuditEventsSearchRequest.java、ExternalAuditEventsSearchResponse.java事件多态模型UsageEventResult.java、EntityEvent.java、LogInEvent.java、LoginSource.java底层搜索实现DataHubUsageServiceImpl.java单元测试DataHubUsageServiceTest.java用量分类配置usage_operations.yaml【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考