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 importanti del prodotto. Se stai leggendo questa guida, è probabile che tu stia già incorporando contenuti Looker nella tua applicazione o che intendi 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. Per approfondire l'argomento, la lettura è un po' lunga, quindi tieni presente che questa guida non è pensata come una soluzione rapida per un problema semplice, ma piuttosto come un elemento di base per aiutarti 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 dell'incorporamento firmato, supponiamo che tu sia l'amministratore dell'istanza di Looker. Puoi lavorare 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 tutti i clienti che utilizzano il tuo prodotto, ma è necessario che la dashboard venga filtrata automaticamente per ciascun cliente, in modo che vengano visualizzati solo i dati specifici di quel cliente. Gli esempi in questo documento utilizzano due aziende fittizie: Hooli e Pied Piper.

Hai una tabella chiamata prodotti, che mostra alcune metriche di prodotto per brand diversi. Ogni brand corrisponde a un utente di incorporamento diverso (con un external_user_id diverso) nell'applicazione di incorporamento firmata. Dal momento che ogni utente incorporato dovrebbe essere in grado di vedere 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 che contiene due riquadri: uno mostra il nome del brand e l'altro il numero di prodotti del brand.

Utilizzerai l'endpoint create_sso_embed_url per generare URL incorporati 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:

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:

Voilà! 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 firmata di Looker è stata progettata per consentire agli sviluppatori di creare esperienze con i dati potenti e su misura per gli utenti, garantendo al contempo che venga mantenuta la governance dei dati definita dal modello dei dati e dai criteri di accesso ai contenuti.

Assicurarsi che la governance dei dati sia impermeabile è fondamentale per offrire un'esperienza sui dati così potente. Continua a leggere per scoprire alcuni concetti e best practice che puoi usare per progettare l'esperienza più adatta alle tue esigenze. Ecco una breve panoramica del funzionamento.

Nozioni di base sull'incorporamento firmato di Looker

È importante tenere presente che l'autenticazione e la gestione degli utenti di Looker nel contesto di incorporamento funzionano sostanzialmente allo stesso modo del contesto non di incorporamento e, in sostanza, allo stesso modo della maggior parte delle altre applicazioni web.

Questo può creare confusione nel contesto dell'incorporamento firmato di Looker, perché il passaggio dell'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 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 incorporati e 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

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 all'URL, si verifica quanto segue:

  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, 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 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

Anche se i passaggi 1-3 avvengono automaticamente in background e tutto l'utente finale vede il risultato finale (la dashboard stessa), questi passaggi sono fondamentalmente uguali ai passaggi con cui si autentica un normale utente Looker non incorporato. Supponi di volere che un utente acceda con le credenziali utente e password. La procedura sarebbe simile a questa:

  1. In qualità di amministratore di Looker, vai al riquadro Amministrazione - Utenti e utilizza la barra di ricerca per verificare se esiste già un account utente per questo utente. In caso contrario, crea un nuovo account utente.

  2. In qualità di amministratore di Looker, premi Modifica accanto all'utente dal 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 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 avvia https://mylookerinstance.cloud.looker.com/browse, apre una nuova scheda del browser e passa a una pagina a cui concede l'accesso in base alle sue autorizzazioni, la pagina verrà caricata come previsto utilizzando il cookie di sessione già impostato nella scheda originale del browser.

Lo stesso vale per gli utenti che inseriscono i video. 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 originale firmato ti reindirizzi a https://mylookerinstance.cloud.looker.com/embed/dashboards/17 in una scheda del browser. Apri quindi 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 una funzionalità della dashboard, e dovrebbero 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

Considera che hai anche partner esterni che possono possedere o gestire più brand. In questo esempio, un partner gestisce entrambi i brand Pied Piper e Hooli.

L'approccio da un punto di vista 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 questo flusso di lavoro se fornissi 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 email e password separate per ogni account.
  4. Devi fornire 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 per l'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... è una cosa molto scomoda. 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 di incorporamento: un singolo utente deve essere associato a un singolo account utente di Looker con un unico insieme di valori dell'attributo utente. Ciò è chiarito anche nella spiegazione di external_user_id nella documentazione relativa all'incorporamento 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 solo un external_user_id o una sessione utente alla volta. Non è possibile apportare modifiche alle autorizzazioni o agli attributi 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 l'app genera gli URL per 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 hanno implementato soluzioni come questa, generando di conseguenza 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 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", devi disporre di un singolo valore dell'attributo utente che conceda l'accesso a TUTTI i dati a cui il partner deve avere accesso nell'intera 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 per un utente in caso di variazioni 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.

Filtro dei risultati della dashboard

Ho capito che gli attributi utente devono specificare tutti i dati a cui l'utente può accedere attraverso l'applicazione. Tuttavia, se specifico gli attributi utente in questo modo, verranno visualizzati i dati di tutti i brand nella mia dashboard. 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 utilizza una delle opzioni di controllo di selezione singola, ad esempio il menu a discesa:

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

Ora il partner può scegliere tra questi due valori (e solo quei due) 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? Avrai notato che quando selezioni un valore di filtro, questo valore 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 usi 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 del filtro (ad esempio, in ?Brand=Pied+Piper è presente uno spazio codificato come +), quindi 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 scheda Community di Looker per discutere di queste sfumature. Se non riesci ancora ad applicare i filtri, quel post della scheda Community sarebbe un buon posto in cui aggiungere eventuali domande.

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 già abilitata sulla tua istanza Looker, contatta il tuo team di vendita di Looker per abilitarla.

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 applicare il tema nell'URL delle tue dashboard specifiche. Anche in questo caso, entri 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 maggiori informazioni su come nascondere i filtri di incorporamento delle dashboard, inclusi alcuni snippet di codice SDK incorporati, consulta il 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.

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 l'utente abbia effettivamente eseguito l'accesso con questi utenti. Come posso farlo?

Se vuoi che un utente sia in grado di eseguire test come ogni singolo utente del brand, puoi creare una funzione sudo simile nella tua app che caricherà gli URL di incorporamento per external_user_id=pied_piper quando l'utente esegue sudo come utente Piper Piper e gli URL di incorporamento per external_user_id=hooli quando l'utente esegue sudo come utente di 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. Lavoriamo costantemente per rendere Looker l'offerta di analisi dei dati incorporata più flessibile e robusta e vorremmo 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.