> ## 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`（即十二個月前同一日期的 UTC 午夜，而非 365 天的時間長度）。
原始用戶端 IP 絕不會出現在 `/v1` 上，這是基於隱私的設計，並非尚待完成的對應。裝置類型是事件列上的衍生類別；原始 `user_agent` 仍保持私有。請參閱[與舊版匯出的差異](#%E8%88%87%E8%88%8A%E7%89%88%E5%8C%AF%E5%87%BA%E7%9A%84%E5%B7%AE%E7%95%B0)。
設定、認證、分頁與速率限制重試的方式，均與 [Power BI / Excel 連線指南](/zh-Hant/developers/v1/powerbi)相同。請先新增共用的 `Fn_FetchAll` 查詢；本報表會依名稱呼叫該查詢。
## 必要的金鑰範圍
| 範圍 | 用途 |
| - | - |
| `reporting:read` | `GET /v1/reporting/simulation_events` |
| `entity:read` | `GET /v1/entities`（電子郵件與顯示名稱的聯結） |
僅被授予 `simulation:read` 的金鑰無法呼叫報表事件端點（API 會傳回 `403`）。請參閱[選擇正確的粒度](/zh-Hant/developers/v1/powerbi#%E9%81%B8%E6%93%87%E6%AD%A3%E7%A2%BA%E7%9A%84%E8%B3%87%E6%96%99%E7%B2%92%E5%BA%A6)。
## 來源端點
| 端點 | 角色 |
| - | - |
| `GET /v1/reporting/simulation_events` | 事件層級事實。粒度為一次具類型的互動。`email_subject`、`sender_email`、`sender_domain` 與 `difficulty_tier` 均位於此列，因此查詢不會為這些欄位聯結活動層級的結果。 |
| `GET /v1/entities` | 將 `entity_id` 解析為電子郵件／顯示名稱。報表事件不含收件者電子郵件（報表讀取器中的硬性排除項目）。舊版「email」欄位即是透過走訪 `/entities` 來填入。 |
事件清單上允許的篩選條件（其他任何條件都會傳回 `400`）：
`limit`、`page_token`、`simulation`、`entity`、`event_type`、
`occurred_after`。
此報表系列屬於[預覽資料集](/zh-Hant/developers/v1/powerbi#%E5%A0%B1%E8%A1%A8%E9%A0%90%E8%A6%BD%E8%B3%87%E6%96%99%E9%9B%86%EF%BC%88%E6%AF%8F%E4%BD%8D%E4%BA%BA%E5%93%A1%E7%9A%84%E7%B6%B2%E8%B7%AF%E9%87%A3%E9%AD%9A%EF%BC%89)。
請於 `GET /v1/reporting/datasets` 與
`GET /v1/reporting/datasets/simulation_events` 檢視資料集結構描述與資料政策。
### 粒度
每個報表模擬事件對應一列。若某人開啟後又點擊同一封郵件，則會產生兩列。`entity_id` 為空值的事件（無執行者／收件者／目標參與者）仍會顯示，此時 `email` 為空值。
API 時間範圍會擴大一分鐘；`occurred_at >= WindowStart` 的確切界限會在本機重新套用，因此過去一年的範圍不會取決於伺服器將 `occurred_after` 視為包含或排除。
請求預算：對時間範圍內的事件進行一次分頁走訪，再加上對實體進行一次走訪。請務必設定 `limit = "500"`。
## 欄位對應
舊版欄位名稱來自您先前供應商的匯出檔。`/v1` 欄位為公開 API 名稱；查詢會為報表將其中部分欄位設定別名。
| 舊版欄位 | `/v1` 欄位或推導方式 | 報表欄位 |
| - | - | - |
| Date | `Event.occurred_at`（作為日期；原始 `occurred_at` 保留為 `datetimezone`） | `date` |
| Action | `Event.event_type`，封閉式代碼列於下方 | `action` |
| Email | `Entity.email`（以 `entity_id` 聯結） | `email` |
| Subject | `Event.email_subject` | `subject` |
| From | `Event.sender_email` | `from` |
| Difficulty | `Event.difficulty_tier`，整數 1–5，1 最容易，5 最困難 | `difficulty` |
| Raw IP | 絕不會出現在 `/v1` | 省略，而非設為空值 |
| Device type | `Event.device_type`，衍生類別；事件沒有衍生類別時為空值 | `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`，但發送端儲存的是自由格式字串，請將其視為開放文字，而非封閉列舉。事件沒有衍生類別時為空值，原始 `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.