SoSafe-gegevens verwerken in PowerBI via Power Query M

Introductie

SoSafe-klanten kunnen analytische/ruwe gegevens rechtstreeks ophalen via de SoSafe API, die ook via PowerBI kan worden gebruikt.

Deze handleiding laat zien hoe u Microsoft Fabric's Gen 2 Dataflows kunt gebruiken om gegevens op te halen en weer te geven in PowerBI, met voorbeelden op basis van de browserversie informatie. Er wordt uitgelegd hoe u query's instelt voor efficiënte datavisualisatie en toekomstige opslag via een meegeleverde sjabloon.

SoSafe PowerBI-sjabloon

Wat is het?

SoSafe heeft een sjabloon gebouwd dat eenvoudig in PowerBI kan worden geïmporteerd om gegevens van de SoSafe API op te halen en te visualiseren. Dit sjabloon bevat basisfunctionaliteit voor het ophalen van gegevens uit de API, het verwerken daarvan en het aanmaken van Table-structuren.

Het sjabloon gebruiken

1. Laad het rechtstreeks in PowerBI door een nieuwe dataflow te maken en het hierboven opgegeven bestand als model te gebruiken. Meer informatie over hoe u dit in PowerBI doet, is te vinden hier en hier.

2. Voeg de API-sleutel en het sleutel-ID toe die zijn verstrekt via de SoSafe Manager, in de twee parameters die het sjabloon biedt: APIKey en KeyID. Als u deze waarden nog niet heeft ontvangen, raadpleegt u deze handleiding.

   

3. Zodra beide waarden zijn toegevoegd, kunt u op de betreffende tabellen aan de rechterkant van de dataflow klikken om ze één voor één te laden en de gegevens te visualiseren:

4. Gereed! De gegevens zijn beschikbaar voor u om te visualiseren en te verwerken!

Basisverzoeken aanpassen

Het sjabloon bevat drie tabellen voor drie soorten gegevens die de SoSafe API biedt:

• Users: https://support.sosafe.de/ADOC/sosafe-api#SoSafeAPI-Usersendpoint
• Campaigns: https://support.sosafe.de/ADOC/sosafe-api#SoSafeAPI-Campaignsendpoint
• Campaign Analytics: https://support.sosafe.de/ADOC/sosafe-api#SoSafeAPI-Analyticsendpoint

Deze endpoints bevatten echter verschillende soorten filters voor gegevens die kunnen worden aangepast om andere resultaten van de API op te halen. Met de tabel Users als voorbeeld kunnen we de query aanpassen.

1. Klik met de rechtermuisknop op de tabelkaart Users en begin met het bewerken van het script.

2. Voeg op basis van de documentatie in de SoSafe Open API-specificatie de bijbehorende parameters als volgt toe en sla het script op

   

3. Gereed!

Nieuwe verzoeken toevoegen

Een nieuw verzoek/nieuwe tabel toevoegen is ook vrij eenvoudig! Voordat u uw eigen query's maakt, vergeet dan niet de SoSafe Open API Spec te raadplegen om te begrijpen wat er via de API kan worden opgehaald.

1. Maak een nieuwe Blank Query aan en open de scripteditor.
2. Gebruik binnen het blok let de functie performGetRequest om JSON-gegevens op te halen
3. Gebruik nog steeds binnen het blok let het resultaat van performGetRequest om de lijst met records op te halen en geef deze als argument door aan de functie convertToTable om de JSON-gegevens om te zetten naar een Power Query-tabel

4. Gereed! U kunt uw nieuwe query nu naast alle andere query's zien!

Aangepaste functies

Het sjabloon biedt twee aangepaste functies die door de gehele pipeline kunnen worden gebruikt om het u gemakkelijker te maken.

performGetRequest

Deze functie roept de SoSafe API rechtstreeks aan en haalt gegevens op in JSON-indeling (voorbeeldreacties zijn te vinden in de SoSafe Open API Spec). De functie verwerkt ook automatisch de authenticatie op basis van de in de eerste stap opgegeven inloggegevens, en voegt Accept en Content-Type toe als standaardheaders.

Deze functie heeft twee argumenten:

• path (text): Het pad van het GET-verzoek, bijvoorbeeld `/v1/users`
• options (nullable record): De opties die aan dit verzoek worden doorgegeven, waaronder:
  • headers (record): Een sleutel/waarde-record van alle door te sturen headers, met uitzondering van de standaardheaders
  • params (record): Een sleutel/waarde-record van parameters die aan dit verzoek worden toegevoegd. Accepteert waarden van het type text, number en list
  • chunkBy (text): Het tekstveld op basis waarvan waarden in blokken worden verdeeld; geef dit op samen met chunkSize en alleen als de te verdelen parameter aanwezig is in params
  • chunkSize (number): Het aantal records dat per keer via de API wordt opgevraagd; geef dit op samen met chunkBy

Voorbeeldverzoek met gesegmenteerde verzoeken:

responses = performGetRequest(
  "/v1/analytics/elearning",
  [
    params = [ campaignId = Table.Column(Campaigns, "id"),
    chunkBy = "campaignId",
    chunkSize = 5
  ]
),

convertToTable

Dit is een eenvoudige functie die een opgegeven lijst met records omzet naar een Power Query-tabel. Binnen de SoSafe API betekent dit dat de JSON-gegevens van een respons opgehaald met performGetRequest hier als argument kunnen worden gebruikt. Daarnaast neemt de functie een argument om te bepalen welk primaire sleutelveld in de gegevensset voor de tabel wordt gebruikt, evenals optionele externe sleutels. De argumenten zijn als volgt:

• records (list van records): De lijst met records die naar een tabel worden omgezet
• types (list van lists): Een lijst met de namen van de velden en hun bijbehorende Power Query-typen. Hiermee worden de typen uit de respons omgezet naar de juiste tabeltypen. Bijvoorbeeld:

  • {
      { "id", Int64.Type },
      { "name", Text.Type }
    }

• primaryKey(text): De naam van het veld dat de primaire sleutel voor deze tabel bevat
• foreignKey (nullable list): Een optionele lijst die kan worden meegegeven met alle namen van de velden die als externe sleutels moeten fungeren

Voorbeeldconversie met gesegmenteerde verzoeken:

table = convertToTable(
  // convert all responses to a list of records containing the correct data
  List.Accumulate(
    responses,
    {},
    (acc, current) => List.Combine({ acc, current[data] })
  ),
  // assign types
  {
    { "customerId", Int64.Type },
    { "campaignId", Int64.Type },
    { "campaignName", Text.Type },
    { "firstname", Text.Type },
    { "lastname", Text.Type },
    { "email", Text.Type },
    { "language", Text.Type },
    { "userGroup", Text.Type },
    { "userCreated", Date.Type },
    { "registrationDate", Date.Type },
    { "isActive", Logical.Type },
    { "progress", Percentage.Type },
    { "achievedLevel", Percentage.Type },
    { "allPassed", Text.Type },
    { "passedModules", Int64.Type },
    { "overdueMandatoryModules", Int64.Type },
    { "passedMandatoryModules", Int64.Type },
    { "passedOptionalModules", Int64.Type },
    { "recentlyFinishedModule", Date.Type }
  },
  // assign primary key
  "email"
)