Implementar a segmentação ao nível da linha para conteúdo do Looker incorporado

Artigo escrito por Christopher Seymour, Sr. Data Analyst, e Dean Hicks, Developer Relations Engineer

A segmentação ao nível da linha permite-lhe limitar os dados aos quais um utilizador individual pode aceder, com base nos valores armazenados num ou mais campos da base de dados. Este guia descreve métodos para implementar a segmentação ao nível da linha no conteúdo incorporado do Looker e contém as seguintes secções:

Introdução

A funcionalidade de incorporação do Looker é uma das funcionalidades mais poderosas e valiosas do produto Looker. Se estiver a ler este guia, é provável que já esteja a incorporar conteúdo do Looker na sua aplicação ou que pretenda fazê-lo num futuro próximo.

Este guia destina-se a ajudar a compreender melhor a conceção da funcionalidade de incorporação do Looker e como implementar a segmentação numa aplicação onde os parceiros podem gerir o acesso a várias marcas. Como uma análise detalhada do tópico, é uma leitura um pouco longa. Por isso, tenha em atenção que este guia não se destina a ser uma correção rápida para um problema simples, mas sim um bloco de construção para ajudar a gerir melhor todo o exemplo de utilização da incorporação do Looker.

Vista geral do exemplo de utilização

Este guia descreve um exemplo de utilização comum em que a sua empresa está a incorporar conteúdo do Looker no seu produto e a publicar segmentos de utilizadores que devem ver diferentes fatias dos seus dados.

Para este exemplo de utilização de incorporação assinada, suponha que é o administrador da sua instância do Looker. Trabalha com dois tipos de utilizadores incorporados externos: clientes, que só devem poder aceder a dados relativos à respetiva marca específica, e parceiros, que vão poder aceder a dados de várias marcas. Tem um painel de controlo com alguns mosaicos que mostra a todos os clientes que usam o seu produto, mas precisa que o painel de controlo seja filtrado automaticamente para cada cliente, de modo que os painéis de controlo apresentem apenas os dados específicos desse cliente. Os exemplos neste documento usam duas empresas fictícias: Hooli e Pied Piper.

Tem uma tabela denominada produtos, que mostra algumas métricas de produtos para diferentes marcas. Cada marca corresponde a um utilizador incorporado diferente (com um external_user_id diferente) na aplicação incorporada assinada. Uma vez que cada utilizador incorporado só deve poder ver os dados da sua própria marca, tem uma análise detalhada que usa um filtro de acesso num atributo do utilizador marca:

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

Tem um painel de controlo baseado nesta análise detalhada e que tem dois mosaicos: um mostra o nome da marca e o outro mostra o número de produtos dessa marca.

Use o ponto final create_sso_embed_url para gerar URLs de incorporação deste painel de controlo para cada utilizador de incorporação. Este exemplo usa duas marcas: Pied Piper e Hooli. Segue-se o corpo do pedido que usa na chamada create_sso_embed_url para 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 gerou para a Pied Piper apresenta o painel de controlo da seguinte forma:

Segue-se o corpo do pedido usado na chamada create_sso_embed_url para a 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 a Hooli apresenta o painel de controlo da seguinte forma:

Voilà! O painel de controlo é filtrado de acordo com o valor de cada utilizador incorporado para o atributo do utilizador marca.

Aprofundar

Muito fixe! Mas e se quiser dar a um único utilizador acesso a várias marcas? Como posso garantir que os meus dados só são vistos por utilizadores relevantes?

Boas notícias! A funcionalidade de incorporação assinada do Looker foi concebida para permitir aos programadores criar experiências de dados personalizadas e eficazes para os utilizadores, ao mesmo tempo que garante que a administração de dados definida pelo seu modelo de dados e pelas políticas de acesso ao conteúdo é mantida.

Garantir que a gestão de dados é hermética é fundamental para oferecer essa experiência de dados poderosa. Continue a ler para explorar alguns conceitos e práticas recomendadas que pode usar para criar a experiência que funciona melhor para si. Primeiro, uma breve vista geral de como tudo isto funciona.

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

É importante ter em atenção que a autenticação e a gestão de utilizadores do Looker no contexto de incorporação funcionam fundamentalmente da mesma forma que no contexto não incorporado e fundamentalmente da mesma forma que a maioria das outras aplicações Web.

Isto pode ser confuso no contexto da incorporação assinada do Looker, porque o passo de autenticação assinada, as definições do utilizador e o próprio painel de controlo estão todos combinados num URL longo e complexo. No entanto, esse URL é usado para estabelecer a sessão, o que continua a aplicar-se mesmo depois de o URL ser abreviado. Ter este conceito em mente é fundamental para o seu sucesso na criação de excelentes experiências de dados.

Estrutura do URL de incorporação assinado

Seguem-se alguns dos URLs de autenticação de incorporação assinados gerados pela chamada create_sso_embed_url com o corpo do pedido para 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

Segue-se o mesmo URL descodificado 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 acede a este URL, acontecem algumas coisas:

  1. O Looker procura uma conta de utilizador existente com external_user_id = pied_piper. Se não existir nenhuma, o Looker cria uma nova conta de utilizador com esse external_user_id.

  2. Os detalhes da conta do utilizador existente, incluindo autorizações, modelos, grupos (se especificado) e valores de atributos do utilizador (se especificado), são substituídos pelos detalhes da conta especificados no URL.

  3. O Looker autentica o utilizador e estabelece uma sessão para esse utilizador armazenando um cookie de sessão no navegador.

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

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

    Pode ver este URL de redirecionamento como um URL relativo codificado no URL incorporado assinado original:

    %2Fembed%2Fdashboards%2F17

Embora os passos 1 a 3 ocorram automaticamente em segundo plano e o utilizador final apenas veja o resultado final (o próprio painel de controlo), estes passos são fundamentalmente os mesmos que um utilizador normal do Looker que não usa a incorporação usa para se autenticar. Suponhamos que quer que um utilizador inicie sessão com credenciais de utilizador e palavra-passe. O processo seria semelhante ao seguinte:

  1. O administrador do Looker navega para o painel Admin – Users e usa a barra de pesquisa para verificar se já existe uma conta de utilizador para este utilizador. Caso contrário, crie uma nova conta de utilizador.

  2. O administrador do Looker clica em Editar junto ao utilizador no painel Administração – Utilizadores e aprovisiona o utilizador com autorizações, modelos, grupos, valores de atributos do utilizador e outros valores.

  3. O utilizador acede à página de início de sessão em https://mylookerinstance.cloud.looker.com/login e introduz o nome de utilizador e a palavra-passe. O Looker autentica o utilizador e estabelece uma sessão para esse utilizador armazenando um cookie de sessão no navegador.

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

Tenha em atenção que o cookie de sessão se aplica a todos os separadores na janela do navegador. Se o utilizador começar em https://mylookerinstance.cloud.looker.com/browse, abrir um novo separador do navegador e navegar para qualquer página à qual as respetivas autorizações lhe dão acesso, a página é carregada conforme esperado através do cookie de sessão que já foi estabelecido no separador do navegador original.

O mesmo se aplica aos utilizadores de incorporação. Os utilizadores incorporados têm um acesso um pouco mais limitado às páginas da IU. Só podem aceder a URLs de Looks, painéis de controlo e explorações com o prefixo /embed. No entanto, continuam a poder navegar manualmente para qualquer painel de controlo ao qual os detalhes da respetiva conta de utilizador lhes concedam acesso. Suponhamos que o URL incorporado assinado original redireciona para https://mylookerinstance.cloud.looker.com/embed/dashboards/17 num separador do navegador. Em seguida, abre um novo separador do navegador e carrega um painel de controlo incorporado diferente que se encontra na mesma pasta (e, por conseguinte, tem as mesmas restrições de acesso): https://mylookerinstance.cloud.looker.com/embed/dashboards/19.

Embora o URL de redirecionamento especificado no URL incorporado assinado original fosse para o painel de controlo 17, pode ver que o painel de controlo 19 é carregado conforme esperado se introduzir manualmente o URL num separador do navegador. Tenha em atenção que não foi necessário outro URL incorporado assinado para carregar um painel de controlo diferente.

A principal estatística aqui é que todos os detalhes da conta de utilizador estabelecidos no URL (autorizações, atributos do utilizador, etc.) são aplicados a toda a sessão do utilizador e não apenas ao painel de controlo específico no URL assinado original. Por outras palavras, como o nome indica, os atributos do utilizador são uma caraterística do utilizador e não do painel de controlo. Devem ser usados para determinar os níveis de acesso de um utilizador específico em toda a aplicação e não apenas num separador específico.

Aceder a várias marcas em simultâneo

Tenha em atenção que também tem parceiros externos que podem ser proprietários ou gerir várias marcas. Neste exemplo, um parceiro gere as marcas Pied Piper e Hooli.

A abordagem de uma perspetiva sem incorporação

As sessões de utilizador incorporadas com assinatura funcionam fundamentalmente da mesma forma que as sessões de utilizador do Looker normais e não incorporadas. Por isso, pode ser útil reformular a abordagem problemática descrita anteriormente no contexto de uma sessão de utilizador do Looker normal e não incorporada, e detalhar esses passos para ajudar a compreender como implementar esta solução de uma forma mais robusta. Veja como seria esse fluxo de trabalho se estivesse a dar instruções a um utilizador de BI padrão com acesso à IU do Looker:

  1. Cria duas contas de utilizador diferentes na página Administração – Utilizadores.
    1. Na página de edição da primeira conta de utilizador, define o valor do atributo do utilizador marca como pied_piper.
    2. Na página de edição da segunda conta de utilizador, define o valor do atributo do utilizador marca como hooli.
  2. Envia emails de configuração da conta para ambas as contas de utilizador ao parceiro.
  3. O parceiro configura credenciais de email e palavra-passe separadas para cada conta.
  4. Dá ao parceiro o link para o painel de controlo. (https://mylookerinstance.cloud.looker.com/dashboards/17) e diga-lhe que, para alternar o painel de controlo entre marcas, tem de voltar à página de início de sessão noutro separador e introduzir as credenciais de email e palavra-passe da outra conta de utilizador e, em seguida, carregar novamente o painel de controlo nesse separador.

O parceiro segue as instruções. No entanto, depois de introduzir o nome de utilizador e a palavra-passe da conta de utilizador do Hooli no segundo separador do navegador e, em seguida, navegar novamente para o primeiro separador onde o painel de controlo do Pied Piper já estava carregado, o parceiro clica no botão Recarregar. Para surpresa do parceiro, o painel de controlo apresenta os dados da Hooli!.

Neste momento, pode estar a pensar:

Espera… isto é muito inconveniente. Qual é a melhor forma de o fazer?

Claro que sim! Estes 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 utilizador humano deve estar associado a uma única conta de utilizador do Looker com um único conjunto de valores de atributos do utilizador. Isto também é esclarecido na nossa explicação do external_user_id na nossa documentação de incorporação assinada.

O Looker usa external_user_id para diferenciar os utilizadores de incorporação com sessão iniciada, pelo que cada utilizador tem de ter um ID exclusivo atribuído.

Pode criar um external_user_id para um utilizador com qualquer string que quiser, desde que seja exclusivo desse utilizador. Cada ID está associado a um conjunto de autorizações, atributos do utilizador e modelos. Um único navegador só pode suportar um external_user_id ou uma sessão do utilizador de cada vez. Não é possível fazer alterações às autorizações nem aos atributos do utilizador durante uma sessão.

Aceder a várias marcas em simultâneo: o que NÃO deve fazer

Tal como acontece com qualquer solução personalizável, existem determinadas abordagens que deve evitar. Por exemplo, uma implementação em que a sua app gera os URLs para ambos os casos external_user_ids usando as mesmas entradas na chamada create_sso_embed_url apresentada anteriormente e cria um novo separador na app para carregar cada painel de controlo ao qual o parceiro precisa de aceder. Vemos frequentemente os programadores implementarem soluções como esta, o que resulta num fluxo de trabalho incorreto para o utilizador:

  1. Navegue para o separador do painel de controlo Pied Piper.
  2. Navegue para o separador do painel de controlo da Hooli.
  3. Navegue novamente para o separador do painel de controlo da Pied Piper.
  4. Clique no botão Atualizar no painel de controlo do Pied Piper.

…o painel de controlo do Pied Piper apresenta os dados da Hooli!

Pode experimentar uma abordagem semelhante, mas usar o mesmo external_user_id test_user para ambas as chamadas create_sso_embed_url. No entanto, o comportamento é exatamente o mesmo: assim que o separador é recarregado com o painel de controlo da Pied Piper, apresenta os dados da Hooli.

Como posso garantir que o painel de controlo de cada marca apresenta apenas os dados dessa marca?

Colocar as práticas recomendadas em prática

Para aplicar a abordagem descrita na secção "A abordagem de uma perspetiva não incorporada", precisa de um único valor de atributo do utilizador que conceda acesso a TODOS os dados aos quais o parceiro deve ter acesso na aplicação. Pode fazê-lo usando um valor separado por vírgulas para o atributo 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"}
}

Para que esta sintaxe funcione, tem de se certificar de que o atributo do utilizador está definido como Filtro de strings (avançado):

Tenha em atenção que ainda pode alterar o conjunto de atributos do utilizador para um utilizador se algo mudar nos respetivos níveis de acesso aos dados. Por exemplo, se o parceiro assumir a propriedade de uma terceira marca, pode adicionar essa terceira marca à lista separada por vírgulas que especificou para o respetivo atributo do utilizador marca. Desta forma, quando o utilizador terminar e voltar a iniciar sessão, as alterações são aplicadas.

Filtrar os resultados do painel de controlo

OK, percebo que os atributos do utilizador têm de especificar todos os dados aos quais um utilizador pode aceder na aplicação. Mas, se especificar os atributos do utilizador desta forma, os dados de todas essas marcas são apresentados no meu painel de controlo. Como posso restringir os resultados de um painel de controlo específico a uma marca específica?

A forma correta de filtrar um painel de controlo específico é usar os filtros de painel de controlo normais! (Isto pode parecer óbvio agora, mas vimos algumas pessoas ficarem presas nos atributos do utilizador como a única forma de aplicar filtros no contexto de incorporação, talvez porque user_attributes é um parâmetro no URL de incorporação assinado e os filtros não são.)

Certifique-se de que exige um valor de filtro e usa uma das opções de controlo de seleção única, como a lista pendente:

Certifique-se de que o filtro é aplicado ao campo correto em todos os mosaicos necessários:

Agora, o seu parceiro pode selecionar entre esses dois (e apenas esses dois) valores, porque as opções disponíveis no menu pendente são limitadas pelos atributos do utilizador:

Pré-preencher os filtros do painel de controlo

OK. Agora, o painel de controlo pode ser filtrado por uma marca específica, mas gostaria que o valor do filtro já estivesse definido para uma marca específica quando o utilizador carregasse o painel de controlo dessa marca na minha app.

Mais uma vez, é útil pensar em como isto funciona no contexto não incorporado. Como envia a alguém um link para um painel de controlo que já tem um valor de filtro específico aplicado? Bem, pode ter reparado que, quando seleciona um valor de filtro, esse valor de filtro aparece no URL do painel de controlo:

Inclua essa parte do URL no seu target_url para a chamada 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 estiver a usar o SDK de incorporação, pode usar withFilters para especificar filtros iniciais a aplicar ao conteúdo incorporado:

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

Se estiver a usar o seu próprio script personalizado, certifique-se de que adiciona o filtro ao URL antes de o caminho ser codificado. Alguns valores podem já estar codificados na string de filtro (por exemplo, existe um espaço codificado como + em ?Brand=Pied+Piper), pelo que esses valores vão ser codificados duas vezes no URL final. Pode consultar o artigo "Painel de controlo incorporado do SO: definir filtro do painel de controlo como parte do URL?" Publicação da comunidade do Looker para alguma discussão destas nuances. Se continuar a ter problemas com a aplicação dos filtros, essa publicação da comunidade também é um bom local para adicionar perguntas.

Ocultar os filtros do painel de controlo

OK, percebi como definir os filtros iniciais nos meus painéis de controlo, mas também não quero que o parceiro altere os filtros do painel de controlo. O valor do filtro deve ser determinado APENAS pelo painel de controlo para o qual o parceiro navegou na minha app. Como posso ocultar os filtros do painel de controlo?

Pode usar temas para tal. Os temas são uma funcionalidade paga. Por isso, se ainda não tiver esta opção ativada na sua instância do Looker, deve contactar a equipa de vendas do Looker para a ativar.

Depois de ativar essa funcionalidade, navegue para a secção Controlos do painel de controlo da página Administração – Temas, onde pode desmarcar a opção Barra de filtros de visualização:

Em seguida, pode definir o tema como predefinição ou aplicar o tema no URL dos seus painéis de controlo específicos. Mais uma vez, isto seria incluído 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"}
}

Pode encontrar mais informações sobre como ocultar filtros do painel de controlo incorporado, incluindo alguns fragmentos de código do SDK de incorporação, neste tutorial do YouTube: Incorpore o Looker com filtros personalizados.

O resultado final deve ser idêntico à experiência do utilizador da pergunta original:

No entanto, agora, uma vez que os valores dos filtros estão codificados nos URLs de destino respetivos incorporados na app, o painel de controlo de cada marca mostra sempre o painel de controlo filtrado para a marca correta, mesmo quando alterna entre separadores.

Testar como outros utilizadores

Agora, a experiência do utilizador é muito semelhante à que imaginei originalmente. No entanto, no meu exemplo de utilização, o parceiro tem autorizações diferentes e outras definições do utilizador que os utilizadores individuais com external_user_id=pied_piper e external_user_id=hooli não têm, o que leva a diferentes opções disponíveis na IU e a uma experiência do utilizador ligeiramente diferente em geral. Quero permitir que um utilizador veja tudo exatamente como os utilizadores pied_piper e hooli o veem, como se a pessoa tivesse iniciado sessão como esses utilizadores. Como posso fazê-lo?

Se quiser que um utilizador possa testar como cada um dos utilizadores individuais da marca, pode criar uma função sudo semelhante na sua app que carregue os URLs incorporados para external_user_id=pied_piper quando o utilizador estiver a usar o sudo como utilizador da Pied Piper e os URLs incorporados para external_user_id=hooli quando o utilizador estiver a usar o sudo como utilizador da Hooli. Também pode usar o login_user ponto final da API para usar o sudo como o utilizador da marca com a API se a sua app usar a API.

No entanto, se pensar novamente no contexto não incorporado: na página Administração – Utilizadores, não pode usar o comando sudo simultaneamente como vários utilizadores não incorporados em vários separadores. A sessão sudo aplica-se a toda a janela do navegador, tal como todas as outras sessões de utilizador. Por conseguinte, deve conceber o sudo para sudo como apenas um utilizador de cada vez. Além disso, se pensar bem, este design é mais consistente com a imitação perfeita da experiência dos utilizadores que está a suar como. O utilizador pied_piper, por exemplo, só tem acesso ao painel de controlo Pied Piper e não tem acesso para abrir painéis de controlo adicionais em separadores adicionais. Por conseguinte, também não deve conseguir abrir diferentes painéis de controlo em diferentes separadores quando estiver a usar o comando sudo como este utilizador.

Conclusão

Esperamos que tenha considerado este guia útil e que se sinta bem preparado para avançar com a criação do seu conteúdo incorporado com sessão iniciada do Looker. Estamos constantemente a trabalhar para tornar o Looker a oferta de estatísticas de dados incorporadas mais flexível e robusta, e queremos receber o seu feedback! Se tiver dúvidas ou quiser saber mais, pode interagir connosco na comunidade do Looker e participar nos nossos eventos da comunidade.