> ## Documentation Index
> Fetch the complete documentation index at: https://docs.livingsecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 电子邮件网络钓鱼日志
> 基于 /v1 报告模拟事件和实体，重建上一家服务商提供的事件级网络钓鱼日志。
本报告是事件级网络钓鱼日志：每个观察到的模拟交互对应一行（日期、操作、收件人电子邮件、主题、发件人、难度）。它保持长格式，不会将个人的历史记录合并为单一结果。
该查询将过去 **12 个日历月**折叠到 `occurred_after` 中（即 12 个月前同一日期当天的 UTC 午夜，而非 365 天的时长）。
原始客户端 IP 绝不会出现在 `/v1` 上，这是出于隐私的设计，而非尚未完成的映射。设备类型是事件行上的派生类别；原始 `user_agent` 保持私有。请参阅[与旧版导出的差异](#%E4%B8%8E%E6%97%A7%E7%89%88%E5%AF%BC%E5%87%BA%E7%9A%84%E5%B7%AE%E5%BC%82)。
设置、凭据、分页和速率限制重试的方式与 [Power BI / Excel 连接指南](/zh-Hans/developers/v1/powerbi)相同。请先添加共享的 `Fn_FetchAll` 查询；本报告会按名称调用该查询。
## 所需的密钥范围
| 范围 | 用途 |
| - | - |
| `reporting:read` | `GET /v1/reporting/simulation_events` |
| `entity:read` | `GET /v1/entities`（电子邮件和显示名称关联） |
仅被授予 `simulation:read` 的密钥无法调用报告事件端点（API 将返回 `403`）。请参阅[选择合适的粒度](/zh-Hans/developers/v1/powerbi#%E9%80%89%E6%8B%A9%E5%90%88%E9%80%82%E7%9A%84%E7%B2%92%E5%BA%A6)。
## 源端点
| 端点 | 作用 |
| - | - |
| `GET /v1/reporting/simulation_events` | 事件级事实。粒度为一次类型化交互。`email_subject`、`sender_email`、`sender_domain` 和 `difficulty_tier` 均位于此行，因此查询不会为这些字段关联活动级结果。 |
| `GET /v1/entities` | 将 `entity_id` 解析为电子邮件/显示名称。报告事件不包含收件人电子邮件（报告读取器对此有硬性排除）。遍历 `/entities` 即可填充旧版的“电子邮件”列。 |
事件列表上允许使用的筛选条件（其他任何条件均返回 `400`）：`limit`、`page_token`、`simulation`、`entity`、`event_type`、`occurred_after`。
此报告系列属于[预览数据集](/zh-Hans/developers/v1/powerbi#%E6%8A%A5%E5%91%8A%E9%A2%84%E8%A7%88%E6%95%B0%E6%8D%AE%E9%9B%86%EF%BC%88%E6%8C%89%E4%BA%BA%E5%91%98%E7%9A%84%E7%BD%91%E7%BB%9C%E9%92%93%E9%B1%BC%EF%BC%89)。可通过 `GET /v1/reporting/datasets` 和 `GET /v1/reporting/datasets/simulation_events` 查看数据集架构和数据策略。
### 粒度
每个报告模拟事件对应一行。如果某人打开并随后点击了同一封邮件，则会产生两行。`entity_id` 为 null（无执行者/收件人/目标参与者）的事件仍会出现，此时 `email` 为 null。
API 时间窗口会扩大一分钟；确切的 `occurred_at >= WindowStart` 边界会在本地重新应用，因此过去一年的范围不取决于服务器将 `occurred_after` 视为包含还是不包含。
请求预算：对窗口内的事件进行一次分页遍历，再对实体进行一次遍历。请始终设置 `limit = "500"`。
## 列映射
旧版列名来自您上一家服务商的导出。`/v1` 字段是公共 API 名称；查询会为报告对其中一些字段设置别名。
| 旧版列 | `/v1` 字段或派生方式 | 报告列 |
| - | - | - |
| 日期 | `Event.occurred_at`（作为日期；原始 `occurred_at` 保留为 `datetimezone`） | `date` |
| 操作 | `Event.event_type`，封闭令牌列于下方 | `action` |
| 电子邮件 | `Entity.email`（通过 `entity_id` 关联） | `email` |
| 主题 | `Event.email_subject` | `subject` |
| 发件人 | `Event.sender_email` | `from` |
| 难度 | `Event.difficulty_tier`，整数 1–5，1 最容易，5 最困难 | `difficulty` |
| 原始 IP | 绝不会出现在 `/v1` 上 | 省略，而非置为 null |
| 设备类型 | `Event.device_type`，派生类别；当事件没有派生类别时为 null | `device_type` |
### 操作令牌
`action` 是封闭的报告令牌。旧版“Email Sent”映射到 `simulation.delivered`（`delivered` 是公共动词；传输令牌为 `simulation.delivered`）。
| `action` 值 |
| - |
| `simulation.delivered` |
| `simulation.opened` |
| `simulation.link_clicked` |
| `simulation.credentials_submitted` |
| `simulation.attachment_opened` |
| `simulation.reported` |
| `simulation.bounced` |
| `simulation.qr_scanned` |
| `simulation.replied` |
因 API 提供而保留的额外字段：`sender_domain`、`full_name`、`event_id`、`entity_id`、`simulation_id`、`occurred_at`，以及来自实体关联的 `entity_type` 和 `entity_status`。
## 与旧版导出的差异
* **原始 IP 始终不可用。** `/v1` 不会公开原始客户端 IP，这是出于隐私的设计，而非尚未完成的映射。查询不会添加占位 IP 列。
* **设备类型是派生的，而非原始值。** `device_type` 是点击、提交和报告事件的派生设备类别。观察到的令牌包括 `desktop`、`mobile`、`tablet` 和 `unknown`，但发送端存储的是自由格式字符串，请将其视为开放文本，而非封闭枚举。当事件没有派生类别时为 null，原始 `user_agent` 字符串保持私有。
* **“Email Sent”对应 `simulation.delivered`。** 筛选或统计发送量时请使用该令牌。请勿查找旧版的 `email_sent` 字符串。
* **收件人电子邮件是关联得到的，而非事件上的字段。** 报告事件不包含电子邮件；查询通过遍历 `/entities` 来填充。
* **过去 12 个日历月**，而非 365 天的时长，也不是完整历史记录。
* **长格式，不合并。** 每次交互一行，而非每人一个结果。
## 后续步骤
凭据、分页，以及在 Power BI 或 Excel 中加载这些查询。
按个人汇总的 12 个月点击、凭据和报告情况。
人员 × 分配粒度的培训注册情况。
在用于刷新此报告的密钥上授予 `reporting:read` 和 `entity:read`。
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.