API con Power BI – Integrazione con SMARTFENSE

Sommario

Questo articolo spiega come autenticarsi e consumare l'API di SMARTFENSE da Microsoft Power BI Desktop usando OAuth 2.0 (Client Credentials), incluso un esempio di paginazione per unificare i risultati di più pagine in un'unica tabella.

Introduzione

SMARTFENSE espone un'API che permette di integrare i dati della tua istanza con strumenti come Microsoft Power BI per reporting e analisi. In questo esempio si utilizza il flusso OAuth 2.0 Client Credentials, pensato per integrazioni server-to-server (senza un utente presente), tipico di un amministratore o partner che necessita di consultare informazioni su campagne e moduli.

URL Base

Tutte le richieste all'API di SMARTFENSE devono essere effettuate utilizzando la seguente URL base:

https://tenant.takesecurity.com/

Autenticazione

L'API di SMARTFENSE utilizza OAuth 2.0, supportando i seguenti flussi:

• Client Credentials
• Authorization Code

Per integrazioni con Power BI, si utilizza il flusso Client Credentials, poiché è progettato per interazioni server to server, senza intervento di un utente finale.

Regole importanti

• Tutte le richieste devono essere effettuate tramite HTTPS.
• Ogni richiesta deve includere un Bearer Token nell'intestazione Authorization.
• Le credenziali devono essere conservate in modo sicuro.

Ottenimento delle credenziali

1. Accedi alla piattaforma SMARTFENSE.
2. Vai su Configurazione → Integrazioni → API

3. Premi Registra nuova applicazione.

   

4. Configura gli ambiti necessari in base agli endpoint da consumare
   (documentazione disponibile su:
   https://tenant.takesecurity.com/api/schema/redoc/)
    
5. Al termine, otterrai:
   • client_id
   • client_secret

Struttura raccomandata in Power BI

Per l'integrazione si consiglia di creare le seguenti funzioni:

1. fnGetToken
   Ottiene il token OAuth 2.0.
2. fnGetPagedResults
   Ottiene e unifica i risultati paginati dell'API.
3. Funzione per endpoint
   Esempio: fnGetCampaignTrainings per Moduli Interattivi.

L'autenticazione è gestita all'interno del codice M, quindi in Power BI la sorgente si configura come Anonimo.

Creare funzione per ottenere il token

1. Avvia Power BI. Vai alla sezione Ottieni dati da altre origini

2. Nella finestra Ottieni dati, seleziona dal menu laterale sinistro Altro e scegli Query vuota, quindi clicca su Connetti.

3. Rinomina la query in fnGetToken e poi vai su Editor avanzato.

4. Nell'Editor avanzato incolla il seguente codice:

let
    fnGetToken = () as text =>
    let
        // Dati dell'applicazione OAuth
        // Sostituire con i valori reali
        client_id     = "client_id della piattaforma SMARTFENSE",
        client_secret = "client_secret della piattaforma SMARTFENSE",
        base_url      = "https://istanza.takesecurity.com",

        // Tempo massimo di attesa in minuti per le chiamate HTTP
        timeoutMinutes = 120,

        // "client_id:client_secret" in Base64 per Authorization: Basic
        TextToEncode = client_id & ":" & client_secret,
        Encoded      = Binary.ToText(Text.ToBinary(TextToEncode), BinaryEncoding.Base64),

        // Corpo per grant_type=client_credentials
        Body = "grant_type=client_credentials",

        TokenResponse = Json.Document(
            Web.Contents(
                base_url & "/oauth/token/",
                [
                    Content = Text.ToBinary(Body),
                    Headers = [
                        #"Content-Type" = "application/x-www-form-urlencoded",
                        #"Cache-Control" = "no-cache",
                        Authorization = "Basic " & Encoded
                    ],
                    Timeout = #duration(0, 0, timeoutMinutes, 0)
                ]
            )
        ),

        AccessToken = TokenResponse[access_token]
    in
        AccessToken
in
    fnGetToken

5. Nella sezione che dice "// Sostituire con i valori reali" inserisci i dati ottenuti registrando l'applicazione sulla piattaforma SMARTFENSE e premi il pulsante Fine.

L'URL "https://istanza.takesecurity.com" deve contenere il sottodominio dell'istanza SMARTFENSE.

Creare funzione per ottenere dati paginati (fnGetPagedResults)

1. Nel menu Home->Nuova origine seleziona "Query vuota".
    

   

2. Rinomina la query in fnGetPagedResults e poi vai su Editor avanzato.
    

   

3. Nell'Editor avanzato incolla il seguente codice:

let
    fnGetPagedResults = (initialPath as text) as list =>
    let
        // URL base dell'istanza (host)
        base_url       = "https://istanza.takesecurity.com",

        // Timeout massimo per richiesta (in minuti)
        timeoutMinutes = 120,

        // Ottieni token usando la funzione precedente (usata nell'header Authorization)
        token    = fnGetToken(),

        // Crea la prima URL assoluta dell'endpoint
        FirstUrl = base_url & initialPath,

        // Funzione locale per ottenere una pagina (richiesta + parsing JSON)
        GetPage = (url as text) as record =>
            let
                Response =
                    Json.Document(
                        Web.Contents(
                            url,
                            [
                                Headers = [ Authorization = "Bearer " & token ],
                                Timeout = #duration(0, 0, timeoutMinutes, 0)
                            ]
                        )
                    )
            in
                Response,

        // Estrai la lista di elementi da una pagina, supportando entrambi i formati:
        // - {"results": [...]}
        // - {"campaigns": [...]}
        GetItems = (page as record) as list =>
            let
                items =
                    if Record.HasFields(page, "results") then page[results]
                    else if Record.HasFields(page, "campaigns") then page[campaigns]
                    else {}
            in
                if items is list then items else {},

        // Scorri tutte le pagine finché esiste il campo "next"
        Pages = List.Generate(
            // Stato iniziale: prima URL e prima pagina scaricata
            () => [ Url = FirstUrl, Page = GetPage(FirstUrl) ],

            // Condizione: continua finché Page non è null
            each [Page] <> null,

            // Stato successivo: leggi "next" e prendi la pagina successiva se esiste
            each
                let
                    NextUrl = try [Page][next] otherwise null
                in
                    [
                        Url  = NextUrl,
                        Page = if NextUrl <> null then GetPage(NextUrl) else null
                    ],

            // Da ogni pagina, restituisci la lista rilevata (results o campaigns)
            each try GetItems([Page]) otherwise {}
        ),

        // Combina tutte le liste in una lista finale unica
        AllResults = List.Combine(Pages)
    in
        AllResults
in
    fnGetPagedResults  

4. Premi il pulsante "Fine".

Creare funzione per Moduli Interattivi (esempio)

1. Nel menu Home->Nuova origine seleziona "Query vuota".
    

   

2. Rinomina la query in fnGetCampaignTrainings e poi vai su Editor avanzato.
   

3. Nell'Editor avanzato incolla il seguente codice:

let
    initial_path = "/api/v1/users/campaigns/trainings",
    ResultsList  = fnGetPagedResults(initial_path)
in
    ResultsList

4. Premi il pulsante "Fine".

Configurare le credenziali in Power BI Desktop

1. Premi su Modifica credenziali.
    

   

2. Cerca la sorgente: https://nomeistanza.takesecurity.com e premi su Connetti.

3. Per specificare i dati di privacy premi su Continua.
    

   

4. Livello di privacy: Organizzativo.

5. Salva e chiudi.

Creare la tabella finale per il modello

1. Se la connessione è andata a buon fine si aprirà l'Editor di Power Query mostrando le seguenti informazioni.
    

   

2. Premi il pulsante "A tabella" in alto a sinistra e poi il pulsante "OK".

3. Poi premi il pulsante di espansione per ampliare le informazioni che desideri importare.
    

   

4. Seleziona i campi che desideri visualizzare nella tabella e premi "OK".
    

   

5. Con la barra inferiore scorri verso destra fino a vedere la colonna results.related_campaigns e clicca sul pulsante di espansione della colonna.
    

   

6. Seleziona Espandi in nuove righe.
    

   

7. Clicca nuovamente sul pulsante di espansione della colonna per vedere i dati che verranno importati e seleziona tutti o quelli che desideri visualizzare. Clicca su OK.
    

   

8. In questo modo visualizzerai tutti i dati dei risultati delle campagne del componente in colonne separate.
    

   

9. Poi puoi andare nel menu superiore e Chiudi e applica per procedere con la creazione delle query desiderate.
    

   

Considerazioni finali

• L'aggiornamento dei dati è manuale.
• Premendo Aggiorna in Power BI, vengono consultati i dati attuali dell'istanza.
• Non esiste un aggiornamento automatico programmato dall'API.
• È possibile riutilizzare questa struttura per qualsiasi endpoint documentato nell'API di SMARTFENSE.

Migliori pratiche

• Proteggi il client_secret: conservalo in un luogo sicuro ed evita di esporlo in file condivisi o repository pubblici, specialmente se l'accesso è gestito da un amministratore o un partner.

• Valida gli ambiti prima di costruire report: conferma permessi e endpoint disponibili su tenant.takesecurity.com/api/schema/redoc/ per evitare errori e rifacimenti.

• Riduci il volume in Power Query: espandi solo le colonne necessarie (ad esempio, evita di espandere liste complete se non apportano valore al modello).

• Standardizza il base_url per istanza: se gestisci più istanze, definisci un criterio chiaro per mantenere coerenza ed evitare di consultare dati errati.

Importante: Devi sostituire la parola istanza nell'URL di ogni API con il sottodominio dell'istanza in questione.