確認事件日誌的儲存結構與載入失敗資料：事件日誌傳送 第4篇
傳送到 Hive Analytics 的事件中，符合收集標準的事件會儲存在各公司 BigQuery 資料集的 t_raw_event_log，不符合標準的事件則會連同原始 JSON 與隔離原因儲存在 t_raw_event_log_rescue。若在一般資料表中找不到事件，可透過 rescue 資料表的 errorReason、errorStackTrace、rawData 確認隔離原因。例如 eventTime 不符合 RFC 3339 格式時，事件會以 201（DATETIME_INVALID）錯誤被隔離。此時修正時間格式並重新傳送事件後，確認事件已儲存在一般資料表即可。
確認已傳送事件的儲存結果
「將遊戲資料以事件日誌傳送：事件日誌傳送 第3篇」介紹了如何將實際遊戲資料以事件日誌傳送。本篇將說明已傳送事件的儲存結構，以及未能正常儲存的事件被隔離的原因與確認方法。
套用日誌傳送功能後，必須確認事件是否已正常儲存。符合必要屬性與值的格式等收集標準的事件會儲存在一般資料表，不符合標準的事件則會儲存在另外的隔離資料表。
若在一般資料表中找不到已傳送的事件，不應只判斷為收集延遲，而需要一併確認事件是否被隔離以及原因。
Hive Analytics 的事件儲存結構
事件資料
Hive Analytics 正常收集的事件會儲存在各公司 BigQuery 資料集的 t_raw_event_log 資料表。此資料表以 dateTime 為基準按日分區，並一併儲存事件的基本資訊與屬性。
| 欄位 | 資料型別 | 說明 | 產生方式 |
|---|---|---|---|
userId | STRING | 以帳號識別用戶的值 | 以必要屬性傳送 |
identifierProvider | STRING | 核發用戶識別碼的系統 | 以必要屬性傳送 |
deviceId | STRING | 以裝置識別用戶的值 | 以必要屬性傳送 |
appId | STRING | 識別發生事件之 App 的值 | 以必要屬性傳送 |
appIdGroup | STRING | 將多個 App 歸為同一款遊戲（專案）的值 | 依 appId 自動產生 |
dateTime | TIMESTAMP | 將 eventTime 轉換為 UTC 的事件發生時間 | 解析 eventTime 後自動產生 |
eventName | STRING | 區分事件的名稱 | 以必要屬性傳送 |
checksum | STRING | 以事件資料產生的雜湊值 | 依事件資料自動產生 |
bigqueryRegistTimestamp | TIMESTAMP | 事件儲存到 BigQuery 的時間 | 儲存時自動產生 |
attributes | JSON | 儲存自訂屬性與自動收集屬性的區域 | 將傳送的屬性依結構自動產生 |
contents_success 事件正常收集後，事件的基本資訊與屬性值會如下圖儲存在同一列。同一事件重新傳送時，可能會儲存重複資料。直接查詢原始資料時，建議以 checksum 為基準去除重複。
t_raw_event_log 中，事件的基本資訊與屬性值儲存在同一列。事件屬性的儲存結構
隨事件傳送或自動收集的屬性，會以 JSON 格式儲存在 attributes 欄位。attributes 內部依屬性的收集方式分為 hiveAttributes 與 eventAttributes。
| 區分 | 說明 | 主要值 |
|---|---|---|
hiveAttributes | Hive Analytics 在資料處理過程中自動加入的屬性 | _dataSource |
eventAttributes | 隨事件傳送，或由用戶端自動收集的屬性 | 原始 eventTime、自訂屬性、SDK 自動收集屬性 |
查看 hiveAttributes 的 _dataSource，即可區分事件是透過 Hive SDK 或遊戲伺服器等哪一種路徑傳送。在 eventAttributes 中，可以確認遊戲直接傳送的自訂屬性及其實際值。透過 Hive SDK 自動收集的用戶端屬性也包含在此區域。詳細內容請參閱 Hive 開發者網站的事件儲存結構。
隔離資料
不符合必要屬性與值的格式等收集標準的事件會載入失敗，並被隔離到各公司 BigQuery 資料集的 t_raw_event_log_rescue。隔離資料表會一併儲存傳送的原始 JSON 與隔離原因。若在一般資料表中找不到事件，請在 rescue 資料表確認該事件是否被隔離。
| 主要隔離原因 | 說明 |
|---|---|
| 缺少必要屬性 | 缺少傳送日誌所需的屬性，或值為空 |
| 使用保留字 | 以 attributes、eventAttributes、hiveAttributes 作為自訂屬性名稱，或使用以 _ 開頭的屬性名稱 |
| 不支援的資料型別 | 以 JSON 物件或陣列作為自訂屬性值傳送 |
eventTime 格式錯誤 | 無法將 eventTime 解讀為包含時區的 RFC 3339 格式 |
eventTime 超出允許範圍 | 事件發生時間超出可收集的範圍（過去 10 年至未來 5 年） |
| JSON 格式錯誤 | 無法將傳送的日誌解讀為正確的 JSON |
屬性名稱使用的保留字不區分英文大小寫。例如 Attributes 或 HIVEATTRIBUTES 也會被視為保留字，因此請勿作為自訂屬性名稱使用。
隔離資料表的儲存結構
t_raw_event_log_rescue 會儲存可從原始日誌讀取的事件基本資訊、原始資料與隔離原因。
| 欄位 | 資料型別 | 說明 |
|---|---|---|
userId | STRING | 可從原始日誌讀取的用戶識別碼 |
identifierProvider | STRING | 核發用戶識別碼的系統 |
deviceId | STRING | 可從原始日誌讀取的裝置識別碼 |
appIdGroup | STRING | 事件所屬遊戲（專案）的識別值 |
dateTime | STRING | 傳送的原始 eventTime 值 |
eventName | STRING | 區分事件的名稱 |
bigqueryRegistTimestamp | TIMESTAMP | 事件儲存到 BigQuery 的時間 |
checksum | STRING | 以事件資料產生的雜湊值 |
rawData | STRING | 傳送事件的原始 JSON |
errorReason | STRING | 表示事件被隔離原因的代碼 |
errorStackTrace | STRING | 缺少的欄位等隔離原因的詳細資訊 |
一般資料表的 dateTime 會儲存由 eventTime 轉換的 TIMESTAMP 值。隔離資料表的 dateTime 則會以字串儲存原始 eventTime，方便確認傳送值的問題。
確認 contents_success 的隔離原因
以下是傳送 contents_success 事件後，在 BigQuery 確認被隔離資料的過程。
申請 BigQuery 查詢權限
確認隔離原因需要 BigQuery 原始資料查詢權限。若要使用 BigQuery，請先取得 Hive Analytics 管理員權限，再從 Hive Analytics 的帳號選單申請 BigQuery 查詢權限。權限生效後，進入 Google Cloud 的 BigQuery 主控台，在探索工具中確認已獲得查詢權限的 Hive Analytics 專案與各公司資料集。接著查詢該資料集的t_raw_event_log_rescue。BigQuery 使用方式的詳細內容，請參閱 Hive 開發者網站的BigQuery 設定。
在 BigQuery 查詢 t_raw_event_log_rescue 後，errorReason 顯示為 201。確認 errorStackTrace 與 rawData 後，可以看到 eventTime 以 2026-10-26T17:51:57+09:00+09:00 傳送，時區重複。此值不符合 RFC 3339 格式，因此無法解析為儲存用的 dateTime。
隔離代碼與處理方式
| errorReason | 處理方式 |
|---|---|
| 100 | 傳送的訊息不是有效的 JSON。請先驗證 JSON 格式再傳送。 |
| 200 | 以包含時區的 RFC 3339 格式傳送 eventTime 欄位。此外，請確保 eventTime 的時間值落在允許範圍（過去 10 年～未來 5 年）內再傳送。 |
| 201 | 以包含時區的 RFC 3339 格式傳送 eventTime 欄位。 |
| 300 | attributes、eventAttributes、hiveAttributes 是管線自動產生的保留欄位，請勿直接包含在事件中。以 _ 開頭的欄位名稱保留給管線內部使用，請勿使用。 |
| 400 | 確認已包含所有必要欄位（userId、identifierProvider、deviceId、appId、eventName、eventTime）後再傳送。 |
| 401 | 事件屬性值包含 JSON 物件（{}）或陣列（[]）。所有屬性都以單層扁平結構（字串／數字）傳送。JSON 字串（"{...}"、"[...]"）也會被拒絕。 |
確認 eventTime 的正確格式與允許範圍後，將值修正為只包含一次時區，例如 2026-10-26T17:51:57+09:00，再重新傳送。之後以相同條件查詢資料，確認修正後的事件已正常儲存在 t_raw_event_log。
開始使用 Hive Analytics
正常收集的事件會儲存在 t_raw_event_log，不符合收集標準的事件則會連同原始資料與錯誤資訊被隔離到 t_raw_event_log_rescue。同時確認兩個資料表，就能區分事件的儲存結果，找出未能正常收集之日誌的原因，並修正傳送程式碼。
Hive Analytics 是一款遊戲專用的分析解決方案，可以分析收集到的遊戲事件，並確認未正常處理之事件日誌的隔離原因與原始資料，找出問題的原因。現在就到 Hive Analytics 的 BigQuery 資料集確認事件的傳送狀態吧。
