Implementazione della segmentazione a livello di riga per i contenuti di Looker incorporati

Scritto da Christopher Seymour, Sr. Data Analyst, e Dean Hicks, Developer Relations Engineer

La segmentazione a livello di riga ti consente di limitare i dati a cui un singolo utente può accedere in base ai valori archiviati in uno o più campi del database. Questa guida descrive i metodi per implementare la segmentazione a livello di riga nei contenuti Looker incorporati e contiene le seguenti sezioni:

Introduzione

La funzionalità di incorporamento di Looker è una delle funzionalità più potenti e preziose del prodotto. Se stai leggendo questa guida, è probabile che tu stia già incorporando contenuti di Looker nella tua applicazione o che intendi farlo nel prossimo futuro.

Questa guida ha lo scopo di aiutarti a comprendere meglio la progettazione della funzionalità di incorporamento di Looker e come implementare la segmentazione in un'applicazione in cui i partner possono gestire l'accesso a più brand. Poiché si tratta di un approfondimento sull'argomento, la lettura è un po' lunga. Tieni presente che questa guida non è pensata per risolvere rapidamente un problema semplice, ma piuttosto per aiutarti a gestire meglio l'intero caso d'uso dell'incorporamento di Looker.

Panoramica del caso d'uso

Questa guida descrive un caso d'uso comune in cui la tua azienda incorpora contenuti di Looker nel tuo prodotto e mostra segmenti di utenti che dovrebbero visualizzare diverse sezioni dei tuoi dati.

Per questo caso d'uso di incorporamento firmato, supponiamo che tu sia l'amministratore della tua istanza di Looker. Lavori con due tipi di utenti di incorporamento esterni: clienti, che devono poter accedere solo ai dati relativi al loro brand specifico, e partner, che potranno accedere ai dati di più brand. Hai una dashboard con alcuni riquadri che mostri a ogni cliente che utilizza il tuo prodotto, ma devi filtrare automaticamente la dashboard per ogni cliente in modo che visualizzi solo i dati specifici di quel cliente. Gli esempi in questo documento utilizzano due società fittizie: Hooli e Pied Piper.

Hai una tabella chiamata products, che mostra alcune metriche di prodotto per brand diversi. Ogni brand corrisponde a un utente incorporato diverso (con un external_user_id diverso) nell'applicazione incorporata firmata. Poiché ogni utente incorporato deve essere in grado di visualizzare solo i dati del proprio brand, hai un'esplorazione che utilizza un filtro di accesso su un attributo utente brand:

explore: products {
  access_filter: {
    field: products.brand
    user_attribute: brand
  }
}

Hai una dashboard basata su questa esplorazione e con due riquadri: uno mostra il nome del brand e l'altro il numero di prodotti per quel brand.

Utilizzi l'endpoint create_sso_embed_url per generare gli URL di incorporamento di questa dashboard per ogni utente incorporato. Questo esempio utilizza due brand: Pied Piper e Hooli. Ecco il corpo della richiesta che utilizzi nella chiamata create_sso_embed_url per Pied Piper, con external_user_id pied_piper:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "pied_piper",
  "first_name": "PiedPiper",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper"}
}

L'URL che hai generato per Pied Piper mostra la dashboard in questo modo:

Ecco il corpo della richiesta utilizzato nella chiamata create_sso_embed_url per Hooli, con external_user_id hooli:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "hooli",
  "first_name": "Hooli",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Hooli"}
}

L'URL generato per Hooli mostra la dashboard in questo modo:

Voilà! La dashboard viene filtrata in base al valore dell'attributo utente brand di ogni utente incorporato.

Approfondimenti

Molto interessante. Ma se voglio concedere a un singolo utente l'accesso a più brand? Come faccio ad assicurarmi che i miei dati siano visibili solo agli utenti pertinenti?

Buone notizie. La funzionalità di incorporamento firmato di Looker è stata progettata per consentire agli sviluppatori di creare esperienze di dati potenti e personalizzate per gli utenti, garantendo al contempo il mantenimento della governance dei dati definita dal modello dei dati e dalle norme di accesso ai contenuti.

Garantire una governance dei dati impeccabile è fondamentale per offrire un'esperienza di dati efficace. Continua a leggere per scoprire alcuni concetti e best practice che puoi utilizzare per progettare l'esperienza più adatta a te. Il primo è una breve panoramica di come funziona il tutto.

Nozioni di base sull'incorporamento firmato di Looker

È importante tenere presente che l'autenticazione e la gestione degli utenti di Looker nel contesto dell'incorporamento funzionano fondamentalmente nello stesso modo del contesto non incorporato e della maggior parte delle altre applicazioni web.

Ciò può creare confusione nel contesto dell'incorporamento firmato di Looker, perché il passaggio di autenticazione firmata, le impostazioni utente e la dashboard stessa sono tutti combinati in un unico URL lungo e complesso. Tuttavia, questo URL viene utilizzato per stabilire la sessione, che viene applicata anche dopo l'abbreviazione dell'URL. Tenere a mente questo concetto ti aiuterà a creare esperienze di dati eccezionali.

Struttura dell'URL di incorporamento firmato

Ecco uno degli URL di autenticazione incorporata firmati generati dalla chiamata create_sso_embed_url con il corpo della richiesta per Pied Piper:

https://mylookerinstance.cloud.looker.com/login/embed/%2Fembed%2Fdashboards%2F17?permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%5D&models=%5B%22thelook%22%5D&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r%2FtFuvE%3D&nonce=%22967729518a7dbb8a178f1c03a3511dd1%22&time=1696013242&session_length=300&external_user_id=%22pied_piper%22&access_filters=%7B%7D&first_name=%22Pied%22&last_name=%22Piper%22&user_attributes=%7B%22brand%22%3A%22Pied+Piper%22%7D&force_logout_login=true

Ecco lo stesso URL decodificato e suddiviso in singole righe:

https://mylookerinstance.cloud.looker.com/login/embed/
/embed/dashboards/17
?permissions=["access_data","see_user_dashboards"]
&models=["thelook"]
&signature=iG6vcKBgnA50jaL2iShFeQHwFPN7wvTx7Rz6r/tFuvE=
&nonce="967729518a7dbb8a178f1c03a3511dd1"
&time=1696013242
&session_length=300
&external_user_id="pied_piper"
&access_filters={}
&first_name="PiedPiper"
&last_name="User"
&user_attributes={"brand":"Pied Piper"}
&force_logout_login=true

Quando accedi a questo URL, si verificano alcune cose:

  1. Looker cerca un account utente esistente con external_user_id = pied_piper. Se non ne esiste nessuno, Looker crea un nuovo account utente con questo external_user_id.

  2. I dettagli dell'account dell'utente esistente, inclusi autorizzazioni, modelli, gruppi (se specificati) e valori degli attributi utente (se specificati), vengono sovrascritti con i dettagli dell'account specificati nell'URL.

  3. Looker autentica l'utente e stabilisce una sessione per quell'utente memorizzando un cookie di sessione nel browser.

  4. Looker reindirizza quindi all'URL di destinazione o all'URL di reindirizzamento specificato nella chiamata create_sso_embed_url:

    https://mylookerinstance.cloud.looker.com/embed/dashboards/17.

    Puoi visualizzare questo URL di reindirizzamento come URL relativo codificato nell'URL di incorporamento firmato originale:

    %2Fembed%2Fdashboards%2F17

Sebbene i passaggi 1-3 vengano eseguiti automaticamente in background e l'utente finale visualizzi solo il risultato finale (la dashboard stessa), questi passaggi sono fondamentalmente gli stessi di quelli con cui si autentica un normale utente Looker non incorporato. Supponiamo che tu voglia che un utente acceda con le credenziali di utente e password. Il processo sarebbe simile al seguente:

  1. Tu (l'amministratore di Looker) vai al pannello Amministratore - Utenti e utilizzi la barra di ricerca per verificare se esiste già un account utente per questo utente. In caso contrario, crea un nuovo account utente.

  2. Tu (l'amministratore di Looker) fai clic su Modifica accanto all'utente nel pannello Amministrazione - Utenti e fornisci all'utente autorizzazioni, modelli, gruppi, valori degli attributi utente e altri valori.

  3. L'utente va alla pagina di accesso all'indirizzo https://mylookerinstance.cloud.looker.com/login e inserisce il proprio nome utente e la password. Looker autentica l'utente e stabilisce una sessione per quell'utente memorizzando un cookie di sessione nel browser.

  4. Looker reindirizza quindi alla pagina di destinazione (di solito https://mylookerinstance.cloud.looker.com/browse).

Tieni presente che il cookie di sessione verrà applicato a ogni scheda nella finestra del browser. Se l'utente inizia su https://mylookerinstance.cloud.looker.com/browse, apre una nuova scheda del browser e visita una pagina a cui può accedere in base alle sue autorizzazioni, la pagina viene caricata come previsto utilizzando il cookie di sessione già stabilito nella scheda del browser originale.

Lo stesso vale per gli utenti incorporati. Gli utenti incorporati hanno un accesso più limitato alle pagine dell'interfaccia utente: possono accedere solo agli URL di Look, dashboard ed Esplora con il prefisso /embed. Tuttavia, possono comunque navigare manualmente in qualsiasi dashboard a cui i dettagli del loro account utente concedono l'accesso. Supponiamo che l'URL di incorporamento firmato originale ti reindirizzi a https://mylookerinstance.cloud.looker.com/embed/dashboards/17 in una scheda del browser. A questo punto, apri una nuova scheda del browser e carica un'altra dashboard incorporata che si trova nella stessa cartella (e quindi ha le stesse limitazioni di accesso): https://mylookerinstance.cloud.looker.com/embed/dashboards/19.

Sebbene l'URL di reindirizzamento specificato nell'URL di incorporamento firmato originale fosse per la dashboard 17, puoi notare che la dashboard 19 viene caricata come previsto se inserisci manualmente l'URL in una scheda del browser. Tieni presente che non è stato necessario un altro URL di incorporamento firmato per caricare una dashboard diversa.

L'aspetto fondamentale è che tutti i dettagli dell'account utente stabiliti nell'URL (autorizzazioni, attributi utente e così via) vengono applicati all'intera sessione utente, non solo alla dashboard specifica indicata nell'URL firmato originale. In altre parole, come suggerisce il nome, gli attributi utente sono una funzionalità dell'utente, non della dashboard, e devono essere utilizzati per determinare i livelli di accesso di un utente specifico nell'intera applicazione, non solo in una scheda specifica.

Accesso a più brand contemporaneamente

Tieni presente che hai anche partner esterni che potrebbero possedere o gestire più brand. In questo esempio, un partner gestisce i brand Pied Piper e Hooli.

L'approccio da una prospettiva non incorporata

Le sessioni utente incorporate con firma funzionano fondamentalmente allo stesso modo delle sessioni utente di Looker regolari e non incorporate, quindi può essere utile riformulare l'approccio problematico descritto in precedenza nel contesto di una sessione utente di Looker regolare e non incorporata e suddividere questi passaggi per comprendere come implementare questa soluzione in modo più solido. Ecco come sarebbe il flusso di lavoro se stessi dando istruzioni a un utente BI standard che ha accesso alla UI di Looker:

  1. Crea due account utente diversi nella pagina Amministrazione - Utenti.
    1. Nella pagina di modifica del primo account utente, imposta il valore dell'attributo utente brand su pied_piper.
    2. Nella pagina di modifica del secondo account utente, imposta il valore dell'attributo utente brand su hooli.
  2. Invii al partner le email di configurazione dell'account per entrambi gli account utente.
  3. Il partner configura credenziali di email e password separate per ogni account.
  4. Fornisci al partner il link alla dashboard. (https://mylookerinstance.cloud.looker.com/dashboards/17) e comunicagli che, per passare da una dashboard all'altra, dovrà tornare alla pagina di accesso in un'altra scheda e inserire le credenziali email e password per l'altro account utente, quindi caricare di nuovo la dashboard in quella scheda.

Il partner segue le istruzioni. Tuttavia, dopo aver inserito il nome utente e la password dell'account utente Hooli nella seconda scheda del browser e poi essere tornato alla prima scheda in cui era già caricata la dashboard di Pied Piper, il partner preme il pulsante Ricarica. Con sorpresa del partner, la dashboard mostra i dati di Hooli.

A questo punto potresti pensare:

Aspetta… è molto scomodo. Qual è il modo migliore per farlo?

Certo. Questi scenari aiutano a illustrare un principio già banale nel contesto non incorporato, ma che può essere oscurato dalle astrazioni del contesto incorporato: un singolo utente umano deve essere associato a un singolo account utente Looker con un singolo insieme di valori degli attributi utente. Questo è chiaramente spiegato anche nella nostra descrizione di external_user_id nella documentazione sull'incorporamento firmato.

Looker utilizza external_user_id per distinguere gli utenti incorporati con accesso, pertanto a ogni utente deve essere assegnato un ID univoco.

Puoi creare un external_user_id per un utente con qualsiasi stringa, purché sia univoca per quell'utente. Ogni ID è associato a un insieme di autorizzazioni, attributi utente e modelli. Un singolo browser può supportare una sola external_user_id o sessione utente alla volta. Non è possibile apportare modifiche alle autorizzazioni o agli attributi di un utente a metà sessione.

Accesso a più brand contemporaneamente: cosa NON fare

Come per qualsiasi soluzione personalizzabile, esistono alcuni approcci da evitare. Ad esempio, un'implementazione in cui la tua app genera gli URL per entrambi i external_user_ids utilizzando gli stessi input nella chiamata create_sso_embed_url mostrata in precedenza e crea una nuova scheda nell'app per caricare ogni dashboard a cui il partner deve accedere. In genere, gli sviluppatori implementano soluzioni come questa, che comportano un flusso di lavoro errato per l'utente:

  1. Vai alla scheda della dashboard Pied Piper.
  2. Vai alla scheda della dashboard Hooli.
  3. Torna alla scheda della dashboard Pied Piper.
  4. Premi il pulsante Ricarica nella dashboard di Pied Piper.

…la dashboard di Pied Piper mostra i dati di Hooli.

Puoi provare un approccio simile, ma utilizzando lo stesso external_user_id test_user per entrambe le chiamate create_sso_embed_url. Tuttavia, il comportamento è esattamente lo stesso: una volta ricaricata la scheda con la dashboard di Pied Piper, vengono visualizzati i dati di Hooli.

Come faccio ad assicurarmi che la dashboard di ogni brand mostri solo i dati relativi a quel brand?

Mettere in pratica le best practice

Per applicare l'approccio descritto nella sezione "L'approccio da una prospettiva non incorporata", avrai bisogno di un singolo valore dell'attributo utente che conceda l'accesso a TUTTI i dati a cui il partner deve avere accesso nell'applicazione. Puoi farlo utilizzando un valore separato da virgole per l'attributo brand Pied Piper,Hooli:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Affinché questa sintassi funzioni, devi assicurarti che l'attributo utente sia impostato come Filtro stringa (avanzato):

Tieni presente che puoi comunque modificare l'insieme di attributi utente per un utente se cambiano i suoi livelli di accesso ai dati. Ad esempio, se il partner acquisisce la proprietà di un terzo brand, puoi aggiungerlo all'elenco separato da virgole che hai specificato per l'attributo utente brand. In questo modo, quando usciranno e accederanno di nuovo, le modifiche verranno applicate.

Filtrare i risultati della dashboard

Ok, ho capito che gli attributi utente devono specificare tutti i dati a cui un utente può accedere nell'applicazione. Ma se specifico gli attributi utente in questo modo, nella dashboard verranno visualizzati i dati di tutti questi brand. Come faccio a restringere i risultati di una determinata dashboard a un brand specifico?

Il modo corretto per filtrare una determinata dashboard è utilizzare i normali filtri della dashboard. (Ora potrebbe sembrare ovvio, ma abbiamo visto alcune persone bloccarsi sugli attributi utente come unico modo per applicare i filtri nel contesto dell'incorporamento, forse perché user_attributes è un parametro nell'URL di incorporamento firmato e i filtri no.)

Assicurati di richiedere un valore di filtro e di utilizzare una delle opzioni di controllo di selezione singola, ad esempio il menu a discesa:

Assicurati che il filtro sia applicato al campo corretto in tutti i riquadri necessari:

Ora il partner può scegliere tra questi due valori (e solo questi due), perché le opzioni disponibili nel menu a discesa sono limitate dagli attributi utente:

Precompilazione dei filtri della dashboard

Ok, ora il dashboard può essere filtrato in base a un brand specifico, ma vorrei che il valore del filtro fosse già impostato su un brand specifico quando l'utente carica il dashboard per quel brand nella mia app.

Anche in questo caso, è utile pensare a come funziona nel contesto non incorporato. Come si invia a qualcuno un link a una dashboard a cui è già stato applicato un valore di filtro specifico? Avrai notato che quando selezioni un valore del filtro, questo viene visualizzato nell'URL della dashboard:

Includi questa parte dell'URL in target_url per la chiamata create_sso_embed_url:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Se utilizzi l'SDK incorporato, puoi utilizzare withFilters per specificare i filtri iniziali da applicare ai contenuti incorporati:

https://looker-open-source.github.io/embed-sdk/classes/EmbedBuilder.html#withFilters

Se utilizzi il tuo script personalizzato, assicurati di aggiungere il filtro all'URL prima che il percorso venga codificato. Alcuni valori potrebbero essere già codificati nella stringa di filtro (ad esempio, è presente uno spazio codificato come + in ?Brand=Pied+Piper), pertanto questi valori verranno codificati due volte nell'URL finale. Puoi consultare la sezione "SO embedded dashboard - set dashboard filter as part of URL?" Post della community di Looker per una discussione su queste sfumature. Se hai ancora difficoltà ad applicare i filtri, il post della community è il posto giusto per porre le tue domande.

Nascondere i filtri della dashboard

Ok, ho capito come impostare i filtri iniziali nelle mie dashboard, ma non voglio che il partner modifichi i filtri della dashboard. Il valore del filtro deve essere determinato SOLO dalla dashboard a cui il partner ha eseguito la navigazione nella mia app. Come posso nascondere i filtri della dashboard?

A questo scopo, puoi utilizzare i temi. I temi sono una funzionalità a pagamento, quindi, se non è già abilitata nella tua istanza di Looker, devi contattare il team di vendita di Looker per attivarla.

Una volta attivata questa funzionalità, vai alla sezione Controlli dashboard della pagina Amministrazione - Temi, dove puoi deselezionare l'opzione Mostra barra dei filtri:

A questo punto, puoi impostare il tema come predefinito o applicarlo nell'URL delle dashboard specifiche. Anche in questo caso, le informazioni verranno inserite nel target_url della chiamata create_sso_embed_url:

{
  "target_url": "https://mylookerinstance.cloud.looker.com/embed/dashboards/17?Brand=Hooli&theme=test_theme",
  "session_length": 300,
  "force_logout_login": true,
  "external_user_id": "test_user",
  "first_name": "Test",
  "last_name": "User",
  "permissions": ["access_data","see_user_dashboards"],
  "models": ["thelook"],
  "user_attributes": {"brand":"Pied Piper,Hooli"}
}

Per ulteriori informazioni su come nascondere i filtri delle dashboard incorporate, inclusi alcuni snippet di codice dell'SDK Embed, consulta questo tutorial di YouTube: Incorporare Looker con filtri personalizzati.

Il risultato finale dovrebbe essere identico all'esperienza utente della domanda originale:

Ora, però, poiché i valori del filtro sono codificati nei rispettivi URL di destinazione incorporati nell'app, la dashboard di ogni brand mostrerà sempre la dashboard filtrata in base al brand corretto anche quando passi da una scheda all'altra.

Test come altri utenti

Ora l'esperienza utente è molto simile a quella che avevo immaginato in origine. Nel mio caso d'uso, il partner dispone di autorizzazioni diverse e di altre impostazioni utente che i singoli utenti con external_user_id=pied_piper e external_user_id=hooli non hanno, il che porta a opzioni diverse disponibili nell'interfaccia utente e a un'esperienza utente complessiva leggermente diversa. Voglio consentire a un utente di vedere tutto esattamente come lo vedono gli utenti pied_piper e hooli , come se avesse eseguito l'accesso come questi utenti. Come faccio a farlo?

Se vuoi che un utente possa eseguire test come ciascuno degli utenti brand individuali, puoi creare una funzione sudo simile nella tua app che carichi gli URL incorporati per external_user_id=pied_piper quando l'utente esegue l'accesso come utente Pied Piper e gli URL incorporati per external_user_id=hooli quando l'utente esegue l'accesso come utente Hooli. Se la tua app utilizza l'API, puoi anche utilizzare l'endpoint API login_user per eseguire il comando sudo come utente del brand con l'API.

Tuttavia, se pensi di nuovo al contesto non incorporato: nella pagina Amministrazione - Utenti, non puoi eseguire contemporaneamente l'accesso come amministratore per più utenti non incorporati in più schede. La sessione di accesso come amministratore si applicherà all'intera finestra del browser, proprio come tutte le altre sessioni utente. Pertanto, devi progettare l'accesso come amministratore in modo che venga eseguito per un solo utente alla volta. Se ci pensi, questa progettazione è più coerente con la simulazione perfetta dell'esperienza degli utenti per cui stai eseguendo l'accesso come amministratore. L'utente pied_piper, ad esempio, ha accesso solo alla dashboard Pied Piper e non può aprire altre dashboard in altre schede. Pertanto, non dovresti essere in grado di aprire dashboard diverse in schede diverse quando esegui l'accesso come amministratore per questo utente.

Conclusione

Ci auguriamo che questa guida ti sia stata utile e che ti senta pronto a procedere con la creazione dei contenuti incorporati firmati di Looker. Ci impegniamo costantemente per rendere Looker l'offerta di analisi dei dati incorporati più flessibile e solida e vogliamo conoscere il tuo feedback. Se hai domande o vuoi saperne di più, puoi interagire con noi nella community di Looker e partecipare ai nostri eventi della community.