Power BI

​

Mục đích của ví dụ này

• Tải các endpoint danh sách /v1 vào tập dữ liệu Power BI với phân trang theo con trỏ chính xác và cơ chế thử lại khi gặp giới hạn tốc độ.
• Xây dựng mô hình ngữ nghĩa trong đó các thước đo (“thực thể hoạt động”, “hoạt động trên mỗi thực thể hoạt động”) mang tính chiều thay vì được đếm từ một bảng phẳng.
• Chuyển việc làm mới theo lịch của Power BI từ việc duyệt toàn bộ lịch sử xuống một khoảng thời gian nhỏ hằng ngày bằng cách làm mới gia tăng.
• Chọn đúng mức chi tiết cho phishing: tổng số theo chiến dịch (vận hành) so với kết quả theo từng cá nhân và các sự kiện có kiểu (xem trước báo cáo).

​

Điều kiện tiên quyết

• Một khóa API có các quyền mà truy vấn của quý vị cần:
  • Ví dụ vận hành: activity:read, entity:read và simulation:read.
  • Phishing theo từng cá nhân thông qua các tập dữ liệu báo cáo: reporting:read. Xem Khóa API.
• Power BI Desktop, hoặc một không gian làm việc Power BI / Fabric nơi quý vị có thể tạo mô hình ngữ nghĩa và lên lịch làm mới.

​

Chọn đúng mức chi tiết

​

Thang độ khó

​

Mẫu kết nối (Power Query)

​

Hàm phân trang dùng chung

• URL cơ sở /v1 tĩnh, RelativePath và Query động. Bắt buộc đối với việc làm mới theo lịch và bước kiểm tra thông tin xác thực.
• ManualStatusHandling = {429} với số lần thử lại có giới hạn. Hàm đọc Retry-After khi Power Query cung cấp, nếu không thì chờ 30 giây, và dừng sau 5 phản hồi 429 liên tiếp với một lỗi tường minh thay vì lặp cho đến khi việc làm mới hết thời gian. 5xx được cố ý không thử lại — lỗi máy chủ cần được hiển thị, không âm thầm tạo ra một tập dữ liệu không đầy đủ.
• Timeout 60 giây. Các trang thường phản hồi trong chưa đầy một giây, do đó một phút không có phản hồi nghĩa là yêu cầu đã chết.
• Binary.Buffer trước Json.Document. Nếu không có bộ đệm, engine mashup có thể yêu cầu lại luồng phản hồi nếu đọc nó nhiều hơn một lần.
• baseQuery được truyền nguyên vẹn ở mỗi lần lặp. Mã thông báo trang là con trỏ có chữ ký, không trong suốt, gắn với tổ chức, thông tin xác thực, phiên bản hợp đồng, và dấu vân tay của bộ lọc và sắp xếp. Thay đổi bộ lọc giữa chừng sẽ bị từ chối như một mã thông báo không hợp lệ thay vì bắt đầu lại từ trang một.

let
    // Literal /v1 root. Callers pass the resource alone ("simulations").
    // US: "https://api.us-east-1.livingsecurity.ai/v1"
    BaseUrl = "https://api.eu-west-1.livingsecurity.ai/v1",

    Fn_FetchAll = (relativePath as text, baseQuery as record) as list =>
        // Walk next_page_token until null. Full pagination + 429 retry lives
        // in examples/powerbi/queries/Fn_FetchAll.pq.
        ...
in
    Fn_FetchAll

​

Truy vấn có kiểu cho từng endpoint

let
    Source = Fn_FetchAll("simulations", [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "name", "description", "status", "vectors",
            "difficulty_level", "difficulty_mode",
            "started_at", "completed_at", "created_at", "updated_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Flattened = Table.TransformColumns(
        Dropped,
        {
            {
                "vectors",
                each if _ = null then null
                     else Text.Combine(List.Transform(_, Text.From), ", "),
                type text
            }
        }),

    Typed = Table.TransformColumnTypes(
        Flattened,
        {
            { "id",           type text },
            { "name",         type text },
            { "description",  type text },
            { "status",       type text },
            { "started_at",   type datetimezone },
            { "completed_at", type datetimezone },
            { "created_at",   type datetimezone },
            { "updated_at",   type datetimezone }
        })
in
    Typed

let
    Source = Fn_FetchAll("entities", [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        { "id", "object", "type", "status", "display_name", "email",
          "created_at", "updated_at" },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",           type text },
            { "type",         type text },
            { "status",       type text },
            { "display_name", type text },
            { "email",        type text },
            { "created_at",   type datetimezone },
            { "updated_at",   type datetimezone }
        })
in
    Typed

​

Excel

1. Data → Get Data → From Other Sources → Blank Query.
2. Trong Power Query Editor, chọn Home → Trình chỉnh sửa nâng cao. Dán Fn_FetchAll trước, sau đó đổi tên truy vấn đó thành Fn_FetchAll (Query Settings → Name, hoặc nhấp chuột phải trong ngăn Queries → Rename).
3. Lặp lại cho Fn_GetJson, rồi cho từng truy vấn báo cáo.
4. Home → Close & Load → Close & Load To… mở hộp thoại Import Data. Chọn Only Create Connection cho Fn_FetchAll và Fn_GetJson (chúng là hàm, không phải bảng). Chọn Table cho từng truy vấn báo cáo mà quý vị muốn đưa vào worksheet.
5. Ở lần làm mới đầu tiên, chọn Basic: khóa API làm User name, một giá trị giữ chỗ như x làm Mật khẩu. Excel lưu một thông tin xác thực cho mỗi URL nguồn dữ liệu; các truy vấn sau đó truy cập cùng máy chủ /v1 sẽ dùng lại thông tin đó.

​

Tập dữ liệu xem trước báo cáo (phishing theo từng cá nhân)

GET /v1/reporting/datasets
GET /v1/reporting/datasets/simulation_results
GET /v1/reporting/datasets/simulation_events
GET /v1/reporting/datasets/entities
GET /v1/reporting/datasets/entity_versions
GET /v1/reporting/datasets/cohort_memberships

​

simulation_results

• Đường dẫn: GET /v1/reporting/simulation_results
• Mức chi tiết: thực thể × mô phỏng
• Bộ lọc: simulation, entity, updated_after, cộng với limit / page_token
• Đối tượng wire: reporting.simulation_result
• Khóa nối: entity_id, simulation_id

let
    Source = Fn_FetchAll(
        "reporting/simulation_results",
        [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "entity_id", "simulation_id", "status",
            "targeted_at", "delivered_at", "opened_at", "clicked_at",
            "credential_submitted_at", "reported_at",
            "email_subject", "sender_email", "difficulty_level",
            "created_at", "updated_at", "deleted_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",            type text },
            { "entity_id",     type text },
            { "simulation_id", type text },
            { "status",        type text },
            { "targeted_at",   type datetimezone },
            { "updated_at",    type datetimezone }
        })
in
    Typed

​

simulation_events

• Đường dẫn: GET /v1/reporting/simulation_events
• Mức chi tiết: một dữ kiện có kiểu cho mỗi tương tác được quan sát
• Bộ lọc: simulation, entity, event_type, occurred_after, cộng với limit / page_token
• Đối tượng wire: reporting.simulation_event
• Loại sự kiện: các mã thông báo công khai đã đóng như simulation.delivered, simulation.opened, simulation.link_clicked, simulation.credentials_submitted, simulation.reported — không phải các loại hoạt động phishing.simulation.* ClickHouse thô
• Thiết bị: device_type là lớp được suy ra (các mã thông báo quan sát được gồm desktop, mobile, tablet, unknown). user_agent thô không có trên /v1. IP thô không bao giờ có trên /v1 (không bao giờ được lưu trữ; chỉ có ip_hash đã thêm salt).

let
    Source = Fn_FetchAll(
        "reporting/simulation_events",
        [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "entity_id", "simulation_id",
            "event_type", "occurred_at",
            "email_subject", "sender_email", "sender_domain", "difficulty_tier",
            "device_type",
            "deleted_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",            type text },
            { "entity_id",     type text },
            { "simulation_id", type text },
            { "event_type",    type text },
            { "occurred_at",   type datetimezone }
        })
in
    Typed

​

entities

• Đường dẫn: GET /v1/reporting/entities
• Mức chi tiết: một dòng hiện tại cho mỗi thực thể
• Bộ lọc: type, updated_after, cộng với limit / page_token
• Đối tượng wire: reporting.entity
• Khóa nối: id / entity_id (cùng giá trị)

let
    Source = Fn_FetchAll("reporting/entities", [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "entity_id", "type", "status",
            "display_name", "created_at", "updated_at", "deleted_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",          type text },
            { "entity_id",   type text },
            { "type",        type text },
            { "status",      type text },
            { "display_name", type text },
            { "created_at",  type datetimezone },
            { "updated_at",  type datetimezone }
        })
in
    Typed

​

entity_versions và cohort_memberships

Không tồn tại bảng lịch sử phiên bản hoặc tư cách thành viên có thẩm quyền. Tập dữ liệu này chiếu dòng hiện tại thành một khoảng không giới hạn cuối (valid_to là null, is_current là true). valid_from là created_at hoặc nếu không thì updated_at đối với phiên bản thực thể, và là thời điểm quan sát yêu cầu đối với tư cách thành viên Nhóm. Các khoảng lịch sử đã đóng không được tạo ra giả.

• entity_versions: GET /v1/reporting/entity_versions. Cùng bộ lọc với entities. valid_from là created_at hoặc nếu không thì updated_at. Một thực thể có cả hai dấu thời gian là null sẽ bị bỏ qua.
• cohort_memberships: GET /v1/reporting/cohort_memberships. Bộ lọc: cohort, entity, updated_after. updated_at là lần cập nhật cuối của Nhóm để việc làm mới gia tăng luôn chính xác. valid_from là thời điểm quan sát yêu cầu. Nối entity_id với reporting.entities.id.

let
    Source = Fn_FetchAll("reporting/entity_versions", [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "entity_id", "type", "status", "display_name",
            "valid_from", "valid_to", "is_current",
            "created_at", "updated_at", "deleted_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",         type text },
            { "entity_id",  type text },
            { "valid_from", type datetimezone },
            { "is_current", type logical }
        })
in
    Typed

let
    Source = Fn_FetchAll("reporting/cohort_memberships", [ limit = "500" ]),

    AsTable = Table.FromRecords(
        Source,
        {
            "id", "object", "cohort_id", "entity_id",
            "valid_from", "valid_to", "is_current",
            "updated_at", "deleted_at"
        },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",         type text },
            { "cohort_id",  type text },
            { "entity_id",  type text },
            { "valid_from", type datetimezone },
            { "is_current", type logical },
            { "updated_at", type datetimezone }
        })
in
    Typed

​

Mô hình ngữ nghĩa lược đồ hình sao trên /v1/activities

Dates (dimension)
      │  1
      ▼  ∗
  Activities (fact)   1  ∗  ActivityParticipants (bridge)   ∗  1   Entities (dimension)

• Activities là bảng dữ kiện sự kiện ở mức chi tiết thực. Một dòng cho mỗi hoạt động. Người tham gia được loại bỏ ở đây và được dựng lại thành bảng riêng.
• ActivityParticipants tồn tại vì người tham gia thực sự là quan hệ một-nhiều, với các vai trò như actor và target. Làm phẳng vào Activities sẽ hoặc nhân đôi các dòng hoạt động (làm phồng mọi số đếm) hoặc loại bỏ các người tham gia bổ sung. Quan hệ với Activities là quan hệ hai chiều duy nhất của mô hình, nhờ đó bộ cắt lát thực thể tác động được tới bảng dữ kiện.
• Entities là chiều đặt tên cho người tham gia. Các dòng người tham gia trên một hoạt động mang entity_id và một vai trò nhưng không có tên hiển thị.
• Dates được tạo trong M (không có lệnh gọi API nào) và được đánh dấu là bảng ngày của mô hình. Điều đó giúp cho DAX time intelligence (DATESINPERIOD, DATEADD) hợp lệ. Các cột tên tháng và tên thứ trong tuần khai báo sortByColumn trên các cột số tương ứng để các hình ảnh trực quan không sắp xếp tháng theo thứ tự bảng chữ cái.

​

Cấu trúc bảng cầu nối

let
    WindowStart = DateTime.AddZone(RangeStart, 0),
    WindowEnd   = DateTime.AddZone(RangeEnd, 0),
    ToIso = (value as datetimezone) as text =>
        DateTimeZone.ToText(value,
            [ Format = "yyyy-MM-dd'T'HH:mm:ss'Z'", Culture = "en-US" ]),

    Source = Fn_FetchAll(
        "activities",
        [
            limit      = "100",
            start_date = ToIso(WindowStart - #duration(0, 0, 1, 0)),
            end_date   = ToIso(WindowEnd + #duration(0, 0, 1, 0))
        ]),

    AsTable = Table.FromRecords(
        Source,
        { "id", "object", "activity_type", "event_ts",
          "service_id", "participants" },
        MissingField.UseNull),

    Selected = Table.SelectColumns(AsTable, { "id", "event_ts", "participants" }),
    Renamed  = Table.RenameColumns(Selected, { { "id", "activity_id" } }),
    Expanded = Table.ExpandListColumn(Renamed, "participants"),
    NonNull  = Table.SelectRows(Expanded, each [participants] <> null),
    Fields   = Table.ExpandRecordColumn(
        NonNull, "participants",
        { "role", "entity_id", "display_name" }),

    Typed = Table.TransformColumnTypes(
        Fields,
        {
            { "activity_id",  type text },
            { "event_ts",     type datetimezone },
            { "role",         type text },
            { "entity_id",    type text },
            { "display_name", type text }
        }),

    Filtered = Table.SelectRows(
        Typed,
        each [event_ts] >= WindowStart and [event_ts] < WindowEnd)
in
    Filtered

​

Làm mới gia tăng

let
    WindowStart = DateTime.AddZone(RangeStart, 0),
    WindowEnd   = DateTime.AddZone(RangeEnd, 0),
    ToIso = (value as datetimezone) as text =>
        DateTimeZone.ToText(value,
            [ Format = "yyyy-MM-dd'T'HH:mm:ss'Z'", Culture = "en-US" ]),

    Source = Fn_FetchAll(
        "activities",
        [
            limit      = "100",
            start_date = ToIso(WindowStart - #duration(0, 0, 1, 0)),
            end_date   = ToIso(WindowEnd + #duration(0, 0, 1, 0))
        ]),

    AsTable = Table.FromRecords(
        Source,
        { "id", "object", "activity_type", "event_ts",
          "service_id", "participants" },
        MissingField.UseNull),

    Dropped = Table.RemoveColumns(AsTable, { "object", "participants" }),

    Typed = Table.TransformColumnTypes(
        Dropped,
        {
            { "id",            type text },
            { "activity_type", type text },
            { "event_ts",      type datetimezone },
            { "service_id",    type text }
        }),

    Filtered = Table.SelectRows(
        Typed,
        each [event_ts] >= WindowStart and [event_ts] < WindowEnd),

    WithDate = Table.AddColumn(
        Filtered, "event_date", each Date.From([event_ts]), type date)
in
    WithDate

​

Mở rộng cửa sổ làm mới vào API

​

Giới hạn tốc độ trong khi làm mới

• Việc duyệt một bảng diễn ra tuần tự. Mỗi yêu cầu trang cần mã thông báo của trang trước, do đó một bảng bị giới hạn bởi độ trễ bất kể kích thước trang.
• Việc làm mới đồng thời nhiều bảng làm tăng tải. Nhiều bảng lớn được làm mới song song là trường hợp chạm trần, đó là lý do đường thử lại 429 trong Fn_FetchAll quan trọng. Hãy ưu tiên ít bảng song song hơn thay vì giả định khả năng đồng thời không giới hạn.

​

Phiên bản hợp đồng và thông tin xác thực được lưu trữ

Expression.Error: The 'Living-Security-Version' header is only supported when
connecting anonymously.
Microsoft.Data.Mashup.ErrorCode = 10348.

​

Làm mới và xác minh mô hình của quý vị

​

Lựa chọn mô hình

• Tổng số theo chiến dịch và kết quả theo từng cá nhân có mức chi tiết khác nhau. SimulationResults gọi GET /v1/simulations/{id}/results (một GET cho mỗi lần chạy). Đối với phishing theo từng cá nhân, hãy thêm các truy vấn cho GET /v1/reporting/simulation_results và GET /v1/reporting/simulation_events (hoặc GET /v1/simulation_results vận hành nếu quý vị đã có simulation:read).
• vectors trên /v1/simulations được làm phẳng thành một chuỗi nối bằng dấu phẩy. Cột kiểu danh sách không thể được dùng để cắt lát như một chiều thực sự. Nếu một trang báo cáo cần lọc theo vector, hãy thêm bảng cầu nối mô phỏng-vector.

​

Bước tiếp theo