Chuyển đến nội dung

Nhật Ký Kiểm Toán

Mọi thay đổi trong tổ chức đều được ghi lại: ai đã làm gì, với cái gì, vào lúc nào. Bao gồm đăng nhập (kể cả lần bị từ chối), chỉnh sửa board và bản ghi, thay đổi Document Model, người dùng và vai trò, API key, cài đặt SSO, workflow và nhiều thứ khác.

SDK cung cấp hai namespace:

  • client.auditLogs / client.audit_logs — nhật ký đang hoạt động: đọc, lọc, đếm, xuất toàn bộ, hoàn tác một thay đổi
  • client.auditArchives / client.audit_archives — các tháng cũ được lưu thành file: tải về, đưa trở lại, đặt thời gian lưu giữ

Tổ chức cần có tính năng Audit Trail. Khởi tạo client trước (xem Cài đặt hoặc Quick Start).


Đọc nhật ký

const page = await client.auditLogs.list({
resource: ["user", "role"], // một hoặc nhiều giá trị
action: ["create", "update", "delete"],
from: "2026-11-01",
limit: 50,
});
for (const e of page.data) {
console.log(e.createdAt, e.actor.email, e.action, e.resource, e.resourceName);
}

Mỗi mục có id, action, resource, resourceId, resourceName, actor (userId, name, email), summary, changes (trước và sau), metadata, revertable và createdAt. client.auditLogs.get(id) đọc một mục.

Bộ lọc

Bộ lọcÝ nghĩa
userId, resource, resourceId, action, boardIdMột hoặc nhiều giá trị
categoryIdMọi board trong danh mục này (bị bỏ qua khi có boardId)
runIdNhững gì một lần chạy workflow hoặc agent đã làm
caseIdNhững gì một case AI đã làm
from, toNgày theo ISO
qTìm theo văn bản
importsonly (chỉ) hoặc exclude (loại trừ) các mục do import tạo ra
includeArchiveĐọc cả các tháng đã lưu trữ (chậm hơn; mục đã lưu trữ không hoàn tác được)
limit, page, cursorPhân trang: limit tối đa 100 (mặc định 25); cursor là pagination.nextCursor của trang trước

action là một trong create, update, delete, upload, login, login_failed (đăng nhập bị từ chối; metadata.reason cho biết lý do), revert, export, download, connect.

Các giá trị resource thường gặp:

NhómGiá trị
Data board và Knowledge Hubboard, board_item, file, folder, integration
DocIQ và cấu hình boarddoc_schema, doc_category, doc_settings, dociq_extraction, segmentation, scheduler, automation
Người dùng và quyền truy cậpuser, team, team_user, role, api_key, sso_config, oidc_role_mapping, business_unit, organization, session
AI, ứng dụng và workflowassistant, llm_provider, flow, tool_server, use_case, app_install
Kênhchannel, contact, campaign, message_template
Chính nhật ký kiểm toánaudit_retention

Xuất toàn bộ

iterate() duyệt qua mọi mục khớp điều kiện, từng trang một, mới nhất trước.

import { createWriteStream } from "node:fs";
const out = createWriteStream("audit-2026-10.jsonl");
for await (const e of client.auditLogs.iterate({ from: "2026-10-01", to: "2026-10-31T23:59:59Z" })) {
out.write(JSON.stringify(e) + "\n");
}
out.end();

Đếm

summary() nhận cùng bộ lọc và trả về total, imports, byAction, byResource và byUser.

const s = await client.auditLogs.summary({ from: "2026-11-01", action: "login_failed" });

Hoàn tác một thay đổi

Mục có revertable: true có thể hoàn tác. Việc hoàn tác cũng được ghi lại thành một mục revert. Cần quyền audit_trail:write.

const { revertEntry } = await client.auditLogs.revert(entryId);

Các tháng đã lưu trữ

Nhật ký đang hoạt động giữ những tháng gần nhất (hotMonths, ví dụ 3). Các tháng cũ hơn được chuyển thành file, mỗi tháng một file, kèm mã băm SHA-256 có ghi cả mã băm của tháng trước, nên các tháng nối thành một chuỗi.

Liệt kê và tải về

import { createHash } from "node:crypto";
import { gunzipSync } from "node:zlib";
const { hotFrom, archives } = await client.auditArchives.list();
const month = archives.find(a => a.status === "archived")!;
const file = await client.auditArchives.download(month.month); // { data, filename, sha256, filtered }
const ok = createHash("sha256").update(Buffer.from(file.data)).digest("hex") === file.sha256;
const entries = gunzipSync(Buffer.from(file.data)).toString("utf8").trim().split("\n").map(l => JSON.parse(l));

File là JSON Lines nén gzip, mỗi dòng một mục. Truyền resource (ví dụ ["user", "role"]) để chỉ tải những loại mục đó; khi đó filtered là true và sha256 là mã băm của phần được gửi về.

status của một bản lưu trữ là archived, restoring, restored (đã trở lại nhật ký đang hoạt động cho đến restoreExpiresAt), failed hoặc purged (đã xóa khi hết thời gian lưu giữ).

Đưa một tháng trở lại

restore() chép các tháng đã lưu trữ trở lại nhật ký đang hoạt động, để auditLogs.list() đọc được chúng. Việc này chạy ở chế độ nền: các tháng hiển thị restoring, rồi restored. list().restore cho biết giới hạn (số ngày mặc định và tối đa, số tháng tối đa mỗi lần khôi phục).

const { months, expiresAt } = await client.auditArchives.restore({ from: "2026-05", to: "2026-06" });
await client.auditArchives.extend("2026-05", 7); // giữ thêm 7 ngày
await client.auditArchives.release("2026-05"); // trả về kho lưu trữ trước khi hết hạn

Thời gian lưu giữ

Thời gian giữ nhật ký, tính bằng tổng số tháng (đang hoạt động và đã lưu trữ).

const retention = await client.auditArchives.getPolicy(); // { totalMonths, hotMonths, minTotalMonths, maxTotalMonths, pending, canEdit, … }
const { outcome } = await client.auditArchives.setPolicy({ totalMonths: 24 });

Thời gian dài hơn được áp dụng ngay (outcome: "increased"). Thời gian ngắn hơn được lên lịch sau một khoảng thời gian chờ (outcome: "scheduled", xem retention.pending) và có thể hủy bằng cancelPendingPolicy(). Legal hold (chặn mọi việc xóa) chỉ do iMBrace đặt hoặc gỡ.

Ai được làm gì

Thao tácAi
Đọc nhật ký, liệt kê bản lưu trữ, xem thời gian lưu giữThành viên có quyền xem nhật ký kiểm toán
Hoàn tác một thay đổiQuyền audit_trail:write
Tải về, khôi phục, gia hạn, trả vềAdmin
Thay đổi thời gian lưu giữOwner của tổ chức hoặc admin

Các trường hợp bị từ chối trả về lỗi kèm code, ví dụ live_month (409: tháng đó vẫn đang hoạt động), not_archived (404), purged (410), not_restored (409).


Xem thêm