Power BI

Tämä opas on kattava esimerkki siitä, miten /v1 luetaan Power BI:hin. Se käsittelee Power Query (M) -yhteysmallin, rakenteen /v1/activities päälle rakennetun tähtiskeemapohjaisen semanttisen mallin, inkrementaalisen päivityksen sekä sen, milloin reporting-esikatselutietojoukkoja kannattaa käyttää henkilökohtaisiin tietojenkalastelun tuloksiin. Esimerkeissä käytetään Yhdysvaltojen tuotantopalvelinta (https://api.us-east-1.livingsecurity.ai/v1). EU-organisaatiossa käytä https://api.eu-west-1.livingsecurity.ai/v1 sekä kohdassa Fn_FetchAll että kohdassa Fn_GetJson ja sido tietolähteen tunnistetiedot kyseiseen palvelimeen. Katso Alueet. Tässä oppaassa käytetään tallennettuja Basic-tunnistetietoja ja API-avainta. OAuth-asiakasta ei tarvita. Tunnistetietovaihtoehdot on kuvattu kohdassa Todennus, ja käyttöoikeudet sekä käyttöönotto kohdassa Developer Hub.

Mihin tätä esimerkkiä käytetään

Käytä sitä, kun haluat:

Ladata /v1-luettelopäätepisteet Power BI -tietojoukkoon oikealla kursoripohjaisella sivutuksella ja nopeusrajoituksen uudelleenyrityksellä.
Rakentaa semanttisen mallin, jossa mittarit (”aktiiviset entiteetit”, ”aktiviteetit aktiivista entiteettiä kohti”) ovat dimensionaalisia eivätkä perustu litteän taulukon rivien laskentaan.
Lyhentää ajastettua Power BI -päivitystä koko historian läpikäynnistä pieneen päivittäiseen ikkunaan inkrementaalisen päivityksen avulla.
Valita oikean tietojenkalastelutietojen tarkkuustason: kampanjakohtaiset summat (operatiivinen) tai henkilökohtaiset tulokset ja tyypitetyt tapahtumat (reporting-esikatselu).

Edellytykset

API-avain, jolla on kyselyidesi edellyttämät käyttöoikeudet:
- Operatiivinen esimerkki: activity:read, entity:read ja simulation:read.
- Henkilökohtaiset tietojenkalastelutiedot reporting-tietojoukoista: reporting:read. Katso API-avaimet.
Power BI Desktop tai Power BI- tai Fabric-työtila, jossa voit luoda semanttisen mallin ja ajastaa päivityksen.

Valitse oikea tarkkuustaso

/v1 tarjoaa tietojenkalasteluun kaksi toisiinsa liittyvää pintaa. Ne eivät ole keskenään vaihdettavissa.

Tarve	Käytä	Käyttöoikeus	Tarkkuustaso
Kampanjan suppilon summat	`GET /v1/simulations/{id}/results`	`simulation:read`	Yksi rivi simulaatiota kohti (toimitettu, avattu, klikattu, …)
Henkilökohtaiset tulokset (operatiivinen)	`GET /v1/simulation_results`	`simulation:read`	Yksi rivi entiteetti × simulaatio
Henkilökohtaiset tulokset (BI / raportointi)	`GET /v1/reporting/simulation_results`	`reporting:read`	Sama tarkkuustaso, BI-kenttien nimet (`entity_id`, `simulation_id`), `updated_after`-vesileima
Tyypitetyt vuorovaikutustiedot	`GET /v1/reporting/simulation_events`	`reporting:read`	Yksi tieto vuorovaikutusta kohti (`simulation.link_clicked`, …), `occurred_after`
Nykyinen työvoimadimensio	`GET /v1/reporting/entities`	`reporting:read`	Yksi nykyinen rivi entiteettiä kohti. Liitä `reporting.simulation_results.entity_id = reporting.entities.id`
Entiteettien nykyiset versiot	`GET /v1/reporting/entity_versions`	`reporting:read`	Yksi avoin nykyinen aikaväli entiteettiä kohti. Versiohistoriataulukkoa ei ole
Nykyiset kohorttijäsenyydet	`GET /v1/reporting/cohort_memberships`	`reporting:read`	Yksi nykyinen tieto kohdetta `(cohort_id, entity_id)` kohti. Jäsenyyshistoriataulukkoa ei ole
Liitosrunko kaikille aktiviteettityypeille	`GET /v1/activities`	`activity:read`	Yksi tapahtuma aktiviteettia kohti, sisäkkäinen `participants[]`

Alla olevat Power BI -esimerkkikyselyt kutsuvat operatiivisia reittejä (/v1/simulations, /v1/simulations/{id}/results, /v1/activities, /v1/entities). Henkilökohtaiseen tietojenkalastelun raportointiin kannattaa käyttää alla kuvattua reporting-esikatseluperhettä. Avain, jolle on myönnetty vain reporting:read, ei voi kutsua operatiivista /v1/simulation_results-päätepistettä (API palauttaa 403).

Vaikeusasteikko

Simulaation vaikeustaso on kokonaisluku 1–5 ominaisuuksissa /v1/simulations (difficulty_level), /v1/simulation_results (difficulty_level), /v1/activities (difficulty_tier) ja /v1/reporting/simulation_events (difficulty_tier). 1 on helpoin ja 5 vaikein. Mukautuvilla ja etenevillä simulaatioilla ei ole yhtä kampanjatason arvoa, joten /v1/simulations.difficulty_level on null, vaikka vastaanottajakohtainen difficulty_level tuloksissa voi silti olla asetettu. Vanhoihin matala/keskitaso/korkea-vienteihin voit yhdistää arvot seuraavasti: 1–2 on matala, 3 keskitaso ja 4–5 korkea.

Älä rakenna uusia BI-integraatioita Kojelaudan dokumentoimattomien verkkokutsujen tai vanhan kuratoidun /api/v1 Public API -yleiskatsauksen varaan. Todenna organisaation alueelliseen /v1-palvelimeen Developer Hub -API-avaimella. Katso Alueet.

Yhteysmalli (Power Query)

Jokaisen esimerkin kyselyn taustalla on neljä sääntöä. Jokaisen niistä valvoo Power BI Service, eivätkä ne ole tyylipreferenssejä.

Pidä Web.Contents-perus-URL staattisena ja päätä se kohtaan /v1

Sijoita kaikki dynaaminen kohtiin RelativePath ja Query. Kohteen Web.Contents ensimmäisen argumentin on oltava kirjaimellinen merkkijono, joka päättyy organisaation alueellisen /v1-juureen:

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

Kutsujat välittävät sitten pelkän resurssin ("simulations", ei "v1/simulations"). Älä liitä yhdysvaltalaista palvelinta EU-organisaatiolle.Jos ensimmäinen argumentti muodostetaan merkkijonojen yhdistämisellä, Power BI Service ei pysty tunnistamaan tietolähdettä staattisesti, ja ajastettu päivitys epäonnistuu ”dynamic data source” -virheeseen, vaikka kysely toimii Power BI Desktopissa.

Anna API-avain tallennettuna Basic-tunnistetietona, älä kyselyn tekstissä

Kun Power BI pyytää tunnistetietoja tietolähteelle /v1, valitse Basic ja liitä API-avain username-kenttään. Kirjoita password-kenttään paikkamerkki, esimerkiksi x. Power BI Service hylkää tyhjän salasanan, vaikka API ei käytä kyseistä kenttää. Myös avain salasanana ja paikkamerkki käyttäjätunnuksena toimii.Älä lisää Authorization-otsaketta M-koodissa. Se toimii työasemallasi, mutta tallentaa avaimen kyselytiedostoon ja häiritsee ajastettua päivitystä.

Anna tunnistetietoikkunan yhteystestin suorittua

GET /v1 vaatii todennuksen: se palauttaa 200 kelvollisella avaimella ja 401 ilman avainta. Osoita tietolähde kohteeseen …/v1 äläkä ohita testiä — kelvollinen avain tallentuu, mutta peruutettu tai virheellinen avain epäonnistuu heti.Vanhemmissa esimerkeissä tietolähteenä käytettiin pelkkää palvelinta ja neuvottiin ohittamaan testi, koska GET / on aina 404. Osoita nämä mallit uudelleen kohteeseen …/v1.

Aseta limit=500 erikseen jokaiseen luettelokyselyyn

Oletussivukoko jokaisessa /v1-luettelopäätepisteessä on 25. Oletuksen jättäminen kasvattaa pyyntöjen määrää samalle datalle. Kyselyarvojen on oltava tekstiä — limit = "500" M-koodissa, ei limit = 500.

Jaettu sivutusfunktio

Jokainen esimerkin kysely kutsuu yhtä Fn_FetchAll-funktiota, joka käy läpi next_page_token, kunnes se on null (katso sivutus). Sen keskeiset ominaisuudet:

Staattinen /v1-perus-URL, dynaaminen RelativePath ja Query. Vaaditaan ajastettua päivitystä ja tunnistetietojen testausta varten.
ManualStatusHandling = {429} rajatulla uudelleenyrityksellä. Funktio lukee Retry-After, kun Power Query tarjoaa sen, muuten odottaa 30 sekuntia ja luovuttaa 5 peräkkäisen 429-vastauksen jälkeen antaen selkeän virheen sen sijaan, että silmukoisi, kunnes päivitys aikakatkaistaan. 5xx-virhettä ei yritetä uudelleen tarkoituksella — palvelinvirheen on tultava näkyviin eikä sen pidä hiljaa tuottaa osittaista tietojoukkoa.
60 sekunnin Timeout. Sivut vastaavat tyypillisesti selvästi alle sekunnissa, joten minuutin hiljaisuus tarkoittaa, että pyyntö on kuollut.
Binary.Buffer ennen Json.Document. Ilman puskurointia mashup- moottori voi pyytää vastausvirran uudelleen, jos se lukee sen useammin kuin kerran.
baseQuery välitetään muuttumattomana jokaisella iteraatiolla. Sivutunnisteet ovat läpinäkymättömiä, allekirjoitettuja kursoreita, jotka on sidottu organisaatioon, tunnistetietoihin, sopimusversioon sekä suodattimien ja lajittelun sormenjälkeen. Suodattimen muuttaminen kesken läpikäynnin hylätään virheellisenä tunnisteena sen sijaan, että läpikäynti aloitettaisiin uudelleen ensimmäiseltä sivulta.

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

Tyypitetyt kyselyt päätepistettä kohti

Jokainen kohteen Fn_FetchAll käyttäjä noudattaa samaa mallia: kutsu päätepistettä, rajaa kiinteä sarakeluettelo, poista object-erottelija ja tyypitä aikaleimat muotoon datetimezone, jotta päivämäärämittarit eivät siirry huomaamatta päivityskapasiteetin aikavyöhykkeen mukaan.

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

Eksplisiittinen sarakeluettelo kohteessa Table.FromRecords pitää skeeman vakaana, kun päätepiste palauttaa nolla riviä. Pelkkä Table.FromRecords({}) tuottaa taulukon ilman sarakkeita, ja kaikki myöhemmät vaiheet epäonnistuvat puuttuviin kenttiin.

Excel

Sama Power Query (M) toimii Excelin Get & Transform -toiminnossa — se on sama moottori kuin Power BI Desktopissa. Käytä tätä, kun haluat työtaulukkoon taulukon semanttisen mallin sijaan. Excel for Windowsissa (Microsoft 365, Excel 2024, 2021, 2019 tai 2016):

Data → Get Data → From Other Sources → Blank Query.
Valitse Power Query Editorissa Home → Advanced Editor. Liitä ensin Fn_FetchAll ja nimeä kysely sitten uudelleen nimellä Fn_FetchAll (Query Settings → Name tai napsauta hiiren kakkospainikkeella Queries-ruudussa → Rename).
Toista kohdalle Fn_GetJson ja sen jälkeen jokaiselle raporttikyselylle.
Home → Close & Load → Close & Load To… avaa Import Data -valintaikkunan. Valitse Only Create Connection kyselyille Fn_FetchAll ja Fn_GetJson (ne ovat funktioita, eivät taulukoita). Valitse Table jokaiselle raporttikyselylle, jonka haluat työtaulukkoon.
Valitse ensimmäisessä päivityksessä Basic: API-avain kohtaan User name ja paikkamerkki, esimerkiksi x, kohtaan Password. Excel tallentaa yhden tunnistetiedon tietolähteen URL-osoitetta kohti; myöhemmät kyselyt, jotka käyttävät samaa /v1-palvelinta, käyttävät sitä uudelleen.

Close & Load To… voi olla harmaana, kun luot työkirjaan ensimmäisen kyselyn. Käytä Close & Load -toimintoa, valitse sitten Excelissä Data → Queries & Connections, napsauta kyselyä hiiren kakkospainikkeella ja valitse Load To. Microsoft dokumentoi tämän polun kyseistä tilannetta varten.

Et voi lähettää otsaketta Living-Security-Version Power Queryssa todennetusta lähteestä — sama rajoitus koskee Power BI:tä. Kiinnitä palvelutili tiettyyn versioon tai välitä api_version kyselyn tietueessa. Katso Sopimusversiot ja tallennetut tunnistetiedot. Valmiit raporttikyselyt (sarakekuvaukset ja poikkeamat aiemman toimittajan viennistä):

Henkilökohtainen vaatimustenmukaisuus

Koulutuksen ilmoittautumiset henkilö × tehtävä -tarkkuudella.

Sähköpostitietojenkalastelun loki

Tapahtumatason tietojenkalasteluvuorovaikutukset, viimeiset 12 kuukautta.

Alttiimmat käyttäjät

Henkilökohtainen 12 kuukauden klikkaus-, tunnistetieto- ja ilmoitusyhteenveto.

Reporting-esikatselutietojoukot (henkilökohtainen tietojenkalastelu)

Reporting-esikatseluperhe tarjoaa tietojoukkoja henkilökohtaiseen tietojenkalasteluun. Se edellyttää reporting:read ja organisaatiosi raportointikäyttöoikeutta. Tarkastele sen skeemoja ja tietokäytäntöjä alla olevan tietojoukkoluettelon avulla. Hae ajantasainen luettelo:

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

Jokainen tietojoukko määrittää tarkkuustason, pääavaimen, liitokset, vesileiman, korjauskäytännön ja poistokäytännön.

simulation_results

Polku: GET /v1/reporting/simulation_results
Tarkkuustaso: entiteetti × simulaatio
Suodattimet: simulation, entity, updated_after sekä limit / page_token
Wire-objekti: reporting.simulation_result
Liitosavaimet: 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

Käytä updated_after sisältävänä alarajavesileimana, kun päivität viimeaikaisia osioita. Muuttuvat tulosdimensiot päivittyvät paikallaan saman id alla.

simulation_events

Polku: GET /v1/reporting/simulation_events
Tarkkuustaso: yksi tyypitetty tieto havaittua vuorovaikutusta kohti
Suodattimet: simulation, entity, event_type, occurred_after sekä limit / page_token
Wire-objekti: reporting.simulation_event
Tapahtumatyypit: suljetut julkiset tunnisteet, kuten simulation.delivered, simulation.opened, simulation.link_clicked, simulation.credentials_submitted, simulation.reported — eivät raakoja ClickHouse-phishing.simulation.*-aktiviteettityyppejä
Laite: device_type on johdettu luokka (havaittuja tunnisteita ovat desktop, mobile, tablet, unknown). Raaka user_agent ei ole kohteessa /v1. Raaka IP ei koskaan ole kohteessa /v1 (sitä ei koskaan tallenneta; vain suolattu 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

Käytä occurred_after inkrementaalisiin tapahtumalatauksiin. Tiedot ovat vain lisättäviä; myöhästyneet tiedot ovat uusia rivejä.

entities

Polku: GET /v1/reporting/entities
Tarkkuustaso: yksi nykyinen rivi entiteettiä kohti
Suodattimet: type, updated_after sekä limit / page_token
Wire-objekti: reporting.entity
Liitosavain: id / entity_id (sama arvo)

Liitä tietojenkalastelutiedot henkilöihin käyttämällä reporting.simulation_results.entity_id = reporting.entities.id. Operatiivinen GET /v1/entities pysyy kohteessa entity:read ja vaatii eri käyttöoikeuden.

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

Näillä kahdella tietojoukolla on nimetty poikkeus, jossa ne sisältävät vain nykyisen tilan:

Luotettavaa versio- tai jäsenyyshistoriataulukkoa ei ole. Tämä tietojoukko projisoi nykyisen rivin yhtenä avoimena aikavälinä (valid_to on null, is_current on true). valid_from on created_at tai muuten updated_at entiteettiversioille ja pyynnön havaintoaika kohorttijäsenyyksille. Suljettuja historiallisia aikavälejä ei muodosteta keinotekoisesti.

entity_versions: GET /v1/reporting/entity_versions. Samat suodattimet kuin entiteeteillä. valid_from on created_at tai muuten updated_at. Entiteetti, jonka molemmat aikaleimat ovat null, jätetään pois.
cohort_memberships: GET /v1/reporting/cohort_memberships. Suodattimet: cohort, entity, updated_after. updated_at on kohortin viimeisin päivitys, jotta inkrementaalinen päivitys pysyy luotettavana. valid_from on pyynnön havaintoaika. Liitä entity_id kohteeseen 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

Tähtiskeemapohjainen semanttinen malli kohteessa /v1/activities

/v1/activities on organisaation aikaleimattu tapahtumavirta. Siinä ei ole numeerisia mittareita — jokainen raportin suure on rivimäärä — mikä tekee tähtiskeemasta luontevan ratkaisun.

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

Activities on tapahtumatieto todellisella tarkkuustasolla. Yksi rivi aktiviteettia kohti. Osallistujat jätetään tästä pois ja rakennetaan uudelleen omaksi taulukokseen.
ActivityParticipants on olemassa, koska osallistujat ovat todella yksi-moneen-suhteessa ja heillä on rooleja, kuten actor ja target. Litistäminen kohteeseen Activities joko monistaisi aktiviteettirivejä (paisuttaen jokaista määrää) tai hävittäisi muut osallistujat. Suhde kohteeseen Activities on mallin ainoa kaksisuuntainen suhde, joten entiteettiviipaloija ulottuu faktataulukkoon.
Entities on dimensio, joka nimeää osallistujat. Aktiviteetin osallistujarivit sisältävät entity_id ja roolin, mutta eivät näyttönimeä.
Dates luodaan M-koodilla (nolla API-kutsua) ja merkitään mallin päivämäärätaulukoksi. Tämä tekee DAX-aikatiedustelutiedon (DATESINPERIOD, DATEADD) käytöstä sallittua. Kuukauden ja viikonpäivän nimisarakkeet määrittävät sortByColumn numeerisille vastinsarakkeilleen, jotta visualisoinnit eivät lajittele kuukausia aakkosjärjestykseen.

Kaikki mittarit ovat eksplisiittisiä (malli asettaa discourageImplicitMeasures): aktiviteetit yhteensä, aktiiviset entiteetit, aktiviteetit aktiivista entiteettiä kohti, aktiviteettipäivät ja 7 päivän liukuva päiväkeskiarvo.

Siltataulukon rakenne

ActivityParticipants käy läpi /v1/activities ja purkaa participants-taulukon yhdeksi riviksi osallistujaa kohti:

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 käy läpi /v1/activities itsenäisesti sen sijaan, että se viittaisi kyselyyn Activities. Power BI:ssä kaksi kyselyä, jotka on ladattu kahtena taulukkona, noutavat kumpikin tietonsa itsenäisesti päivityksen aikana. Itsenäisyys antaa palvelun päivittää molempien taulukoiden osiot rinnakkain.

Inkrementaalinen päivitys

Molemmat faktatason taulukot (Activities ja ActivityParticipants) määrittävät Power BI:n inkrementaalisen päivityskäytännön: säilytä 5 vuotta vuosiosioita ja tuo viimeiset 14 päivää uudelleen jokaisessa päivityksessä. Mekanismina on DateTime-parametripari, RangeStart ja RangeEnd, jonka Power BI Service sitoo uudelleen osiokohtaisesti päivityksen aikana. Jokainen faktakysely välittää nämä parametrit API:n suodattimiin start_date ja end_date, joten osiotason pyyntömäärä riippuu osiosta eikä koko historiasta. Kysely laajentaa API-ikkunaa minuutilla kummallakin puolella ja soveltaa tarkan puoliavoimen [RangeStart, RangeEnd)-rajan uudelleen paikallisesti, joten osion oikeellisuus ei riipu siitä, käsitteleekö palvelin rajansa sisältävinä vai poissulkevina.

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

Käyttöönoton jälkeinen ensimmäinen päivitys ottaa käytännön käyttöön: täydellinen historiallinen lataus, hidas. Kaikki sen jälkeiset päivitykset käsittelevät vain inkrementaalista ikkunaa. Mitattu tietojoukolla, jossa on noin 158 000 aktiviteettia ja noin 2 300 entiteettiä:

Päivitys	Kokonaiskesto
Ensimmäinen (käytännön käyttöönotto, täydellinen historiallinen lataus)	~31 min
Jokainen sen jälkeinen	~15 s

Power BI:n klassinen päivitys-REST-päätepiste (POST .../refreshes pelkällä notifyOption) ohittaa päivityskäytännöt huomaamatta ja käy läpi koko datan joka kerta. Jos haluat soveltaa käytäntöä REST API:n kautta, käytä parannettua päivitystä: lähetä type, commitMode ja applyRefreshPolicy pyynnön rungossa. Power BI Servicen ajastimen käynnistämät päivitykset soveltavat käytäntöjä aina — tämä erikoisuus koskee vain REST-kutsua.

14 päivän ikkuna on tarkoituksella väljä. Aktiviteettien vastaanotto ei ole vain nykyhetkeen lisääviä: konnektorien täydennykset tuovat tapahtumia menneillä aikaleimoilla. 1–2 päivän ikkuna jättäisi ne pysyvästi huomiotta.

Päivitysikkunan laajentaminen API:in

GET /v1/activities hyväksyy suodattimet start_date ja end_date, joihin Power BI -parametrit välittyvät, ja suodattaa kohteen event_ts rajojen välillä. Entities on dimensio, joten tässä esimerkissä se päivitetään kokonaisuudessaan joka kerta inkrementaalisen päivityksen sijaan. Reporting-tietojoukot käyttävät omia vesileimojaan (updated_after, occurred_after) aktiviteettien päivämääräikkunan sijaan.

Nopeusrajoitukset päivityksen aikana

/v1 valvoo erillisiä avainkohtaisia ja IP-kohtaisia budjetteja (katso nopeusrajoitukset). Noudata 429 + Retry-After; älä kovakoodaa pyyntöbudjettia malliisi. Power BI -päivityksissä kaksi asiaa on tärkeää:

Yksittäisen taulukon läpikäynti on peräkkäistä. Jokainen sivupyyntö tarvitsee edellisen sivun tunnisteen, joten yksittäisen taulukon nopeutta rajoittaa viive sivukoosta riippumatta.
Samanaikaiset taulukkopäivitykset kertautuvat. Useiden suurten taulukoiden päivittäminen rinnakkain on tilanne, jossa yläraja saavutetaan, minkä vuoksi kohdan Fn_FetchAll 429-uudelleenyrityspolku on tärkeä. Suosi vähäisempää määrää rinnakkaisia taulukoita sen sijaan, että olettaisit rajoittamattoman samanaikaisuuden.

Uudelleenyritystä on testattu todellista kyllästynyttä rajoitinta vastaan. Päivitys, joka ajettiin rinnakkaisen kuorman pitäessä avainta tarkoituksella sen ylärajalla, valmistui silti ja tuotti samat rivimäärät kuin kuormittamaton vertailuajo — uudelleenyritykset palauttivat täydet sivut ilman aukkoja.

Sopimusversiot ja tallennetut tunnistetiedot

/v1 hyväksyy pyyntöotsakkeen Living-Security-Version, jolla julkaistu sopimusversio kiinnitetään (katso API-pikaopas). Power Query ei voi lähettää kyseistä otsaketta, kun tietolähde käyttää tallennettuja tunnistetietoja — vain anonyymit tietolähteet sallivat mukautetut otsakkeet. Sen lisääminen aiheuttaa päivityksen epäonnistumisen virheeseen:

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

Pidä avain Power BI:n tallennetuissa tunnistetiedoissa äläkä käytä mukautettua otsaketta. Jos pyynnössä ei ole eksplisiittistä versiota, API käyttää palvelutilin kiinnitettyä contract_version tai uusinta julkaistua versiota, jos kiinnitystä ei ole asetettu. Varmista tilin sopimusversio API-ylläpitäjältäsi ennen päivityksen julkaisemista. Tuetut versiot on lueteltu API-muutoslokissa. Jos päivitys alkaa käyttäytyä odottamattomasti, tarkista API:n Living-Security-Version-vastausotsake nähdäksesi, mikä sopimus palveli pyyntöä.

Päivitä ja varmista mallisi

Julkaise semanttinen malli Power BI -työtilaasi, sido sen tallennetut tunnistetiedot alueelliseen /v1-lähteeseen ja suorita päivitys ennen aikataulun käyttöönottoa. Tarkista päivityshistoriasta epäonnistumiset tai epätäydelliset lukemiset. Tarkista rivimäärät riippumatonta API-lukua vastaan samoilla suodattimilla. Sivutusoppaassa on Python- ja cURL-esimerkkejä täydellisen tulosjoukon lukemiseen. Päivitys, joka lukee vain ensimmäisen sivun, voi näyttää onnistuneelta pienellä tietojoukolla; vertaa määriä ennen kuin luotat raporttiin.

Mallinnusvalinnat

Kampanjasummilla ja henkilökohtaisilla tuloksilla on eri tarkkuustasot. SimulationResults kutsuu GET /v1/simulations/{id}/results (yksi GET ajoa kohti). Henkilökohtaiseen tietojenkalasteluun lisää kyselyt kohteisiin GET /v1/reporting/simulation_results ja GET /v1/reporting/simulation_events (tai operatiiviseen GET /v1/simulation_results, jos sinulla on jo simulation:read).
vectors kohteessa /v1/simulations on litistetty pilkuilla erotetuksi merkkijonoksi. Luettelotyyppistä saraketta ei voi viipaloida varsinaisena dimensiona. Jos raporttisivun täytyy suodattaa vektorin mukaan, lisää simulaatio–vektori-siltataulukko.

Seuraavat vaiheet

Developer Hub

Luo palvelutili ja API-avain Power BI:tä varten.

API-pikaopas

Todenna /v1-pyynnöt Basic-todennuksella.

Sivutus

Luettelokuori, kursoritunnisteet ja suodattimien vakaus läpikäynnin aikana.

Nopeusrajoitukset

Avainkohtaiset ja IP-kohtaiset budjetit, 429-sopimus ja uudelleenyritysohjeet.

Kehittäjäkeskus

Julkinen rajapinta v1

API v1 -viite

Mihin tätä esimerkkiä käytetään

Edellytykset

Valitse oikea tarkkuustaso

Vaikeusasteikko

Yhteysmalli (Power Query)

Jaettu sivutusfunktio

Tyypitetyt kyselyt päätepistettä kohti

Excel

Henkilökohtainen vaatimustenmukaisuus

Sähköpostitietojenkalastelun loki

Alttiimmat käyttäjät

Reporting-esikatselutietojoukot (henkilökohtainen tietojenkalastelu)

simulation_results

simulation_events

entities

entity_versions ja cohort_memberships

Tähtiskeemapohjainen semanttinen malli kohteessa /v1/activities

Siltataulukon rakenne

Inkrementaalinen päivitys

Päivitysikkunan laajentaminen API:in

Nopeusrajoitukset päivityksen aikana

Sopimusversiot ja tallennetut tunnistetiedot

Päivitä ja varmista mallisi

Mallinnusvalinnat

Seuraavat vaiheet

Developer Hub

API-pikaopas

Sivutus

Nopeusrajoitukset

Kehittäjäkeskus

Julkinen rajapinta v1

API v1 -viite

​Mihin tätä esimerkkiä käytetään

​Edellytykset

​Valitse oikea tarkkuustaso

​Vaikeusasteikko

​Yhteysmalli (Power Query)

​Jaettu sivutusfunktio

​Tyypitetyt kyselyt päätepistettä kohti

​Excel

Henkilökohtainen vaatimustenmukaisuus

Sähköpostitietojenkalastelun loki

Alttiimmat käyttäjät

​Reporting-esikatselutietojoukot (henkilökohtainen tietojenkalastelu)

​simulation_results

​simulation_events

​entities

​entity_versions ja cohort_memberships

​Tähtiskeemapohjainen semanttinen malli kohteessa /v1/activities

​Siltataulukon rakenne

​Inkrementaalinen päivitys

​Päivitysikkunan laajentaminen API:in

​Nopeusrajoitukset päivityksen aikana

​Sopimusversiot ja tallennetut tunnistetiedot

​Päivitä ja varmista mallisi

​Mallinnusvalinnat

​Seuraavat vaiheet

Developer Hub

API-pikaopas

Sivutus

Nopeusrajoitukset

Mihin tätä esimerkkiä käytetään

Edellytykset

Valitse oikea tarkkuustaso

Vaikeusasteikko

Yhteysmalli (Power Query)

Jaettu sivutusfunktio

Tyypitetyt kyselyt päätepistettä kohti

Excel

Reporting-esikatselutietojoukot (henkilökohtainen tietojenkalastelu)

simulation_results

simulation_events

entities

entity_versions ja cohort_memberships

Tähtiskeemapohjainen semanttinen malli kohteessa /v1/activities

Siltataulukon rakenne

Inkrementaalinen päivitys

Päivitysikkunan laajentaminen API:in

Nopeusrajoitukset päivityksen aikana

Sopimusversiot ja tallennetut tunnistetiedot

Päivitä ja varmista mallisi

Mallinnusvalinnat

Seuraavat vaiheet