Power BI

이 가이드는 /v1를 Power BI로 읽어 들이는 전 과정을 보여 주는 예제입니다. Power Query(M) 연결 패턴, /v1/activities 기반의 스타 스키마 시맨틱 모델, 증분 새로 고침, 그리고 개인별 피싱 결과에 reporting 미리 보기 데이터셋을 사용해야 하는 경우를 다룹니다. 예제에서는 미국 프로덕션 호스트(https://api.us-east-1.livingsecurity.ai/v1)를 사용합니다. EU 조직의 경우 Fn_FetchAll와 Fn_GetJson 모두에서 https://api.eu-west-1.livingsecurity.ai/v1을 사용한 다음, 데이터 원본 자격 증명을 해당 호스트에 바인딩하십시오. 리전을 참조하십시오. 이 가이드는 API 키와 함께 저장된 Basic 자격 증명을 사용합니다. OAuth 클라이언트는 필요하지 않습니다. 자격 증명 선택 사항은 인증을, 액세스 및 설정은 개발자 허브를 참조하십시오.

이 예제의 용도

다음과 같은 경우에 사용하십시오.

올바른 커서 페이지 매김과 속도 제한 재시도를 적용하여 /v1 목록 엔드포인트를 Power BI 데이터셋으로 로드해야 하는 경우
측정값(“활성 엔터티”, “활성 엔터티당 활동”)을 단순 테이블의 행 수 집계가 아니라 차원 기반으로 구성한 시맨틱 모델을 구축해야 하는 경우
증분 새로 고침을 사용하여 예약된 Power BI 새로 고침을 전체 이력 탐색에서 소규모 일일 범위로 줄여야 하는 경우
적절한 피싱 그레인을 선택해야 하는 경우: 캠페인 합계(운영용)와 개인별 결과 및 유형별 이벤트(보고용 미리 보기) 중에서 선택

사전 요구 사항

쿼리에 필요한 권한이 있는 API 키:
- 운영용 예제: activity:read, entity:read, simulation:read
- 보고용 데이터셋을 통한 개인별 피싱: reporting:read API 키를 참조하십시오.
Power BI Desktop 또는 시맨틱 모델을 만들고 새로 고침을 예약할 수 있는 Power BI / Fabric 작업 영역

적절한 그레인 선택

/v1는 피싱에 대해 서로 관련된 두 가지 표면을 제공합니다. 두 표면은 서로 바꿔 사용할 수 없습니다.

필요 사항	사용	권한	그레인
캠페인 퍼널 합계	`GET /v1/simulations/{id}/results`	`simulation:read`	시뮬레이션당 한 행(전달, 열람, 클릭, …)
개인별 결과(운영용)	`GET /v1/simulation_results`	`simulation:read`	엔터티 × 시뮬레이션당 한 행
개인별 결과(BI / 보고용)	`GET /v1/reporting/simulation_results`	`reporting:read`	동일한 그레인, BI 필드 이름(`entity_id`, `simulation_id`), `updated_after` 워터마크
유형별 상호작용 팩트	`GET /v1/reporting/simulation_events`	`reporting:read`	상호작용당 한 팩트(`simulation.link_clicked`, …), `occurred_after`
현재 인력 차원	`GET /v1/reporting/entities`	`reporting:read`	엔터티당 현재 행 한 개. `reporting.simulation_results.entity_id = reporting.entities.id`에 조인
현재 엔터티 버전	`GET /v1/reporting/entity_versions`	`reporting:read`	엔터티당 종료 시점이 없는 현재 구간 한 개. 버전 이력 테이블은 없음
현재 코호트 멤버십	`GET /v1/reporting/cohort_memberships`	`reporting:read`	`(cohort_id, entity_id)`당 현재 팩트 한 개. 멤버십 이력 테이블은 없음
모든 활동 유형을 위한 조인 스파인	`GET /v1/activities`	`activity:read`	활동당 이벤트 한 개, 중첩된 `participants[]`

아래의 Power BI 예제 쿼리는 운영용 경로(/v1/simulations, /v1/simulations/{id}/results, /v1/activities, /v1/entities)를 호출합니다. 개인별 피싱 보고에는 아래의 reporting 미리 보기 패밀리를 사용하는 것이 좋습니다. reporting:read 권한만 부여된 키는 운영용 /v1/simulation_results를 호출할 수 없습니다(API가 403를 반환함).

난이도 척도

시뮬레이션 난이도는 /v1/simulations(difficulty_level), /v1/simulation_results(difficulty_level), /v1/activities 속성(difficulty_tier), /v1/reporting/simulation_events(difficulty_tier)에서 1–5 정수입니다. 1이 가장 쉽고 5가 가장 어렵습니다. 적응형 및 점진형 시뮬레이션에는 캠페인 수준의 단일 값이 없으므로 /v1/simulations.difficulty_level은 null이며, 결과의 수신자별 difficulty_level은 여전히 설정될 수 있습니다. 기존의 낮음/중간/높음 내보내기에 매핑하려면 1–2은 낮음, 3은 중간, 4–5은 높음으로 처리하십시오.

문서화되지 않은 대시보드 네트워크 호출이나 기존의 선별된 /api/v1 Public API 개요를 기반으로 새로운 BI 연동을 구축하지 마십시오. 개발자 허브 API 키를 사용하여 조직의 리전별 /v1 호스트에 인증하십시오. 리전을 참조하십시오.

연결 패턴(Power Query)

예제의 모든 쿼리는 네 가지 규칙을 기반으로 합니다. 각 규칙은 스타일 선호가 아니라 Power BI 서비스에 의해 강제됩니다.

Web.Contents 기본 URL을 정적으로 유지하고 /v1에서 끝내십시오

동적인 모든 값은 RelativePath와 Query에 넣으십시오. Web.Contents의 첫 번째 인수는 조직의 리전별 /v1 루트에서 끝나는 리터럴 문자열이어야 합니다.

미국: https://api.us-east-1.livingsecurity.ai/v1
EU: https://api.eu-west-1.livingsecurity.ai/v1

그러면 호출자는 리소스만 전달합니다("v1/simulations"가 아니라 "simulations"). EU 조직에 미국 호스트를 붙여 넣지 마십시오.첫 번째 인수가 문자열 연결로 만들어지면 Power BI 서비스가 데이터 원본을 정적으로 식별할 수 없으며, 쿼리가 Power BI Desktop에서는 작동하더라도 예약된 새로 고침이 “동적 데이터 원본” 오류로 실패합니다.

API 키는 쿼리 텍스트에 넣지 말고 저장된 Basic 자격 증명으로 제공하십시오

Power BI가 /v1 데이터 원본의 자격 증명을 요청하면 Basic을 선택하고 API 키를 사용자 이름으로 붙여 넣으십시오. 비밀번호 필드에는 x 같은 자리 표시자를 입력하십시오. API는 이 필드를 무시하지만 Power BI 서비스는 빈 비밀번호를 거부합니다. 자리 표시자 사용자 이름에 키를 비밀번호로 입력하는 방식도 작동합니다.M에서 Authorization 헤더를 추가하지 마십시오. 데스크톱에서는 작동하지만 키가 쿼리 파일에 그대로 포함되며 예약된 새로 고침과 충돌합니다.

자격 증명 대화 상자의 연결 테스트가 실행되도록 하십시오

GET /v1는 인증이 필요합니다. 유효한 키로는 200을 반환하고 키가 없으면 401을 반환합니다. 데이터 원본이 …/v1를 가리키도록 설정하고 테스트를 건너뛰지 마십시오. 올바른 키는 저장되고, 폐기되었거나 형식이 잘못된 키는 즉시 실패합니다.이전 예제에서는 호스트만을 데이터 원본으로 사용하고 GET /가 항상 404이라는 이유로 테스트를 건너뛰라고 안내했습니다. 해당 모델은 …/v1를 가리키도록 다시 설정하십시오.

모든 목록 쿼리에 limit=500을 명시적으로 설정하십시오

모든 /v1 목록 엔드포인트의 기본 페이지 크기는 25입니다. 기본값을 그대로 두면 동일한 데이터에 대해 요청 수가 늘어납니다. 쿼리 값은 텍스트여야 하므로 M에서 limit = 500가 아니라 limit = "500"를 사용하십시오.

공유 페이지 매김 함수

예제의 모든 쿼리는 next_page_token이 null이 될 때까지 탐색하는 단일 Fn_FetchAll를 호출합니다(페이지 매김 참조). 주요 특징은 다음과 같습니다.

정적 /v1 기본 URL, 동적 RelativePath 및 Query. 예약된 새로 고침과 자격 증명 테스트에 필요합니다.
제한된 재시도를 포함한 ManualStatusHandling = {429}. 이 함수는 Power Query에서 노출되는 경우 Retry-After를 읽고, 그렇지 않으면 30초 동안 대기하며, 연속 5회의 429 응답 후에는 새로 고침 시간 초과까지 반복하지 않고 명시적인 오류와 함께 중단합니다. 5xx은 의도적으로 재시도하지 않습니다. 서버 오류는 부분 데이터셋을 조용히 생성하는 대신 드러나야 하기 때문입니다.
60초 Timeout. 페이지는 일반적으로 1초 미만에 응답하므로 1분 동안 응답이 없으면 요청이 중단된 것입니다.
Json.Document 전에 Binary.Buffer. 버퍼링이 없으면 매시업 엔진이 응답 스트림을 두 번 이상 읽을 때 다시 요청할 수 있습니다.
baseQuery은 모든 반복에서 변경 없이 전달됩니다. 페이지 토큰은 조직, 자격 증명, 계약 버전, 필터 및 정렬의 핑거프린트에 바인딩된 불투명한 서명 커서입니다. 탐색 도중 필터를 변경하면 첫 페이지부터 다시 시작하지 않고 잘못된 토큰으로 거부됩니다.

Fn_FetchAll.pq — base and call shape

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

엔드포인트별 형식 지정 쿼리

Fn_FetchAll를 사용하는 모든 소비자는 동일한 형태를 따릅니다. 엔드포인트를 호출하고, 고정된 열 목록을 프로젝션하고, object 식별자를 제거하고, 타임스탬프를 datetimezone로 지정하여 날짜 측정값이 새로 고침 용량의 표준 시간대에 따라 조용히 어긋나지 않도록 합니다.

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

Table.FromRecords에 명시적인 열 목록을 지정하면 엔드포인트가 0개의 행을 반환하더라도 스키마가 안정적으로 유지됩니다. 단순한 Table.FromRecords({})는 열이 없는 테이블을 생성하며, 이후의 모든 단계가 누락된 필드 때문에 실패합니다.

Excel

동일한 Power Query(M)를 Excel의 데이터 가져오기 및 변환에서 실행할 수 있습니다. Power BI Desktop과 같은 엔진입니다. 시맨틱 모델 대신 워크시트 테이블이 필요할 때 사용하십시오. Windows용 Excel(Microsoft 365, Excel 2024, 2021, 2019 또는 2016)에서는 다음과 같이 합니다.

Data → Get Data → From Other Sources → Blank Query.
Power Query 편집기에서 홈 → 고급 편집기를 선택합니다. Fn_FetchAll를 먼저 붙여 넣은 다음, 해당 쿼리의 이름을 Fn_FetchAll(으)로 변경합니다(Query Settings → Name 또는 Queries 창에서 마우스 오른쪽 버튼 클릭 → Rename).
Fn_GetJson에 대해 반복한 다음, 각 보고서 쿼리에 대해 반복합니다.
**홈 → Close & Load → Close & Load To…**를 선택하면 Import Data 대화 상자가 열립니다. Fn_FetchAll와 Fn_GetJson는 테이블이 아니라 함수이므로 Only Create Connection을 선택합니다. 워크시트에 표시하려는 각 보고서 쿼리에는 Table을 선택합니다.
처음 새로 고침할 때 Basic을 선택하고, API 키를 User name에, x 같은 자리 표시자를 Password에 입력합니다. Excel은 데이터 원본 URL별로 자격 증명 하나를 저장하며, 동일한 /v1 호스트에 접근하는 이후 쿼리는 이를 재사용합니다.

통합 문서에서 쿼리를 처음 만들 때는 **Close & Load To…**가 비활성화되어 있을 수 있습니다. 이 경우 Close & Load를 사용한 다음, Excel에서 Data → Queries & Connections를 선택하고 쿼리를 마우스 오른쪽 버튼으로 클릭하여 Load To를 선택하십시오. 이 경로는 Microsoft가 이러한 경우에 대해 문서화한 방법입니다.

인증된 원본에서는 Power Query로 Living-Security-Version를 전송할 수 없습니다. 이는 Power BI와 동일한 제한입니다. 서비스 계정을 고정하거나 쿼리 레코드에 api_version를 전달하십시오. 계약 버전 및 저장된 자격 증명을 참조하십시오. 바로 사용할 수 있는 보고서 쿼리(열 매핑 및 이전 공급자의 내보내기와의 차이점):

개인별 준수 현황

사람 × 할당 그레인의 교육 등록 현황.

이메일 피싱 로그

최근 12개월간 이벤트 수준의 피싱 상호작용.

가장 취약한 사용자

개인별 12개월 클릭, 자격 증명 및 신고 롤업.

보고용 미리 보기 데이터셋(개인별 피싱)

보고용 미리 보기 패밀리는 개인별 피싱을 위한 데이터셋을 제공합니다. 이를 사용하려면 reporting:read 및 조직에 대한 보고 액세스 권한이 필요합니다. 아래의 데이터셋 카탈로그를 사용하여 스키마와 데이터 정책을 확인하십시오. 라이브 카탈로그 확인:

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

경로: GET /v1/reporting/simulation_results
그레인: 엔터티 × 시뮬레이션
필터: simulation, entity, updated_after 및 limit / page_token
와이어 객체: reporting.simulation_result
조인 키: entity_id, simulation_id

ReportingSimulationResults.pq (sketch)

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

최근 파티션을 새로 고칠 때는 updated_after를 포함 하한 워터마크로 사용하십시오. 변경 가능한 결과 차원은 동일한 id 아래에서 그 자리에서 다시 기록됩니다.

simulation_events

경로: GET /v1/reporting/simulation_events
그레인: 관찰된 상호작용당 유형별 팩트 한 개
필터: simulation, entity, event_type, occurred_after 및 limit / page_token
와이어 객체: reporting.simulation_event
이벤트 유형: simulation.delivered, simulation.opened, simulation.link_clicked, simulation.credentials_submitted, simulation.reported 같은 닫힌 공개 토큰이며, 원시 ClickHouse phishing.simulation.* 활동 유형이 아닙니다.
장치: device_type는 파생된 클래스입니다(관찰되는 토큰에는 desktop, mobile, tablet, unknown 포함). 원시 user_agent는 /v1에 포함되지 않습니다. 원시 IP는 /v1에 절대 포함되지 않습니다(저장되지 않으며 솔트가 적용된 ip_hash만 사용).

ReportingSimulationEvents.pq (sketch)

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

증분 이벤트 로드에는 occurred_after를 사용하십시오. 팩트는 추가 전용이며, 늦게 도착한 데이터는 새 행으로 추가됩니다.

entities

경로: GET /v1/reporting/entities
그레인: 엔터티당 현재 행 한 개
필터: type, updated_after 및 limit / page_token
와이어 객체: reporting.entity
조인 키: id / entity_id(동일한 값)

피싱 팩트를 사람에 조인하려면 reporting.simulation_results.entity_id = reporting.entities.id를 사용하십시오. 운영용 GET /v1/entities는 entity:read에 그대로 있으며 다른 권한입니다.

ReportingEntities.pq

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 및 cohort_memberships

이 두 데이터셋에는 현재 상태만 제공하는 명명된 예외가 적용됩니다.

신뢰할 수 있는 버전 또는 멤버십 이력 테이블이 없습니다. 이 데이터셋은 현재 행을 종료 시점이 없는 하나의 구간으로 투영합니다(valid_to는 null이고 is_current는 true임). valid_from는 엔터티 버전의 경우 created_at이며, 없으면 updated_at이고, 코호트 멤버십의 경우 요청 관찰 시간입니다. 종료된 과거 구간은 만들어 내지 않습니다.

entity_versions: GET /v1/reporting/entity_versions. 필터는 entities와 동일합니다. valid_from는 created_at이며, 없으면 updated_at입니다. 두 타임스탬프가 모두 null인 엔터티는 제외됩니다.
cohort_memberships: GET /v1/reporting/cohort_memberships. 필터: cohort, entity, updated_after. updated_at는 코호트의 마지막 업데이트이므로 증분 새로 고침의 정확성이 유지됩니다. valid_from는 요청 관찰 시간입니다. entity_id를 reporting.entities.id에 조인하십시오.

ReportingEntityVersions.pq

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

ReportingCohortMemberships.pq

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

/v1/activities 기반 스타 스키마 시맨틱 모델

/v1/activities는 조직의 타임스탬프가 있는 이벤트 스트림입니다. 숫자형 측정값이 없으며 보고서의 모든 수량이 행 수이므로 스타 스키마가 자연스럽게 적합합니다.

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

**Activities**는 실제 그레인의 이벤트 팩트입니다. 활동당 한 행입니다. 참가자는 여기에서 제외되고 별도의 테이블로 재구성됩니다.
**ActivityParticipants**는 참가자가 actor 및 target 같은 역할을 가진 일대다 관계이기 때문에 존재합니다. Activities에 평면화하면 활동 행이 중복되어 모든 집계가 부풀려지거나 추가 참가자가 버려집니다. Activities와의 관계는 모델에서 유일한 양방향 관계이므로 엔터티 슬라이서가 팩트 테이블에 도달합니다.
**Entities**는 참가자의 이름을 제공하는 차원입니다. 활동의 참가자 행에는 entity_id와 역할이 있지만 표시 이름은 없습니다.
**Dates**는 M에서 생성되며(API 호출 0회) 모델의 날짜 테이블로 표시됩니다. 이 때문에 DAX 시간 인텔리전스(DATESINPERIOD, DATEADD)를 사용할 수 있습니다. 월 및 요일 이름 열은 숫자 쌍 열에 sortByColumn를 선언하여 시각적 개체가 월을 알파벳순으로 정렬하지 않도록 합니다.

모든 측정값은 명시적입니다(모델이 discourageImplicitMeasures를 설정함). 총 활동, 활성 엔터티, 활성 엔터티당 활동, 활동이 있는 일수, 7일 후행 일일 평균이 있습니다.

브리지 테이블 형태

ActivityParticipants는 /v1/activities을 탐색하고 participants 배열을 참가자당 한 행으로 펼칩니다.

ActivityParticipants.pq

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

ActivityParticipants는 Activities 쿼리를 참조하지 않고 /v1/activities를 독립적으로 탐색합니다. Power BI에서는 두 개의 테이블로 로드된 두 쿼리가 새로 고침 시점에 각각 독립적으로 데이터를 가져옵니다. 독립성을 유지하면 서비스가 두 테이블의 파티션을 병렬로 새로 고칠 수 있습니다.

증분 새로 고침

두 팩트 그레인 테이블(Activities 및 ActivityParticipants)은 Power BI 증분 새로 고침 정책을 선언합니다. 연 단위 파티션으로 5년을 보관하고, 새로 고침할 때마다 최근 14일을 다시 가져옵니다. 이 메커니즘은 Power BI 서비스가 새로 고침 시점에 파티션별로 다시 바인딩하는 DateTime 매개 변수 쌍, RangeStart와 RangeEnd를 사용합니다. 각 팩트 쿼리는 이 매개 변수를 API의 start_date 및 end_date 필터에 반영하므로, 파티션 수준의 요청량은 전체 이력이 아니라 파티션에 비례합니다. 쿼리는 API 범위를 양쪽으로 1분씩 넓히고 정확한 반개방 [RangeStart, RangeEnd) 경계를 로컬에서 다시 적용하므로, 서버가 경계를 포함으로 처리하는지 제외로 처리하는지에 관계없이 파티션의 정확성이 유지됩니다.

Activities.pq — the fold that makes incremental refresh work

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

배포 후 첫 번째 새로 고침에서 정책이 적용되며, 전체 이력을 로드하므로 느립니다. 그 이후의 모든 새로 고침은 증분 범위만 처리합니다. 약 158,000건의 활동과 약 2,300개의 엔터티로 구성된 데이터셋에서 측정한 결과:

새로 고침	소요 시간
첫 번째(정책 적용, 전체 이력 로드)	약 31분
이후 모든 새로 고침	약 15초

Power BI 클래식 새로 고침 REST 엔드포인트(notifyOption만 포함한 POST .../refreshes)는 새로 고침 정책을 조용히 무시하고 매번 전체를 탐색합니다. REST API를 통해 정책을 적용하려면 향상된 새로 고침을 사용하여 본문에 type, commitMode, applyRefreshPolicy을 전송하십시오. Power BI 서비스 스케줄러에서 트리거한 새로 고침은 항상 정책을 적용하며, 이 특이 사항은 REST 호출에만 해당합니다.

14일 범위는 의도적으로 넉넉하게 설정되었습니다. 활동 수집은 현재 시점에만 추가되는 방식이 아닙니다. 커넥터 백필은 과거 타임스탬프를 가진 이벤트를 로드합니다. 1-2일 범위에서는 이러한 이벤트를 영구적으로 놓치게 됩니다.

API로 새로 고침 범위 넓히기

GET /v1/activities는 Power BI 매개 변수가 반영되는 start_date 및 end_date 필터를 허용하며, 두 경계 사이에서 event_ts를 필터링합니다. Entities는 차원이므로 이 예제에서는 증분 방식이 아니라 매번 전체를 새로 고칩니다. 보고용 데이터셋은 활동 날짜 범위 대신 자체 워터마크(updated_after, occurred_after)를 사용합니다.

새로 고침 중 속도 제한

/v1는 키별 및 IP별 예산을 별도로 적용합니다(속도 제한 참조). 429 + Retry-After를 준수하고, 모델에 요청 예산을 하드코딩하지 마십시오. Power BI 새로 고침에서는 다음 두 가지 특성이 중요합니다.

단일 테이블 탐색은 순차적입니다. 각 페이지 요청에는 이전 페이지의 토큰이 필요하므로, 페이지 크기와 관계없이 하나의 테이블은 지연 시간에 좌우됩니다.
동시 테이블 새로 고침은 부하가 누적됩니다. 여러 대형 테이블이 병렬로 새로 고쳐지는 경우가 한도에 도달하는 상황이며, 이 때문에 Fn_FetchAll의 429 재시도 경로가 중요합니다. 무제한 동시성을 가정하기보다 병렬 테이블 수를 줄이는 것이 좋습니다.

재시도는 실제로 포화된 제한기를 대상으로 검증되었습니다. 병렬 워크로드가 의도적으로 키를 한도까지 사용하고 있는 동안 실행된 새로 고침도 정상적으로 완료되었으며, 경합이 없는 기준선과 동일한 행 수를 생성했습니다. 재시도는 누락 없이 완전한 페이지를 반환했습니다.

계약 버전 및 저장된 자격 증명

/v1는 게시된 계약 버전을 고정하기 위한 Living-Security-Version 요청 헤더를 허용합니다(API 빠른 시작 참조). 데이터 원본이 저장된 자격 증명을 사용하는 경우 Power Query는 해당 헤더를 전송할 수 없으며, 사용자 지정 헤더는 익명 데이터 원본에서만 허용됩니다. 헤더를 추가하면 새로 고침이 다음 오류와 함께 실패합니다.

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

키는 Power BI의 저장된 자격 증명에 보관하고 사용자 지정 헤더는 생략하십시오. 요청에 명시적인 버전이 없으면 API는 서비스 계정에 고정된 contract_version을 사용하며, 고정된 버전이 없으면 게시된 최신 버전을 사용합니다. 새로 고침을 게시하기 전에 API 관리자에게 계정의 계약 버전을 확인하십시오. 지원되는 버전은 API 변경 로그를 참조하십시오. 새로 고침이 예기치 않게 동작하기 시작하면 API의 Living-Security-Version 응답 헤더를 확인하여 실제로 어떤 계약이 요청을 처리했는지 확인하십시오.

모델 새로 고침 및 확인

시맨틱 모델을 Power BI 작업 영역에 게시하고, 저장된 자격 증명을 리전별 /v1 원본에 바인딩한 다음, 일정을 사용하도록 설정하기 전에 새로 고침을 실행하십시오. 새로 고침 기록에서 실패 또는 불완전한 읽기가 있는지 검토하십시오. 동일한 필터를 사용한 독립적인 API 읽기 결과와 행 수를 비교하십시오. 페이지 매김 가이드에는 전체 결과 집합을 읽는 Python 및 cURL 예제가 포함되어 있습니다. 첫 페이지만 읽는 새로 고침은 소규모 데이터셋에서는 성공한 것처럼 보일 수 있으므로, 보고서를 신뢰하기 전에 행 수를 비교하십시오.

모델 선택 사항

캠페인 합계와 개인별 결과는 그레인이 다릅니다. SimulationResults는 GET /v1/simulations/{id}/results을 호출합니다(실행당 GET 한 번). 개인별 피싱에는 GET /v1/reporting/simulation_results 및 GET /v1/reporting/simulation_events에 대한 쿼리를 추가하십시오(이미 simulation:read을 보유한 경우에는 운영용 GET /v1/simulation_results).
/v1/simulations의 vectors은 쉼표로 연결된 문자열로 평면화됩니다. 목록 형식 열은 실제 차원으로 슬라이스할 수 없습니다. 보고서 페이지에서 벡터별로 필터링해야 하는 경우 시뮬레이션-벡터 브리지 테이블을 추가하십시오.

다음 단계

개발자 허브

Power BI용 서비스 계정과 API 키를 만듭니다.

API 빠른 시작

Basic 인증으로 /v1 요청을 인증합니다.

페이지 매김

목록 엔벨로프, 커서 토큰, 탐색 중 필터 안정성.

속도 제한

키별 및 IP별 예산, 429 규약, 재시도 지침.

개발자 허브

공개 API v1

API v1 참조

이 예제의 용도

사전 요구 사항

적절한 그레인 선택

난이도 척도

연결 패턴(Power Query)

공유 페이지 매김 함수

엔드포인트별 형식 지정 쿼리

Excel

개인별 준수 현황

이메일 피싱 로그

가장 취약한 사용자

보고용 미리 보기 데이터셋(개인별 피싱)

simulation_results

simulation_events

entities

entity_versions 및 cohort_memberships

/v1/activities 기반 스타 스키마 시맨틱 모델

브리지 테이블 형태

증분 새로 고침

API로 새로 고침 범위 넓히기

새로 고침 중 속도 제한

계약 버전 및 저장된 자격 증명

모델 새로 고침 및 확인

모델 선택 사항

다음 단계

개발자 허브

API 빠른 시작

페이지 매김

속도 제한

개발자 허브

공개 API v1

API v1 참조

​이 예제의 용도

​사전 요구 사항

​적절한 그레인 선택

​난이도 척도

​연결 패턴(Power Query)

​공유 페이지 매김 함수

​엔드포인트별 형식 지정 쿼리

​Excel

개인별 준수 현황

이메일 피싱 로그

가장 취약한 사용자

​보고용 미리 보기 데이터셋(개인별 피싱)

​simulation_results

​simulation_events

​entities

​entity_versions 및 cohort_memberships

​/v1/activities 기반 스타 스키마 시맨틱 모델

​브리지 테이블 형태

​증분 새로 고침

​API로 새로 고침 범위 넓히기

​새로 고침 중 속도 제한

​계약 버전 및 저장된 자격 증명

​모델 새로 고침 및 확인

​모델 선택 사항

​다음 단계

개발자 허브

API 빠른 시작

페이지 매김

속도 제한

이 예제의 용도

사전 요구 사항

적절한 그레인 선택

난이도 척도

연결 패턴(Power Query)

공유 페이지 매김 함수

엔드포인트별 형식 지정 쿼리

Excel

보고용 미리 보기 데이터셋(개인별 피싱)

simulation_results

simulation_events

entities

entity_versions 및 cohort_memberships

/v1/activities 기반 스타 스키마 시맨틱 모델

브리지 테이블 형태

증분 새로 고침

API로 새로 고침 범위 넓히기

새로 고침 중 속도 제한

계약 버전 및 저장된 자격 증명

모델 새로 고침 및 확인

모델 선택 사항

다음 단계