Power BI

Denne veiledningen er et helhetlig eksempel på hvordan man leser /v1 inn i Power BI. Den dekker tilkoblingsmønsteret i Power Query (M), en semantisk stjerneskjemamodell bygget på /v1/activities, inkrementell oppdatering, og når man bør bruke reporting-forhåndsvisningsdatasettene for utfall knyttet til phishing per person. Eksemplene bruker produksjonsverten i USA (https://api.us-east-1.livingsecurity.ai/v1). For en organisasjon i EU bruker du https://api.eu-west-1.livingsecurity.ai/v1 i både Fn_FetchAll og Fn_GetJson, og binder deretter datakildens legitimasjon til den verten. Se Regioner. Denne veiledningen bruker lagret Basic-legitimasjon med en API-nøkkel. Du trenger ingen OAuth-klient. Se Autentisering for valg av legitimasjon, og Developer Hub for tilgang og oppsett.

Hva dette eksempelet brukes til

Bruk det når du må:

Laste listeendepunktene i /v1 inn i et Power BI-datasett med korrekt markørbasert paginering og nytt forsøk ved ratebegrensning.
Bygge en semantisk modell der målinger («aktive enheter», «aktiviteter per aktiv enhet») er dimensjonelle i stedet for å telles fra en flat tabell.
Redusere en planlagt Power BI-oppdatering fra en full gjennomgang av historikken til et lite døgnvindu ved hjelp av inkrementell oppdatering.
Velge riktig granularitet for phishing: kampanjetotaler (operasjonelt) versus resultater per person og typede hendelser (forhåndsvisning av rapportering).

Forutsetninger

En API-nøkkel med de tillatelsene spørringene dine trenger:
- Operasjonelt eksempel: activity:read, entity:read og simulation:read.
- Phishing per person via rapporteringsdatasett: reporting:read. Se API-nøkler.
Power BI Desktop, eller et Power BI- / Fabric-arbeidsområde der du kan opprette en semantisk modell og planlegge oppdatering.

Velg riktig granularitet

/v1 tilbyr to beslektede flater for phishing. De er ikke utskiftbare.

Behov	Bruk	Tillatelse	Granularitet
Totaler for kampanjetrakt	`GET /v1/simulations/{id}/results`	`simulation:read`	Én rad per simulering (levert, åpnet, klikket, …)
Utfall per person (operasjonelt)	`GET /v1/simulation_results`	`simulation:read`	Én rad per enhet × simulering
Utfall per person (BI / rapportering)	`GET /v1/reporting/simulation_results`	`reporting:read`	Samme granularitet, BI-feltnavn (`entity_id`, `simulation_id`), `updated_after`-vannmerke
Typede interaksjonsfakta	`GET /v1/reporting/simulation_events`	`reporting:read`	Ett faktum per interaksjon (`simulation.link_clicked`, …), `occurred_after`
Gjeldende arbeidsstyrkedimensjon	`GET /v1/reporting/entities`	`reporting:read`	Én gjeldende rad per enhet. Koble på `reporting.simulation_results.entity_id = reporting.entities.id`
Gjeldende enhetsversjoner	`GET /v1/reporting/entity_versions`	`reporting:read`	Ett åpent, gjeldende intervall per enhet. Det finnes ingen tabell med versjonshistorikk
Gjeldende kohortmedlemskap	`GET /v1/reporting/cohort_memberships`	`reporting:read`	Ett gjeldende faktum per `(cohort_id, entity_id)`. Det finnes ingen tabell med medlemskapshistorikk
Koblingsrygg for alle aktivitetstyper	`GET /v1/activities`	`activity:read`	Én hendelse per aktivitet, med nøstet `participants[]`

Eksempelspørringene for Power BI nedenfor kaller de operasjonelle rutene (/v1/simulations, /v1/simulations/{id}/results, /v1/activities, /v1/entities). For rapportering av phishing per person bør du bruke reporting-forhåndsvisningsfamilien nedenfor. En nøkkel som kun har fått reporting:read kan ikke kalle operasjonell /v1/simulation_results (API-et returnerer 403).

Vanskelighetsskala

Vanskelighetsgraden for simuleringer er et heltall fra 1 til 5 på /v1/simulations (difficulty_level), /v1/simulation_results (difficulty_level), /v1/activities-egenskaper (difficulty_tier) og /v1/reporting/simulation_events (difficulty_tier). 1 er enklest og 5 er vanskeligst. Adaptive og progressive simuleringer har ingen enkeltverdi på kampanjenivå, så /v1/simulations.difficulty_level er null, mens difficulty_level per mottaker på resultater fortsatt kan være satt. For å tilordne til eldre eksporter med lav/middels/høy, behandler du 1–2 som lav, 3 som middels og 4–5 som høy.

Ikke bygg nye BI-integrasjoner mot udokumenterte nettverkskall fra Dashbord eller den eldre, kuraterte oversikten over Public API for /api/v1. Autentiser mot organisasjonens regionale /v1-vert med en API-nøkkel fra Developer Hub. Se Regioner.

Tilkoblingsmønster (Power Query)

Fire regler ligger til grunn for hver spørring i eksempelet. Hver av dem håndheves av Power BI-tjenesten, og er ikke et spørsmål om stil.

Hold basis-URL-en i Web.Contents statisk og la den ende på /v1

Legg alt dynamisk i RelativePath og Query. Det første argumentet til Web.Contents må være en bokstavelig streng som ender ved organisasjonens regionale /v1-rot:

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

Kallere sender deretter kun ressursen ("simulations", ikke "v1/simulations"). Ikke lim inn en amerikansk vert for en organisasjon i EU.Hvis det første argumentet bygges ved strengsammenslåing, kan Power BI-tjenesten ikke identifisere datakilden statisk, og planlagt oppdatering mislykkes med en feil om «dynamisk datakilde», selv om spørringen fungerer i Power BI Desktop.

Oppgi API-nøkkelen som lagret Basic-legitimasjon, ikke i spørringsteksten

Når Power BI ber om legitimasjon for datakilden /v1, velger du Basic og limer inn API-nøkkelen som brukernavn. Legg inn en plassholder som x i feltet passord. Power BI-tjenesten avviser et tomt passord selv om API-et ignorerer det feltet. Nøkkel som passord med et plassholder-brukernavn fungerer også.Ikke legg til en Authorization-header i M. Det fungerer på din lokale maskin, men bakes deretter inn i spørringsfilen med nøkkelen og skaper problemer for planlagt oppdatering.

La tilkoblingstesten i legitimasjonsdialogen kjøre

GET /v1 er autentisert: den returnerer 200 med en gyldig nøkkel og 401 uten. Pek datakilden mot …/v1 og ikke hopp over testen – en gyldig nøkkel lagres, mens en tilbakekalt eller ugyldig nøkkel mislykkes umiddelbart.Eldre eksempler brukte den rene verten som datakilde og ba deg hoppe over testen fordi GET / alltid er 404. Pek disse modellene om til …/v1.

Sett limit=500 eksplisitt på hver listespørring

Standard sidestørrelse på hvert listeendepunkt i /v1 er 25. Hvis du beholder standarden, øker antall forespørsler for de samme dataene. Spørringsverdier må være tekst – limit = "500" i M, ikke limit = 500.

Delt pagineringsfunksjon

Hver spørring i eksempelet kaller én enkelt Fn_FetchAll som går gjennom next_page_token til den er null (se paginering). Dens viktigste egenskaper:

Statisk /v1-basis-URL, dynamisk RelativePath og Query. Påkrevd for planlagt oppdatering og for legitimasjonstesten.
ManualStatusHandling = {429} med begrenset antall nye forsøk. Funksjonen leser Retry-After når Power Query eksponerer den, ellers venter den 30 sekunder, og gir opp etter 5 påfølgende 429-svar med en eksplisitt feil i stedet for å gå i løkke til oppdateringen går ut på tid. 5xx prøves bevisst ikke på nytt – en serverfeil skal komme til syne, ikke i det stille gi et delvis datasett.
Timeout på 60 sekunder. Sider svarer vanligvis på godt under ett sekund, så ett minutts stillhet betyr at forespørselen er død.
Binary.Buffer før Json.Document. Uten buffering kan mashup-motoren be om svarstrømmen på nytt hvis den leser den mer enn én gang.
baseQuery sendes uendret i hver iterasjon. Sidetokener er ugjennomsiktige, signerte markører bundet til organisasjonen, legitimasjonen, kontraktsversjonen og fingeravtrykket av filtre og sortering. Hvis et filter endres midt i gjennomgangen, avvises det som et ugyldig token i stedet for å starte på nytt fra side én.

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

Typede spørringer per endepunkt

Hver forbruker av Fn_FetchAll følger samme mønster: kall endepunktet, projiser en fast kolonneliste, fjern diskriminatoren object, og typ tidsstempler som datetimezone slik at datomål ikke forskyves i det stille på grunn av tidssonen til oppdateringskapasiteten.

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

En eksplisitt kolonneliste på Table.FromRecords holder skjemaet stabilt når et endepunkt returnerer null rader. En bar Table.FromRecords({}) gir en tabell uten kolonner, og alle senere trinn mislykkes på grunn av manglende felt.

Excel

Den samme Power Query (M) kjører i Excels Get & Transform – det er samme motor som i Power BI Desktop. Bruk dette når du vil ha en regnearktabell i stedet for en semantisk modell. I Excel for Windows (Microsoft 365, Excel 2024, 2021, 2019 eller 2016):

Data → Get Data → From Other Sources → Blank Query.
I Power Query Editor velger du Hjem → Avansert Redigerer. Lim inn Fn_FetchAll først, og gi deretter spørringen navnet Fn_FetchAll (Innstillinger for spørring → Name, eller høyreklikk i Queries-ruten → Rename).
Gjenta for Fn_GetJson, og deretter for hver rapportspørring.
Hjem → Close & Load → Close & Load To… åpner dialogen Import Data. Velg Only Create Connection for Fn_FetchAll og Fn_GetJson (de er funksjoner, ikke tabeller). Velg Table for hver rapportspørring du vil ha i et regneark.
Ved første oppdatering velger du Basic: API-nøkkelen som User name, en plassholder som x som passord. Excel lagrer én legitimasjon per datakilde-URL; senere spørringer som treffer samme /v1-vert gjenbruker den.

Close & Load To… kan være nedtonet første gang du oppretter en spørring i en arbeidsbok. Bruk Close & Load, velg deretter i Excel Data → Queries & Connections, høyreklikk spørringen og velg Load To. Denne fremgangsmåten er dokumentert av Microsoft for dette tilfellet.

Du kan ikke sende Living-Security-Version fra Power Query på en autentisert kilde – samme begrensning som i Power BI. Fest versjonen på tjenestekontoen eller send api_version i spørringsposten. Se Kontraktsversjoner og lagret legitimasjon. Ferdige rapportspørringer (kolonnetilordninger og avvik fra en tidligere leverandørs eksport):

Samsvar per person

Opplæringspåmeldinger med granularitet person × tildeling.

Phishing-logg for e-post

Phishing-interaksjoner på hendelsesnivå, siste 12 måneder.

Mest utsatte brukere

Oppsummering per person over 12 måneder for klikk, legitimasjon og rapportering.

Forhåndsvisningsdatasett for rapportering (phishing per person)

Forhåndsvisningsfamilien for rapportering tilbyr datasett for phishing per person. Den krever reporting:read og rapporteringstilgang for organisasjonen din. Bruk datasettkatalogen nedenfor til å undersøke skjemaene og databehandlingsreglene. Oppdag den aktive katalogen:

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

Hvert datasett deklarerer granularitet, primærnøkkel, koblinger, vannmerke, korrigerings- og slettingsregel.

simulation_results

Sti: GET /v1/reporting/simulation_results
Granularitet: enhet × simulering
Filtre: simulation, entity, updated_after, pluss limit / page_token
Wire-objekt: reporting.simulation_result
Koblingsnøkler: 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

Bruk updated_after som inkluderende nedre vannmerke når du oppdaterer nylige partisjoner. Mutable resultatdimensjoner omskrives på stedet under samme id.

simulation_events

Sti: GET /v1/reporting/simulation_events
Granularitet: ett typet faktum per observerte interaksjon
Filtre: simulation, entity, event_type, occurred_after, pluss limit / page_token
Wire-objekt: reporting.simulation_event
Hendelsestyper: lukkede offentlige tokens som simulation.delivered, simulation.opened, simulation.link_clicked, simulation.credentials_submitted, simulation.reported – ikke rå ClickHouse-aktivitetstyper av typen phishing.simulation.*
Enhet: device_type er den avledede klassen (observerte tokens inkluderer desktop, mobile, tablet, unknown). Rå user_agent finnes ikke på /v1. Rå IP finnes aldri på /v1 (lagres aldri; kun saltet 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

Bruk occurred_after for inkrementelle hendelsesinnlastinger. Fakta er kun-tillegg; sene ankomster er nye rader.

entities

Sti: GET /v1/reporting/entities
Granularitet: én gjeldende rad per enhet
Filtre: type, updated_after, pluss limit / page_token
Wire-objekt: reporting.entity
Koblingsnøkkel: id / entity_id (samme verdi)

Koble phishing-fakta til personer med reporting.simulation_results.entity_id = reporting.entities.id. Operasjonell GET /v1/entities forblir på entity:read og er en annen tillatelse.

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

Disse to datasettene har et navngitt unntak som kun gjelder gjeldende tilstand:

Det finnes ingen autoritativ tabell for versjons- eller medlemskapshistorikk. Dette datasettet projiserer den gjeldende raden som ett åpent intervall (valid_to er null, is_current er true). valid_from er created_at eller ellers updated_at for enhetsversjoner, og forespørselens observasjonstidspunkt for kohortmedlemskap. Lukkede historiske intervaller fabrikkeres ikke.

entity_versions: GET /v1/reporting/entity_versions. Samme filtre som entities. valid_from er created_at eller ellers updated_at. En enhet der begge tidsstemplene er null utelates.
cohort_memberships: GET /v1/reporting/cohort_memberships. Filtre: cohort, entity, updated_after. updated_at er siste oppdatering av kohorten, slik at inkrementell oppdatering forblir pålitelig. valid_from er forespørselens observasjonstidspunkt. Koble entity_id til 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

Semantisk stjerneskjemamodell på /v1/activities

/v1/activities er organisasjonens tidsstemplede hendelsesstrøm. Den har ingen numeriske mål – hver mengde i en rapport er et radantall – noe som gjør et stjerneskjema til et naturlig valg.

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

Activities er hendelsesfaktaet på reell granularitet. Én rad per aktivitet. Deltakere fjernes her og bygges opp igjen som sin egen tabell.
ActivityParticipants finnes fordi deltakere faktisk er én-til-mange, med roller som actor og target. Flating ut på Activities ville enten duplisert aktivitetsrader (og blåst opp alle tellinger) eller forkastet ytterligere deltakere. Relasjonen til Activities er modellens eneste toveisrelasjon, slik at en enhetsslicer når faktatabellen.
Entities er dimensjonen som navngir deltakere. Deltakerrader på en aktivitet har entity_id og en rolle, men ikke et visningsnavn.
Dates genereres i M (null API-kall) og markeres som modellens datotabell. Det er dette som gjør DAX-funksjoner for tidsetterretning (DATESINPERIOD, DATEADD) tillatt. Kolonner for måneds- og ukedagsnavn deklarerer sortByColumn på de numeriske tvillingkolonnene, slik at visualiseringer ikke sorterer måneder alfabetisk.

Alle mål er eksplisitte (modellen setter discourageImplicitMeasures): totalt antall aktiviteter, aktive enheter, aktiviteter per aktiv enhet, dager med aktivitet, og et 7-dagers glidende døgngjennomsnitt.

Utforming av koblingstabellen

ActivityParticipants går gjennom /v1/activities og ekspanderer participants-arrayen til én rad per deltaker:

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 går gjennom /v1/activities uavhengig i stedet for å referere til spørringen Activities. I Power BI henter to spørringer som lastes som to tabeller hver for seg ved oppdatering. Ved å holde dem uavhengige kan tjenesten oppdatere partisjonene i begge tabellene parallelt.

Inkrementell oppdatering

Begge tabellene på faktanivå (Activities og ActivityParticipants) deklarerer en inkrementell oppdateringspolicy i Power BI: behold 5 år med årlige partisjoner, importer de siste 14 dagene på nytt ved hver oppdatering. Mekanismen er et par DateTime-parametere, RangeStart og RangeEnd, som Power BI-tjenesten binder på nytt per partisjon ved oppdatering. Hver faktaspørring bretter disse parameterne inn i API-ets filtre start_date og end_date, slik at antall forespørsler per partisjon står i forhold til partisjonen, ikke til total historikk. Spørringen utvider API-vinduet med ett minutt på hver side og anvender den nøyaktige halvåpne grensen [RangeStart, RangeEnd) lokalt på nytt, slik at partisjonens korrekthet ikke avhenger av om serveren behandler grensene sine som inkluderende eller ekskluderende.

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

Den første oppdateringen etter en distribusjon anvender policyen: en full historisk innlasting, som er langsom. Hver oppdatering etter det berører bare det inkrementelle vinduet. Målt på et datasett med ca. 158 000 aktiviteter og ca. 2 300 enheter:

Oppdatering	Tidsbruk
Første (anvendelse av policy, full historisk innlasting)	~31 min
Hver oppdatering etter det	~15 s

Det klassiske REST-endepunktet for oppdatering i Power BI (POST .../refreshes med kun notifyOption) ignorerer oppdateringspolicyer i det stille og gjør en full gjennomgang hver gang. For å anvende policyen gjennom REST-API-et bruker du utvidet oppdatering: send type, commitMode og applyRefreshPolicy i forespørselens body. Oppdateringer utløst av planleggeren i Power BI-tjenesten anvender alltid policyer – denne egenheten gjelder kun REST-kallet.

Vinduet på 14 dager er bevisst romslig. Aktivitetsinnhenting er ikke kun-tillegg-på-nåtidspunktet: etterfylling fra koblinger legger inn hendelser med tidsstempler fra fortiden. Et vindu på 1–2 dager ville gått glipp av dem for alltid.

Utvide oppdateringsvinduet inn i API-et

GET /v1/activities godtar filtrene start_date og end_date som Power BI-parameterne bretter seg inn i, og filtrerer event_ts mellom grensene. Entities er en dimensjon, så dette eksempelet oppdaterer den fullstendig hver gang i stedet for inkrementelt. Rapporteringsdatasett bruker sine egne vannmerker (updated_after, occurred_after) i stedet for datovinduet for aktiviteter.

Ratebegrensninger under oppdatering

/v1 håndhever separate budsjetter per nøkkel og per IP (se ratebegrensninger). Respekter 429 + Retry-After; ikke hardkod et forespørselsbudsjett inn i modellen. To egenskaper ved Power BI-oppdateringer er viktige:

En enkelt tabellgjennomgang er sekvensiell. Hver sideforespørsel trenger forrige sides token, så én tabell er latensbundet uavhengig av sidestørrelse.
Samtidige tabelloppdateringer multipliseres. Når flere store tabeller oppdateres parallelt, nås taket, og det er derfor 429-stien for nye forsøk i Fn_FetchAll er viktig. Foretrekk færre parallelle tabeller fremfor å anta ubegrenset samtidighet.

Logikken for nye forsøk er testet mot en reell, mettet begrenser. En oppdatering som kjørte mens en parallell arbeidsbelastning bevisst holdt nøkkelen ved taket fullførte likevel og ga samme radantall som en basislinje uten konkurranse – nye forsøk ga komplette sider, ikke hull.

Kontraktsversjoner og lagret legitimasjon

/v1 godtar en forespørselsheader Living-Security-Version for å feste en publisert kontraktsversjon (se API-hurtigstart). Power Query kan ikke sende den headeren når datakilden bruker lagret legitimasjon – bare anonyme datakilder tillater egendefinerte headere. Hvis du legger den til, mislykkes en oppdatering med:

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

Behold nøkkelen i Power BIs lagrede legitimasjon og utelat den egendefinerte headeren. Når forespørselen ikke angir eksplisitt versjon, bruker API-et tjenestekontoens festede contract_version, eller den nyeste publiserte versjonen hvis ingen versjon er festet. Bekreft kontoens kontraktsversjon med API-administratoren før du publiserer en oppdatering. Se API-endringsloggen for støttede versjoner. Hvis en oppdatering begynner å oppføre seg uventet, kan du inspisere API-ets svarheader Living-Security-Version for å se hvilken kontrakt som faktisk behandlet forespørselen.

Oppdater og verifiser modellen din

Publiser den semantiske modellen til Power BI-arbeidsområdet ditt, bind den lagrede legitimasjonen til den regionale /v1-kilden, og kjør en oppdatering før du aktiverer en tidsplan. Gå gjennom oppdateringshistorikken for feil eller ufullstendige lesinger. Sjekk radantall mot en uavhengig API-lesing med de samme filtrene. Pagineringsveiledningen inneholder Python- og cURL-eksempler for å lese et komplett resultatsett. En oppdatering som bare leser den første siden kan se vellykket ut på et lite datasett; sammenlign antallet før du stoler på rapporten.

Modellvalg

Kampanjetotaler og resultater per person har ulik granularitet. SimulationResults kaller GET /v1/simulations/{id}/results (ett GET per kjøring). For phishing per person legger du til spørringer for GET /v1/reporting/simulation_results og GET /v1/reporting/simulation_events (eller operasjonell GET /v1/simulation_results hvis du allerede har simulation:read).
vectors på /v1/simulations er flatet ut til en kommaseparert streng. En kolonne av listetype kan ikke brukes som en reell dimensjon i slicere. Hvis en rapportside må filtrere på vektor, legger du til en koblingstabell mellom simulering og vektor.

Neste trinn

Developer Hub

Opprett en tjenestekonto og en API-nøkkel for Power BI.

API-hurtigstart

Autentiser forespørsler til /v1 med Basic-autentisering.

Paginering

Listeomslaget, markørtokener og filterstabilitet gjennom en hel gjennomgang.

Ratebegrensninger

Budsjetter per nøkkel og per IP, 429-kontrakten og veiledning for nye forsøk.

Utviklersenter

Offentlig API v1

API v1-referanse

Hva dette eksempelet brukes til

Forutsetninger

Velg riktig granularitet

Vanskelighetsskala

Tilkoblingsmønster (Power Query)

Delt pagineringsfunksjon

Typede spørringer per endepunkt

Excel

Samsvar per person

Phishing-logg for e-post

Mest utsatte brukere

Forhåndsvisningsdatasett for rapportering (phishing per person)

simulation_results

simulation_events

entities

entity_versions og cohort_memberships

Semantisk stjerneskjemamodell på /v1/activities

Utforming av koblingstabellen

Inkrementell oppdatering

Utvide oppdateringsvinduet inn i API-et

Ratebegrensninger under oppdatering

Kontraktsversjoner og lagret legitimasjon

Oppdater og verifiser modellen din

Modellvalg

Neste trinn

Developer Hub

API-hurtigstart

Paginering

Ratebegrensninger

Utviklersenter

Offentlig API v1

API v1-referanse

​Hva dette eksempelet brukes til

​Forutsetninger

​Velg riktig granularitet

​Vanskelighetsskala

​Tilkoblingsmønster (Power Query)

​Delt pagineringsfunksjon

​Typede spørringer per endepunkt

​Excel

Samsvar per person

Phishing-logg for e-post

Mest utsatte brukere

​Forhåndsvisningsdatasett for rapportering (phishing per person)

​simulation_results

​simulation_events

​entities

​entity_versions og cohort_memberships

​Semantisk stjerneskjemamodell på /v1/activities

​Utforming av koblingstabellen

​Inkrementell oppdatering

​Utvide oppdateringsvinduet inn i API-et

​Ratebegrensninger under oppdatering

​Kontraktsversjoner og lagret legitimasjon

​Oppdater og verifiser modellen din

​Modellvalg

​Neste trinn

Developer Hub

API-hurtigstart

Paginering

Ratebegrensninger

Hva dette eksempelet brukes til

Forutsetninger

Velg riktig granularitet

Vanskelighetsskala

Tilkoblingsmønster (Power Query)

Delt pagineringsfunksjon

Typede spørringer per endepunkt

Excel

Forhåndsvisningsdatasett for rapportering (phishing per person)

simulation_results

simulation_events

entities

entity_versions og cohort_memberships

Semantisk stjerneskjemamodell på /v1/activities

Utforming av koblingstabellen

Inkrementell oppdatering

Utvide oppdateringsvinduet inn i API-et

Ratebegrensninger under oppdatering

Kontraktsversjoner og lagret legitimasjon

Oppdater og verifiser modellen din

Modellvalg

Neste trinn