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 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 Looker. 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 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. 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 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 contenuti Looker all'interno del tuo prodotto e fornisce segmenti di utenti che dovrebbero vedere sezioni diverse dei tuoi dati.

Per questo caso d'uso dell'incorporamento firmato, supponiamo che tu sia l'amministratore dell'istanza di Looker. Collabori con due tipi di utenti incorporati esterni: i clienti, che devono poter accedere solo ai dati relativi al loro brand specifico, e i 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 mostrino 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 incorporato diverso (con un external_user_id diverso) nell'applicazione di incorporamento firmata. Dal momento che ogni utente incorporato dovrebbe poter 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 con due riquadri: uno mostra il nome del brand e l'altro il numero di prodotti per quel brand.

Utilizzerai l'endpoint create_sso_embed_url per generare URL incorporati di questa dashboard per ogni utente incorporato. In questo esempio vengono utilizzati 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 di ciascun utente incorporato per l'attributo utente brand.

Approfondimento

Molto bene. 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 utilizzare per progettare l'esperienza più adatta alle tue esigenze. Innanzitutto, facciamo una breve panoramica di come funziona.

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 di autenticazione firmato, 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 rimane valida anche dopo l'abbreviazione dell'URL. Tenere a mente questo concetto sarà molto importante per creare esperienze con i dati ottimali.

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

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

  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 URL di reindirizzamento, specificato nella chiamata create_sso_embed_url:

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

    Questo URL di reindirizzamento può essere visualizzato come URL relativo codificato nell'URL di incorporamento originale firmato:

    %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 credenziali utente e password. La procedura è simile alla seguente:

  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 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 viene applicato a tutte le schede della 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 incorporati. Gli utenti incorporati sono un po' più limitati in termini di pagine accessibili nella UI: possono accedere solo agli URL Look, dashboard ed Esplora con il prefisso /embed. Tuttavia, l'utente è comunque libero di passare manualmente a qualsiasi dashboard a cui i dettagli del suo account utente gli ha concesso 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. Quindi apri una nuova scheda del browser e carichi una dashboard di incorporamento diversa che si trova nella stessa cartella (e che quindi presenta le stesse restrizioni di accesso): https://mylookerinstance.cloud.looker.com/embed/dashboards/19.

Anche se l'URL di reindirizzamento specificato nell'URL incorporato originale firmato era della dashboard 17, puoi vedere 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 incorporato firmato per caricare una dashboard diversa.

In questo caso, 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 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.

Accedere 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 di incorporamento firmate funzionano sostanzialmente allo stesso modo delle sessioni utente Looker standard e non incorporate. Pertanto, può essere utile ridefinire l'approccio problematico descritto in precedenza nel contesto di una sessione utente Looker regolare e non incorporata e suddividere questi passaggi per comprendere come implementare questa soluzione in modo più efficace. Ecco come sarebbe questo flusso di lavoro se fornissi istruzioni a un utente BI standard che ha accesso alla UI di Looker:

  1. Puoi creare 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. Devi inviare al partner email per la creazione dell'account di 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 dire che, per poter cambiare la dashboard da un brand all'altro, dovrà tornare alla pagina di accesso in un'altra scheda, inserire l'email e la password dell'altro account utente e poi caricare nuovamente 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 tornare alla prima scheda in cui la dashboard di Pied Piper era già caricata, il partner preme il 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. Ciò che questi scenari aiutano a illustrare è un principio che è già banale nel contesto non incorporato, ma che può essere oscurato dalle astrazioni del contesto di incorporamento: un singolo utente umano dovrebbe essere associato a un singolo account utente Looker con un singolo set di valori di attributi utente. Ciò è chiarito anche nella spiegazione di external_user_id nella documentazione relativa all'incorporamento firmato.

Looker utilizza external_user_id per differenziare gli utenti incorporati che hanno eseguito l'accesso, quindi a ogni utente deve essere assegnato un ID univoco.

Puoi creare un external_user_id per un utente con qualsiasi stringa tu voglia, 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 Pied Piper.
  2. Vai alla scheda della dashboard Hooli.
  3. Torna alla scheda della dashboard Pied Piper.
  4. Premi il pulsante Ricarica sulla dashboard Pied Piper.

... la dashboard Pifferaio magico 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. Il comportamento è esattamente lo stesso: una volta ricaricata la scheda con la dashboard Pied Piper, vengono visualizzati i dati relativi a Hooli.

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

Utilizzo delle best practice

Per applicare l'approccio descritto nella sezione "L'approccio da un punto di vista non incorporato", è necessario un singolo valore di attributo utente che conceda l'accesso a TUTTI i dati a cui il partner deve avere accesso all'interno dell'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 su 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 specificato per il suo attributo utente brand. In questo modo, quando si disconnettono e accedono di nuovo, le modifiche verranno applicate.

Filtrare i risultati della dashboard

Ho capito che gli attributi utente devono specificare tutti i dati a cui un 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 posso restringere i risultati di una determinata dashboard a un brand specifico?

Il modo corretto per filtrare una determinata dashboard è utilizzare i valori standard filtri della dashboard! (Ora questo può sembrare ovvio, ma abbiamo notato che alcune persone si bloccano sugli attributi dell'utente come unico modo per applicare filtri nel contesto di incorporamento, forse perché user_attributes è un parametro nell'URL di incorporamento firmato e i filtri non lo sono).

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

Verifica che il filtro venga applicato al campo corretto su 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 pensare a come funziona nel contesto non incorporato. Come si invia a qualcuno un link a una dashboard a cui è già applicato un determinato valore di filtro? Avrai notato che quando selezioni un valore di filtro, questo valore viene visualizzato nell'URL della dashboard:

Includi quella 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, è presente uno spazio codificato come + in ?Brand=Pied+Piper), quindi questi valori verranno codificati due volte nell'URL finale. Puoi consultare la sezione "Dashboard incorporata - 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 sia il partner a modificare i filtri della dashboard. Il valore del filtro deve essere determinato SOLO dalla dashboard a cui il partner ha raggiunto la 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 attivarla.

Una volta attivata la funzione, vai alla sezione Controlli della dashboard della pagina Amministrazione - Temi, dove puoi cancellare l'opzione Visualizza barra dei filtri:

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.

Test come altri utenti

Ora l'esperienza utente sembra molto simile a quanto previsto in origine. Tuttavia, nel mio caso d'uso, il partner ha autorizzazioni diverse e altre impostazioni utente che i singoli utenti con external_user_id=pied_piper e external_user_id=hooli non hanno, il che genera opzioni diverse nell'interfaccia utente e solo un'esperienza utente leggermente diversa nel complesso. Voglio consentire a un utente di vedere tutto esattamente come lo vedono gli utenti pied_piper e pied_piper , 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 incorporati per external_user_id=hooli quando l'utente esegue sudo come utente di Hooli. Puoi anche utilizzare l'endpoint API login_user per sudo come utente del brand con l'API se la tua app la utilizza.

Tuttavia, ripensando al contesto non di incorporamento: nella pagina Amministrazione - Utenti, non puoi eseguire contemporaneamente sudo più utenti non incorporati in più schede: la sessione sudo verrà applicata all'intera finestra del browser, proprio come tutte le altre sessioni utente. Ti consigliamo quindi di progettare sudo per eseguire il comando sudo come un solo utente alla volta. Inoltre, a pensarci bene, questo design è più coerente con l'imitazione perfetta dell'esperienza degli utenti con cui stai sudondo. L'utente pied_piper, ad esempio, ha accesso solo alla dashboard 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 l'operazione su questo utente.

Conclusione

Ci auguriamo che questa guida ti sia stata utile e che ti senta pronto per procedere con la creazione dei tuoi contenuti incorporati firmati da 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.