Power BI

​

À quoi sert cet exemple

• Charger les points de terminaison de liste /v1 dans un jeu de données Power BI avec une pagination par curseur correcte et une nouvelle tentative en cas de limite de débit.
• Créer un modèle sémantique dans lequel les mesures (« entités actives », « activités par entité active ») sont dimensionnelles plutôt que comptées à partir d’une table à plat.
• Faire passer une actualisation Power BI planifiée d’un parcours complet de l’historique à une petite fenêtre quotidienne grâce à l’actualisation incrémentielle.
• Choisir la bonne granularité pour le phishing : totaux de campagne (opérationnel) ou résultats par personne et événements typés (préversion reporting).

​

Prérequis

• Une clé d’API disposant des autorisations requises par vos requêtes :
  • Exemple opérationnel : activity:read, entity:read et simulation:read.
  • Phishing par personne via les jeux de données de reporting : reporting:read. Consultez Clés d’API.
• Power BI Desktop, ou un espace de travail Power BI / Fabric dans lequel vous pouvez créer un modèle sémantique et planifier une actualisation.

​

Choisir la bonne granularité

​

Échelle de difficulté

​

Modèle de connectivité (Power Query)

​

Fonction de pagination partagée

• URL de base /v1 statique, RelativePath et Query dynamiques. Requis pour l’actualisation planifiée et pour le test des identifiants.
• ManualStatusHandling = {429} avec une nouvelle tentative bornée. La fonction lit Retry-After lorsque Power Query l’expose, sinon attend 30 secondes, et abandonne après 5 réponses 429 consécutives avec une erreur explicite plutôt que de boucler jusqu’à l’expiration de l’actualisation. 5xx n’est volontairement pas retenté — une erreur de serveur doit remonter, et non produire silencieusement un jeu de données partiel.
• Timeout de 60 secondes. Les pages répondent généralement en bien moins d’une seconde ; une minute de silence signifie donc que la requête est perdue.
• Binary.Buffer avant Json.Document. Sans mise en mémoire tampon, le moteur mashup peut redemander le flux de réponse s’il le lit plus d’une fois.
• baseQuery est transmis sans modification à chaque itération. Les jetons de page sont des curseurs opaques et signés, liés à l’organisation, aux identifiants, à la version du contrat et à l’empreinte des filtres et du tri. Modifier un filtre en cours de parcours est rejeté comme jeton invalide, au lieu de repartir de la première page.

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

​

Requêtes typées par point de terminaison

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. Données → Obtenir des données → À partir d’autres sources → Requête vide.
2. Dans l’Éditeur Power Query, Accueil → Éditeur avancé. Collez d’abord Fn_FetchAll, puis renommez cette requête Fn_FetchAll (Paramètres de la requête → Nom, ou clic droit dans le volet Requêtes → Renommer).
3. Répétez l’opération pour Fn_GetJson, puis pour chaque requête de rapport.
4. Accueil → Fermer et charger → Fermer et charger dans… ouvre la boîte de dialogue Importer les données. Choisissez Créer uniquement une connexion pour Fn_FetchAll et Fn_GetJson (ce sont des fonctions, pas des tables). Choisissez Tableau pour chaque requête de rapport que vous souhaitez placer dans une feuille de calcul.
5. Lors de la première actualisation, choisissez Basic : la clé d’API comme Nom d’utilisateur, un espace réservé tel que x comme Mot de passe. Excel stocke un seul jeu d’identifiants par URL de source de données ; les requêtes suivantes qui ciblent le même hôte /v1 le réutilisent.

​

Jeux de données de reporting en préversion (phishing par personne)

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

• Chemin : GET /v1/reporting/simulation_results
• Granularité : entité × simulation
• Filtres : simulation, entity, updated_after, ainsi que limit / page_token
• Objet transmis : reporting.simulation_result
• Clés de jointure : 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

• Chemin : GET /v1/reporting/simulation_events
• Granularité : un fait typé par interaction observée
• Filtres : simulation, entity, event_type, occurred_after, ainsi que limit / page_token
• Objet transmis : reporting.simulation_event
• Types d’événement : jetons publics fermés tels que simulation.delivered, simulation.opened, simulation.link_clicked, simulation.credentials_submitted, simulation.reported — et non les types d’activité phishing.simulation.* bruts de ClickHouse
• Appareil : device_type est la classe dérivée (les jetons observés incluent desktop, mobile, tablet, unknown). user_agent brut n’est pas présent sur /v1. L’adresse IP brute n’est jamais présente sur /v1 (jamais conservée ; uniquement ip_hash salé).

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

• Chemin : GET /v1/reporting/entities
• Granularité : une ligne actuelle par entité
• Filtres : type, updated_after, ainsi que limit / page_token
• Objet transmis : reporting.entity
• Clé de jointure : id / entity_id (même valeur)

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

Aucune table faisant autorité pour l’historique des versions ou des appartenances n’existe. Ce jeu de données projette la ligne actuelle sous la forme d’un intervalle ouvert (valid_to est null, is_current est true). valid_from vaut created_at ou à défaut updated_at pour les versions d’entités, et l’heure d’observation de la requête pour les appartenances aux cohortes. Les intervalles historiques fermés ne sont pas fabriqués.

• entity_versions : GET /v1/reporting/entity_versions. Mêmes filtres que entities. valid_from vaut created_at ou à défaut updated_at. Une entité dont les deux horodatages sont null est omise.
• cohort_memberships : GET /v1/reporting/cohort_memberships. Filtres : cohort, entity, updated_after. updated_at correspond à la dernière mise à jour de la Cohorte, afin que l’actualisation incrémentielle reste fiable. valid_from est l’heure d’observation de la requête. Jointure de entity_id à 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

​

Modèle sémantique en étoile sur /v1/activities

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

• Activities est le fait d’événement à sa granularité réelle. Une ligne par activité. Les participants y sont supprimés et reconstruits dans leur propre table.
• ActivityParticipants existe parce que les participants relèvent véritablement d’une relation un-à-plusieurs, avec des rôles tels que actor et target. Les aplatir dans Activities dupliquerait les lignes d’activité (gonflant chaque décompte) ou supprimerait les participants supplémentaires. La relation avec Activities est la seule relation bidirectionnelle du modèle ; ainsi, un segment d’entité atteint la table de faits.
• Entities est la dimension qui nomme les participants. Les lignes de participants d’une activité contiennent entity_id et un rôle, mais pas de nom d’affichage.
• Dates est générée en M (aucun appel d’API) et désignée comme table de dates du modèle. C’est ce qui rend valides les fonctions d’intelligence temporelle DAX (DATESINPERIOD, DATEADD). Les colonnes de nom de mois et de jour de la semaine déclarent sortByColumn sur leurs jumelles numériques afin que les visuels ne trient pas les mois par ordre alphabétique.

​

Structure de la table pont

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

​

Actualisation incrémentielle

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

​

Élargir la fenêtre d’actualisation dans l’API

​

Limites de débit pendant l’actualisation

• Le parcours d’une seule table est séquentiel. Chaque requête de page a besoin du jeton de la page précédente ; une table est donc limitée par la latence, quelle que soit la taille de page.
• Les actualisations simultanées de tables se cumulent. Plusieurs grandes tables actualisées en parallèle constituent le cas qui atteint le plafond, et c’est pourquoi le chemin de nouvelle tentative 429 dans Fn_FetchAll est important. Privilégiez un nombre réduit de tables en parallèle plutôt que de supposer une simultanéité illimitée.

​

Versions du contrat et identifiants stockés

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

​

Actualiser et vérifier votre modèle

​

Choix de modélisation

• Les totaux de campagne et les résultats par personne n’ont pas la même granularité. SimulationResults appelle GET /v1/simulations/{id}/results (un GET par exécution). Pour le phishing par personne, ajoutez des requêtes pour GET /v1/reporting/simulation_results et GET /v1/reporting/simulation_events (ou GET /v1/simulation_results opérationnel si vous disposez déjà de simulation:read).
• vectors sur /v1/simulations est aplati en une chaîne séparée par des virgules. Une colonne de type liste ne peut pas servir de véritable dimension de segment. Si une page de rapport doit filtrer par vecteur, ajoutez une table pont simulation-vecteur.

​

Étapes suivantes