Como implementar a segmentação no nível da linha para conteúdo incorporado do Looker

Criado por Christopher Seymour, analista de dados sênior, e Dean Hicks, engenheiro de relações com desenvolvedores

A segmentação no nível da linha permite limitar os dados que um usuário individual pode acessar, com base nos valores armazenados em um ou mais campos do banco de dados. Este guia descreve métodos para implementar a segmentação no nível da linha em conteúdo incorporado do Looker e contém as seguintes seções:

Introdução

A funcionalidade de incorporação do Looker é um dos recursos mais eficientes e valiosos do produto Looker. Se você está lendo este guia, é provável que já esteja incorporando conteúdo do Looker no seu aplicativo ou pretenda fazer isso em breve.

O objetivo deste guia é ajudar você a entender melhor o design do recurso de incorporação do Looker e como implementar a segmentação em um aplicativo em que os parceiros podem gerenciar o acesso a várias marcas. Como o assunto é se aprofundando, esta é uma leitura um pouco longa. Lembre-se de que este guia não é uma solução rápida para um problema simples, mas um elemento básico para ajudar você a gerenciar melhor todo o caso de uso de incorporação do Looker.

Visão geral do caso de uso

Neste guia, descrevemos um caso de uso comum em que sua empresa incorpora o conteúdo do Looker no seu produto e atende a segmentos de usuários que vão receber diferentes partes dos seus dados.

Neste caso de uso de incorporação assinada, vamos supor que você seja o administrador da sua instância do Looker. Você trabalha com dois tipos de usuários incorporados externos: os clientes, que só podem acessar dados da marca específica deles, e os parceiros, que podem acessar dados de várias marcas. Você tem um painel com alguns blocos que é mostrado a todos os clientes que usam seu produto, mas precisa que o painel seja filtrado automaticamente para cada cliente para que os painéis exibam apenas os dados específicos desse cliente. Os exemplos neste documento usam duas empresas fictícias: Hooli e Pied Piper.

Você tem uma tabela chamada products, que mostra algumas métricas de produtos para marcas diferentes. Cada marca corresponde a um usuário de incorporação diferente (com um external_user_id diferente) no aplicativo de incorporação assinado. Como cada usuário de incorporação pode ver somente os dados da própria marca, você tem uma Análise que usa um filtro de acesso em um atributo de usuário da marca:

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

Você tem um painel baseado nesse Explore com dois blocos: um mostra o nome da marca e o outro mostra o número de produtos dela.

Use o endpoint create_sso_embed_url para gerar URLs incorporados desse painel para cada usuário incorporado. Este exemplo usa duas marcas: Pied Piper e Hooli. Confira o corpo da solicitação usado na chamada create_sso_embed_url para o Pied Piper, com 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"}
}

O URL que você gerou para o Pied Piper exibe o painel desta maneira:

Confira o corpo da solicitação usado na chamada create_sso_embed_url do Hooli, com 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"}
}

O URL gerado para o Hooli exibe o painel desta forma:

Voilà! O painel é filtrado de acordo com o valor de cada usuário incorporado para o atributo de usuário brand.

Mais detalhes

É muito legal! Mas e se eu quiser que um único usuário tenha acesso a várias marcas? Como posso ter certeza de que meus dados serão vistos apenas por usuários relevantes?

Boas notícias! O recurso de incorporação assinada do Looker foi projetado para capacitar os desenvolvedores a criar experiências de dados avançadas e personalizadas para os usuários, garantindo que a governança de dados definida pelo modelo de dados e as políticas de acesso ao conteúdo seja mantida.

Garantir que a governança de dados seja impecável é fundamental para fornecer essa experiência de dados poderosa. Continue lendo para explorar alguns conceitos e práticas recomendadas que você pode usar para projetar a experiência que funciona melhor para você. Primeiro, uma breve visão geral de como tudo isso funciona.

Noções básicas sobre a incorporação assinada do Looker

É importante lembrar que a autenticação e o gerenciamento de usuários do Looker no contexto de incorporação funcionam basicamente da mesma maneira que no contexto sem incorporação e da mesma forma que a maioria dos outros aplicativos da Web.

Isso pode ser confuso no contexto de incorporação assinada do Looker, porque a etapa de autenticação assinada, as configurações do usuário e o próprio painel são combinados em um URL longo e complexo. No entanto, esse URL é usado para estabelecer a sessão, que ainda se aplica mesmo após o URL ser encurtado. Ter esse conceito em mente ajudará muito no seu sucesso na criação de ótimas experiências de dados.

Estrutura do URL de incorporação assinado

Confira um dos URLs de autenticação de incorporação assinados gerados pela chamada create_sso_embed_url com o corpo da solicitação para o 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

Este é o mesmo URL decodificado e dividido em linhas individuais:

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 você acessa esse URL, acontece o seguinte:

  1. O Looker procura uma conta de usuário com external_user_id = pied_piper. Se não houver nenhuma, o Looker criará uma conta de usuário com esse external_user_id.

  2. Os detalhes da conta do usuário existente, incluindo permissões, modelos, grupos (se especificados) e valores de atributos do usuário (se especificados), são substituídos pelos detalhes da conta especificados no URL.

  3. O Looker autentica o usuário e estabelece uma sessão para ele armazenando um cookie de sessão no navegador.

  4. Em seguida, o Looker redireciona para o URL de destino, ou URL de redirecionamento, especificado na chamada create_sso_embed_url:

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

    Você pode ver esse URL de redirecionamento como um URL relativo codificado no URL de incorporação assinado original:

    %2Fembed%2Fdashboards%2F17

Embora as etapas de 1 a 3 aconteçam em segundo plano automaticamente e tudo que o usuário final veja seja o resultado final (o próprio painel), essas etapas são basicamente as mesmas que um usuário normal e não incorporado do Looker autentica. Suponha que você queira que um usuário faça login com credenciais de usuário e senha. O processo ficaria mais ou menos assim:

  1. Você (administrador do Looker) acessa o painel "Administrador - Usuários" e usa a barra de pesquisa para verificar se já existe uma conta de usuário para esse usuário. Caso contrário, crie uma nova conta de usuário.

  2. Você (administrador do Looker) clica em Editar ao lado do usuário no painel Administrador – Usuários e provisiona permissões, modelos, grupos, valores de atributos do usuário e outros valores.

  3. O usuário acessa a página de login em https://mylookerinstance.cloud.looker.com/login e digita o nome de usuário e a senha. O Looker autentica o usuário e estabelece uma sessão para ele armazenando um cookie de sessão no navegador.

  4. Em seguida, o Looker redireciona para a página de destino (geralmente https://mylookerinstance.cloud.looker.com/browse).

O cookie de sessão será aplicado a todas as guias da janela do navegador. Se o usuário começar em https://mylookerinstance.cloud.looker.com/browse, abrir uma nova guia do navegador e navegar para qualquer página a que as permissões dele tenham acesso, a página será carregada conforme o esperado usando o cookie de sessão estabelecido na guia original.

O mesmo vale para usuários incorporados. Os usuários de incorporação são um pouco mais limitados em quais páginas podem acessar na UI: eles só podem acessar URLs de Look, dashboard e Explore com o prefixo /embed. No entanto, é possível navegar manualmente para qualquer painel ao qual os detalhes da conta de usuário concedam acesso. Suponha que o URL de incorporação assinado original redirecione você para https://mylookerinstance.cloud.looker.com/embed/dashboards/17 em uma guia do navegador. Em seguida, você abre uma nova guia do navegador e carrega um painel de incorporação diferente que está na mesma pasta (e, portanto, tem as mesmas restrições de acesso): https://mylookerinstance.cloud.looker.com/embed/dashboards/19.

Embora o URL de redirecionamento especificado no URL de incorporação assinado original fosse para o painel 17, é possível ver que o painel 19 é carregado conforme o esperado se você inserir manualmente o URL em uma guia do navegador. Observe que não foi necessário outro URL de incorporação assinado para carregar um painel diferente.

O insight principal aqui é que todos os detalhes da conta do usuário estabelecidos no URL (permissões, atributos do usuário etc.) são aplicados a toda a sessão do usuário, não apenas ao painel específico especificado no URL assinado original. Em outras palavras, como o nome indica, os atributos do usuário são um recurso do usuário, não do painel, e devem ser usados para determinar os níveis de acesso de um usuário específico em todo o aplicativo, não apenas em uma guia específica.

Acesso a várias marcas ao mesmo tempo

Considere que você também tem parceiros externos que são proprietários ou administradores de várias marcas. Neste exemplo, um parceiro gerencia as marcas Pied Piper e Hooli.

A abordagem de uma perspectiva não incorporada

As sessões de usuário de incorporação assinadas funcionam basicamente da mesma forma que as sessões de usuário normais e não incorporadas do Looker. Por isso, pode ser útil reformular a abordagem problemática descrita anteriormente no contexto de uma sessão de usuário normal e não incorporada do Looker e dividir essas etapas para entender como implementar essa solução de maneira mais robusta. Esse fluxo de trabalho seria assim se você estivesse fornecendo instruções a um usuário de BI padrão que tenha acesso à interface do Looker:

  1. Você cria duas contas de usuário diferentes na página Administrador - Usuários.
    1. Na página de edição da primeira conta de usuário, você define o valor do atributo do usuário brand como pied_piper.
    2. Na página de edição da segunda conta de usuário, defina o valor do atributo de usuário da marca como hooli.
  2. Você envia e-mails de configuração das duas contas de usuário para o parceiro.
  3. O parceiro configura credenciais separadas de e-mail e senha para cada conta.
  4. Você fornece ao parceiro o link para o painel. (https://mylookerinstance.cloud.looker.com/dashboards/17) e informar que, para alternar o painel entre as marcas, será necessário voltar à página de login em outra guia e inserir as credenciais de e-mail e senha da outra conta de usuário e, em seguida, carregar o painel novamente nessa guia.

O parceiro segue as instruções. No entanto, depois de inserir o nome de usuário e a senha da conta de usuário do Hooli na segunda guia do navegador e voltar à primeira guia em que o painel do Pied Piper já estava carregado, o parceiro clica no botão Atualizar. Para a surpresa do parceiro, o painel exibe os dados do Hooli.

Agora você deve estar pensando:

Espere... isso é muito inconveniente. Qual é a melhor maneira de fazer isso?

Com certeza! O que esses cenários ajudam a ilustrar é um princípio que já é trivial no contexto não incorporado, mas que pode ser obscurecido pelas abstrações do contexto incorporado: Um único usuário humano precisa ser associado a uma única conta de usuário do Looker com um único conjunto de valores de atributos do usuário. Isso também está claro na explicação de external_user_id na documentação de incorporação assinada.

O Looker usa external_user_id para diferenciar os usuários incorporados assinados. Portanto, cada usuário precisa ter um ID exclusivo atribuído a eles.

Você pode criar uma external_user_id para um usuário com qualquer string que quiser, desde que ela seja exclusiva para esse usuário. Cada ID é associado a um conjunto de permissões, atributos de usuário e modelos. Um navegador é compatível com apenas uma external_user_id ou sessão de usuário por vez. Nenhuma alteração pode ser feita nas permissões ou nos atributos do usuário durante a sessão.

Acessar várias marcas ao mesmo tempo: o que NÃO fazer

Como acontece com qualquer solução personalizável, há certas abordagens que você deve evitar. Por exemplo, uma implementação em que o app gera os URLs para ambos external_user_ids usando as mesmas entradas na chamada create_sso_embed_url mostrada anteriormente e cria uma nova guia no app para carregar cada painel que o parceiro precisa acessar. Muitas vezes, os desenvolvedores implementam soluções como esta, o que resulta em um fluxo de trabalho incorreto para o usuário:

  1. Navegue até a guia do painel do Pied Piper.
  2. Acesse a guia do painel do Hooli.
  3. Volte para a guia do painel do Pied Piper.
  4. Clique no botão Atualizar no painel do Pied Piper.

... o painel do Pied Piper mostra os dados do Hooli.

Você pode tentar uma abordagem semelhante, mas use o mesmo test_user external_user_id para as duas chamadas create_sso_embed_url. Mas o comportamento é exatamente o mesmo: quando a guia é recarregada com o painel do Pied Piper, ela mostra os dados do Hooli.

Como posso ter certeza de que o painel de cada marca exibe somente os dados dela?

Como usar as práticas recomendadas

Para aplicar a abordagem descrita na seção A abordagem de uma perspectiva não incorporada, você vai precisar de um único valor de atributo do usuário que conceda acesso a TODOS os dados que o parceiro pode acessar no aplicativo. Para isso, use valores separados por vírgula para o atributo 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"}
}

Para que essa sintaxe funcione, confira se o atributo do usuário está definido como Filtro de string (avançado):

Observe que você ainda pode alterar o conjunto de atributos de um usuário se algo mudar nos níveis de acesso aos dados. Por exemplo, se o parceiro assumir a propriedade de uma terceira marca, você poderá adicionar essa terceira marca à lista separada por vírgulas que você especificou para o atributo de usuário brand. Dessa forma, quando ele sair e fizer login novamente, as alterações serão aplicadas.

Como filtrar os resultados do painel

Entendi que os atributos do usuário precisam especificar todos os dados que um usuário pode acessar no aplicativo. No entanto, se eu especificar os atributos do usuário dessa forma, ele mostrará os dados de todas essas marcas no meu painel. Como faço para restringir os resultados de um determinado painel a uma marca específica?

A maneira correta de filtrar um painel específico é usar filtros de painel comuns. Isso pode parecer óbvio agora, mas vimos que algumas pessoas ficam presas nos atributos do usuário como a única maneira de aplicar filtros no contexto de incorporação, talvez porque user_attributes seja um parâmetro no URL de incorporação assinado, e os filtros não seja.

Exija um valor de filtro e use uma das opções de controle de seleção única, como no menu suspenso:

Verifique se o filtro foi aplicado ao campo correto em todos os blocos necessários:

Agora seu parceiro pode selecionar entre esses dois valores, porque as opções disponíveis no menu suspenso são limitadas pelos atributos do usuário:

Preenchimento prévio dos filtros do painel

Ok, agora o painel pode ser filtrado para uma marca específica, mas quero que o valor do filtro já esteja definido como uma marca específica quando o usuário carregar o painel dessa marca no meu app.

Mais uma vez, vale a pena pensar em como isso funciona no contexto não incorporado. Como enviar a alguém um link para um painel que já tenha um valor de filtro específico? Você deve ter notado que, ao selecionar um valor de filtro, ele aparece no URL do painel:

Inclua essa parte do URL no target_url para a chamada de 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 você estiver usando o SDK de incorporação, poderá usar withFilters para especificar os filtros iniciais a serem aplicados ao conteúdo incorporado:

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

Se você estiver usando seu próprio script personalizado, verifique se adicionou o filtro ao URL antes que o caminho seja codificado. Alguns valores podem já estar codificados na string de filtro (por exemplo, há um espaço codificado como + em ?Brand=Pied+Piper), então esses valores serão codificados duas vezes no URL final. Confira "SO internal dashboard - set dashboard filter as part of URL?" Postagem na Comunidade do Looker para uma discussão sobre essas nuances. Caso ainda tenha problemas para aplicar os filtros, essa postagem na Comunidade é um bom lugar para adicionar dúvidas.

Como ocultar os filtros do painel

Ok, vejo como definir os filtros iniciais nos meus painéis, mas não quero que o parceiro altere os filtros do painel por conta própria. O valor do filtro deve ser determinado APENAS pelo painel que o parceiro acessou no meu app. Como esconder os filtros do painel?

Você pode usar temas para isso. Os temas são um recurso pago. Por isso, se você ainda não ativou esse recurso na sua instância do Looker, entre em contato com a equipe de vendas do Looker para fazer isso.

Quando o recurso estiver ativado, acesse a seção Controles do painel da página Administrador - Temas, onde você pode limpar a opção Barra de filtros de exibição:

Em seguida, é possível definir seu tema como padrão ou aplicar o tema ao URL dos seus painéis específicos. Novamente, isso entraria no target_url da chamada 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"}
}

Para mais informações sobre como ocultar filtros do painel de incorporação, incluindo alguns snippets de código do SDK de incorporação, confira este tutorial do YouTube, Incorporar o Looker com filtros personalizados.

O resultado final precisa ser idêntico à experiência do usuário da pergunta original:

Mas agora, como os valores do filtro são codificados nos respectivos URLs de destino incorporados no aplicativo, o painel de cada marca sempre mostrará o painel filtrado para a marca correta, mesmo quando você alternar entre as guias.

Testar como outros usuários

Agora a experiência do usuário parece muito próxima do que eu imaginava. Mas, no meu caso de uso, o parceiro tem permissões e outras configurações de usuário que os usuários individuais com external_user_id=pied_piper e external_user_id=hooli não têm, o que leva a opções diferentes na UI e a uma experiência do usuário ligeiramente diferente em geral. Quero permitir que um usuário veja tudo exatamente como os usuários do pied_piper e pied_piper enxergam isso, como se a pessoa tivesse feito login como esses usuários. Como faço isso?

Se você quiser que um usuário possa testar como cada um dos usuários de marca, crie uma função sudo semelhante no app para carregar os URLs incorporados para external_user_id=pied_piper quando o usuário estiver executando o sudo como o usuário do Pied Piper e os URLs de incorporação para o external_user_id=hooli quando o usuário estiver executando o sudo como o usuário do Hooli. Também é possível usar o endpoint da API login_user para executar o sudo como o usuário da marca com a API, caso o app use a API.

Mas, se você pensar de novo no contexto de não incorporação: na página Administrador - Usuários, não é possível executar sudo simultaneamente como vários usuários não incorporados em várias guias. A sessão sudo será aplicada a toda a janela do navegador, assim como todas as outras sessões de usuário. Portanto, crie o sudo para apenas um usuário por vez. Se você pensar a respeito, esse design é mais consistente com imitar perfeitamente a experiência dos usuários que você está executando no sudo. O usuário pied_piper, por exemplo, tem acesso somente ao painel do Pied Piper e não pode abrir painéis adicionais em outras guias. Portanto, não vai ser possível abrir painéis diferentes em guias distintas ao executar o sudo como esse usuário.

Conclusão

Esperamos que o guia tenha sido útil e que você esteja se sentindo bem preparado para desenvolver seu conteúdo de incorporação assinado pelo Looker. Trabalhamos continuamente para tornar o Looker a oferta de análise de dados incorporados mais flexível e robusta e queremos saber sua opinião. Se você tiver dúvidas ou quiser saber mais, entre em contato com a nossa equipe na Comunidade Looker e participe dos nossos eventos.