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

Autore: 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 di Looker incorporati e contiene le seguenti sezioni:

Introduzione

La funzionalità di incorporamento di Looker è una delle funzionalità più potenti e utili del prodotto. Se stai leggendo questa guida, è probabile che tu abbia già incorporato i contenuti di Looker nella tua applicazione o che intenda farlo nel prossimo futuro.

Questa guida ha lo scopo di aiutarti a comprendere meglio il design 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'analisi approfondita dell'argomento, la lettura è un po' lunga. Tieni presente che questa guida non è pensata per essere una soluzione rapida per un problema semplice, ma piuttosto un elemento costitutivo che ti aiuterà a gestire meglio l'intero caso d'uso di incorporamento di Looker.

Panoramica del caso d'uso

Questa guida descrive un caso d'uso comune in cui la tua azienda incorpora i contenuti di Looker nel tuo prodotto e serve segmenti di utenti che devono visualizzare diversi segmenti dei tuoi dati.

Per questo caso d'uso di incorporamento firmato, supponiamo che tu sia l'amministratore della tua istanza di Looker. Puoi lavorare con due tipi di utenti di incorporamento esterni: clienti, che dovrebbero essere in grado di 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 tutti i clienti che utilizzano il tuo prodotto, ma devi filtrare automaticamente la dashboard per ciascun cliente in modo che vengano visualizzati solo i dati specifici per quel cliente. Gli esempi in questo documento utilizzano due aziende immaginarie: Hooli e Pied Piper.

Hai una tabella denominata products che mostra alcune metriche dei prodotti per brand diversi. Ogni brand corrisponde a un utente di incorporamento diverso (con un external_user_id diverso) nell'applicazione di incorporamento firmata. Poiché ogni utente incorporato deve essere in grado di vedere solo i dati relativi al 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 che contiene due riquadri: uno mostra il nome del brand e l'altro il numero di prodotti del brand.

Utilizza l'endpoint create_sso_embed_url per generare gli URL di incorporamento di questa dashboard per ogni utente che può incorporarla. Questo esempio utilizza due brand: Pied Piper e Hooli. Di seguito è riportato il corpo della richiesta da utilizzare 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:

Di seguito è riportato 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:

Ecco fatto. La dashboard viene filtrata in base al valore di ciascun utente di incorporamento per l'attributo utente marca.

Approfondimenti

Fantastico. E se volessi concedere a un singolo utente l'accesso a più brand? Come faccio ad assicurarmi che i miei dati vengano visualizzati solo dagli utenti pertinenti?

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

Assicurarsi che la governance dei dati sia perfetta è fondamentale per offrire un'esperienza dati efficace. Continua a leggere per scoprire alcuni concetti e best practice che puoi utilizzare per progettare l'esperienza più adatta a te. Innanzitutto, ecco una breve panoramica del funzionamento.

Nozioni di base sull'embedding firmato di Looker

È importante tenere presente che l'autenticazione e la gestione degli utenti di Looker nel contesto di incorporamento funzionano in modo sostanzialmente uguale a quello del contesto non di incorporamento e in modo sostanzialmente uguale alla maggior parte delle altre applicazioni web.

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

Struttura dell'URL di incorporamento firmato

Ecco uno degli URL di autenticazione dell'embed firmato generato 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

Di seguito viene riportato 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 esiste, Looker crea un nuovo account utente con quel external_user_id.

  2. I dettagli dell'account utente esistente, tra cui 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 l'utente memorizzando un cookie di sessione nel browser.

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

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

    Puoi vedere 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 veda solo il risultato finale (la dashboard stessa), questi passaggi sono sostanzialmente gli stessi di quelli con cui un utente Looker normale non incorporato esegue l'autenticazione. Supponiamo che tu voglia che un utente acceda con le credenziali utente e password. La procedura sarà simile alla seguente:

  1. Tu (l'amministratore di Looker) vai al riquadro Amministrazione - 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 riquadro Amministrazione - Utenti ed esegui il provisioning dell'utente con autorizzazioni, modelli, gruppi, valori degli attributi utente e altri valori.

  3. L'utente accede 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 l'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 le sue autorizzazioni gli consentono di accedere, la pagina verrà caricata come previsto utilizzando il cookie della sessione già stabilito nella scheda del browser originale.

Lo stesso vale per gli utenti di embed. Gli utenti incorporati hanno un accesso un po' più limitato alle pagine dell'interfaccia utente: possono accedere solo agli URL di look, dashboard ed esplorazioni con il prefisso /embed. Tuttavia, sono comunque liberi di accedere manualmente a qualsiasi dashboard a cui i dettagli del loro account utente consentono 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. Apri una nuova scheda del browser e carica un'altra dashboard di incorporamento 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 vedere che la dashboard 19 si carica 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 chiave è 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 specificata 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 entrambi i brand Pied Piper e Hooli.

L'approccio dal punto di vista di un video non incorporato

Le sessioni utente con embedding firmato funzionano fondamentalmente nello stesso modo delle sessioni utente di Looker normali non con embedding, quindi può essere utile riformulare l'approccio problematico descritto in precedenza nel contesto di una sessione utente di Looker normale non con embedding e suddividere questi passaggi per capire come implementare questa soluzione in modo più solido. Ecco come sarebbe il flusso di lavoro se dessi istruzioni a un utente di BI standard che ha accesso all'interfaccia utente 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 email e password separate per ogni account.
  4. Fornisci al partner il link alla dashboard. (https://mylookerinstance.cloud.looker.com/dashboards/17) e digli che, per passare da un brand all'altro nella dashboard, dovrà tornare alla pagina di accesso in un'altra scheda, inserire le credenziali email e password del suo altro account utente e ricaricare la dashboard nella scheda in questione.

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 aver fatto clic sulla prima scheda in cui era già caricata la dashboard di Pied Piper, il partner fa clic sul pulsante Ricarica. Con sorpresa del partner, la dashboard mostra i dati di Hooli.

A questo punto potresti pensare:

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

Certo che c'è. Questi scenari aiutano a illustrare un principio già banale nel contesto non incorporato, ma che può essere oscurato dalle astrazioni del contesto di incorporamento: un singolo utente deve essere associato a un singolo account utente di Looker con un unico insieme di valori dell'attributo utente. Questo è chiarito anche nella nostra spiegazione del parametro external_user_id nella documentazione relativa all'embedding firmato.

Looker utilizza external_user_id per distinguere gli utenti di incorporamento che hanno eseguito l'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 un solo external_user_id, o sessione utente, alla volta. Non è possibile apportare modifiche alle autorizzazioni o agli attributi di un utente durante la sessione.

Accesso a più brand contemporaneamente: cosa NON fare

Come per qualsiasi soluzione personalizzabile, ci sono alcuni approcci che dovresti 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. Spesso gli sviluppatori implementano soluzioni come questa, che comportano un flusso di lavoro errato per l'utente:

  1. Vai alla scheda della dashboard di Pied Piper.
  2. Vai alla scheda della dashboard di Hooli.
  3. Torna alla scheda della dashboard di Pied Piper.
  4. Fai clic sul pulsante Ricarica nella dashboard di Pied Piper.

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

Puoi provare un approccio simile, ma utilizzare 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?

Applicazione delle best practice

Per applicare l'approccio descritto nella sezione "L'approccio dal punto di vista di un'integrazione non incorporata", è necessario un singolo valore dell'attributo utente che conceda l'accesso a TUTTI i dati a cui il partner deve avere accesso nell'intera applicazione. A tale scopo, utilizza un valore separato da virgole per l'attributo marca 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 cambia qualcosa nei 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 escono e rientrano, 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. Tuttavia, se specifico gli attributi utente in questo modo, nella mia 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 notato che alcune persone si bloccano 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 a selezione singola, ad esempio il menu a discesa:

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

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

Precompilazione dei filtri della dashboard

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

Anche in questo caso, è utile capire come funziona nel contesto non di incorporamento. Come inviare a un utente un link a una dashboard a cui è già stato applicato un valore di filtro specifico? Probabilmente 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 di incorporamento, 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 del filtro (ad esempio, in ?Brand=Pied+Piper è presente uno spazio codificato come +), pertanto questi valori verranno sottoposti a doppia codifica nell'URL finale. Puoi consultare l'articolo "Dashboard incorporata in SO: impostare il filtro della dashboard come parte dell'URL?" Post della community di Looker per una discussione su queste sfumature. Se hai ancora difficoltà ad applicare i filtri, puoi anche aggiungere eventuali domande nel post della scheda Community.

Nascondere i filtri della dashboard

Ok, ho capito come impostare i filtri iniziali nelle mie dashboard, ma non voglio nemmeno 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 faccio a nascondere i filtri della dashboard?

A questo scopo puoi utilizzare i temi. I temi sono una funzionalità a pagamento, quindi, se non l'hai ancora attivata nella tua istanza di Looker, devi contattare il team di vendita di Looker per farlo.

Una volta attivata la funzionalità, vai alla sezione Controlli dashboard della pagina Amministrazione - Temi, dove puoi deselezionare l'opzione Barra dei filtri di visualizzazione:

A questo punto, puoi impostare il tema come predefinito o applicarlo all'URL di dashboard specifiche. Anche in questo caso, andrà inserito in 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 saperne di più sull'occultamento dei filtri della dashboard incorporata, 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, 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 per il brand corretto anche quando passi da una scheda all'altra.

Testare come altri utenti

Ora l'esperienza utente è molto simile a quella che avevo immaginato inizialmente. Tuttavia, nel mio caso d'uso, il partner ha autorizzazioni e altre impostazioni utente diverse da quelle dei singoli utenti con external_user_id=pied_piper e external_user_id=hooli, il che comporta opzioni diverse disponibili nell'interfaccia utente e un'esperienza utente leggermente diversa in generale. Voglio consentire a un utente di vedere tutto esattamente come lo vedono gli utenti pied_piper e hooli , come se la persona avesse effettivamente eseguito l'accesso come questi utenti. Come faccio a farlo?

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

Tuttavia, se ripensi al contesto non incorporato: nella pagina Amministrazione - Utenti, non puoi eseguire sudo contemporaneamente come più utenti non incorporati in più schede. La sessione sudo verrà applicata all'intera finestra del browser, come tutte le altre sessioni utente. Pertanto, devi progettare sudo in modo che esegua il sudo come un solo utente alla volta. E, se ci pensi, questo design è più coerente con la simulazione perfetta dell'esperienza degli utenti con cui esegui sudo. L'utente pied_piper, ad esempio, ha accesso solo alla dashboard di Pied Piper e non può aprire dashboard aggiuntive in schede aggiuntive. Di conseguenza, non dovresti essere in grado di aprire dashboard diverse in schede diverse anche quando esegui sudo come questo utente.

Conclusione

Ci auguriamo che questa guida ti sia stata utile e che tu ti senta ben preparato per procedere con la creazione dei contenuti incorporati firmati di Looker. Ci impegniamo costantemente per rendere Looker la soluzione di analisi dei dati incorporata 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.