Configurar e usar a resolução de entidades no BigQuery

Neste documento, mostramos como implementar a resolução de entidades para usuários finais (daqui em diante chamados de usuários finais) e provedores de identidade.

Os usuários finais podem usar este documento ao se conectar e usar o serviço de um provedor de identidade para fazer correspondência de registros. Por sua vez, os provedores de identidade podem usar este documento para definir e configurar serviços a serem compartilhados com usuários finais no Google Cloud Marketplace.

Fluxo de trabalho para usuários finais

As seções a seguir mostram aos usuários finais como configurar a resolução de entidades no BigQuery. Para uma representação visual da configuração completa, consulte a arquitetura para resolução de entidades.

Antes de começar

  1. Entre em contato e estabeleça um relacionamento com um provedor de identidade. O BigQuery é compatível com a resolução de entidades com o LiveRamp e a TransUnion.
  2. Adquira os seguintes itens do provedor de identidade:
    • Credenciais da conta de serviço
    • Assinatura da função remota
  3. Crie dois conjuntos de dados no seu projeto:
    • Conjunto de dados de entrada
    • Conjunto de dados de saída

Funções exigidas

Para receber as permissões necessárias para executar jobs de resolução de entidades, peça ao administrador para conceder a você os seguintes papéis do IAM:

  • Para que a conta de serviço do provedor de identidade leia o conjunto de dados de entrada e grave-o no conjunto de saída:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Traduzir ou resolver entidades

Para instruções específicas sobre provedores de identidade, consulte as seções a seguir.

LiveRamp

Pré-requisitos

Configuração

As etapas abaixo são necessárias ao usar a identidade incorporada do LiveRamp pela primeira vez. Depois que a configuração for concluída, apenas as tabelas de entrada e de metadados precisarão ser modificadas entre as execuções.

Criar uma tabela de entrada

Crie uma tabela no conjunto de dados de entrada. Preencha a tabela com RampIDs, domínios e tipos de destino. Para mais detalhes e exemplos, consulte Colunas e descrições da tabela de entrada.

Criar uma tabela de metadados

A tabela de metadados é usada para controlar a execução da identidade incorporada do LiveRamp no BigQuery. Crie uma tabela de metadados no conjunto de dados de entrada. Preencha a tabela de metadados com IDs do cliente, modos de execução, domínios e tipos de destino. Para detalhes e exemplos, consulte Colunas e descrições da tabela de metadados.

Compartilhar tabelas com o LiveRamp

Conceda à conta de serviço do LiveRamp Google Cloud acesso para ver e processar dados no conjunto de entrada. Para mais detalhes e exemplos, consulte Compartilhar tabelas e conjuntos de dados com o LiveRamp.

Executar um job de identidade embedded

Para executar um job de identidade embedded com o LiveRamp no BigQuery, faça o seguinte:

  1. Confirme que todos os RampIDs codificados no seu domínio estão na sua tabela de entrada.
  2. Confirme a precisão da tabela de metadados antes de executar o job.
  3. Entre em contato com LiveRampIdentitySupport@liveramp.com com uma solicitação de processo do job. Inclua os IDs do projeto, do conjunto de dados e da tabela (se aplicável) referentes às tabelas de entrada, de metadados e de saída. Para saber mais, consulte Notificar o LiveRamp para iniciar a transcodificação.

Os resultados geralmente são entregues ao conjunto de dados de saída em até três dias úteis.

Suporte ao LiveRamp

Em caso de problemas de suporte, entre em contato com o Suporte de identidade do LiveRamp.

Faturamento do LiveRamp

O LiveRamp processa o faturamento da resolução de entidades.

TransUnion

Pré-requisitos

  • Entre em contato com o suporte da TransUnion Cloud para executar um contrato e acessar o serviço. Forneça os detalhes do seu ID do projetoGoogle Cloud , tipos de dados de entrada, caso de uso e volume de dados.
  • O suporte na nuvem da TransUnion ativa o serviço para seu projeto Google Cloud e compartilha um guia de implementação detalhado que inclui dados de saída disponíveis.

Configuração

As etapas a seguir são necessárias ao usar o serviço de resolução e enriquecimento de identidade TruAudience da TransUnion no ambiente do BigQuery.

Criar uma conexão externa

Crie uma conexão com uma fonte de dados externa do tipo Modelos remotos da Vertex AI, funções remotas e BigLake (recurso de nuvem). Você vai usar essa conexão para acionar o serviço de resolução de identidade hospedado na conta da TransUnion Google Cloud pela sua conta do Google Cloud .

Copie o ID da conexão e o ID da conta de serviço e compartilhe esses identificadores com a equipe de entrega ao cliente da TransUnion.

Criar uma função remota

Crie uma função remota que interaja com o endpoint do orquestrador de serviços hospedado no projeto Google Cloud da TransUnion para transmitir os metadados necessários (incluindo mapeamentos de esquema) ao serviço da TransUnion. Use o ID da conexão externa que você criou e o endpoint da função do Cloud hospedada pela TransUnion compartilhado pela equipe de entrega ao cliente da TransUnion.

Criar uma tabela de entrada

Crie uma tabela no conjunto de dados de entrada. A TransUnion aceita nome, endereço postal, e-mail, telefone, data de nascimento, endereço IPv4 e IDs de dispositivo como entradas. Siga as diretrizes de formatação no guia de implementação que a TransUnion compartilhou com você.

Criar uma tabela de metadados

Crie uma tabela de metadados que armazene a configuração exigida pelo serviço de resolução de identidade para processar dados, incluindo mapeamentos de esquema. Para mais detalhes e exemplos, consulte o guia de implementação que a TransUnion compartilhou com você.

Criar uma tabela de status do job

Crie uma tabela que vai receber atualizações sobre o processamento de um lote de entrada. É possível consultar essa tabela para acionar outros processos downstream no seu pipeline. Os status possíveis do job são: RUNNING, COMPLETED ou ERROR.

Criar a invocação de serviço

Use o procedimento a seguir para chamar o serviço de resolução de identidade da TransUnion depois de coletar todos os metadados, empacotá-los e transmiti-los ao endpoint da função do Cloud de invocação hospedado pela TransUnion.

-- create service invocation procedure
CREATE OR REPLACE
  PROCEDURE
    `<project_id>.<dataset_id>.TransUnion_get_identities`(metadata_table STRING, config_id STRING)
      begin
        declare sql_query STRING;

declare json_result STRING;
declare base64_result STRING;

SET sql_query =
  '''select to_json_string(array_agg(struct(config_id,key,value))) from `''' || metadata_table
  || '''` where  config_id="''' || config_id || '''" ''';

EXECUTE immediate sql_query INTO json_result;

SET base64_result = (SELECT to_base64(CAST(json_result AS bytes)));

SELECT `<project_id>.<dataset_id>.remote_call_TransUnion_er`(base64_result);

END;
Criar a tabela de saída correspondente

Execute o script SQL a seguir para criar a tabela de saída correspondente. Essa é a saída padrão do aplicativo, que inclui flags de correspondência, pontuações, IDs individuais persistentes e IDs domésticos.

-- create output table
CREATE TABLE `<project_id>.<dataset_id>.TransUnion_identity_output`(
  batchid STRING,
  uniqueid STRING,
  ekey STRING,
  hhid STRING,
  collaborationid STRING,
  firstnamematch STRING,
  lastnamematch STRING,
  addressmatches STRING,
  addresslinkagescores STRING,
  phonematches STRING,
  phonelinkagescores STRING,
  emailmatches STRING,
  emaillinkagescores STRING,
  dobmatches STRING,
  doblinkagescore STRING,
  ipmatches STRING,
  iplinkagescore STRING,
  devicematches STRING,
  devicelinkagescore STRING,
  lastprocessed STRING);
Configurar metadados

Siga o guia de implementação que a TransUnion compartilhou com você para mapear seu esquema de entrada para o esquema do aplicativo. Esses metadados também configuram a geração de IDs de colaboração, que são identificadores compartilháveis não persistentes que podem ser usados em data clean rooms.

Conceder acesso de leitura e gravação

Receba o ID da conta de serviço da conexão do Apache Spark da equipe de entrega ao cliente da TransUnion e conceda a ela acesso de leitura e gravação ao conjunto de dados que contém as tabelas de entrada e saída. Recomendamos fornecer o ID da conta de serviço com um papel de editor de dados do BigQuery no conjunto de dados.

Invocar o aplicativo

É possível invocar o aplicativo no seu ambiente executando o script a seguir.

call `<project_id>.<dataset_id>.TransUnion_get_identities`("<project_id>.<dataset_id>.TransUnion_er_metadata","1");
-- using metadata table, and 1 = config_id for the batch run

Suporte

Para problemas técnicos, entre em contato com o Suporte do Cloud da TransUnion.

Faturamento e uso

A TransUnion rastreia o uso do aplicativo e o utiliza para fins de faturamento. Os clientes ativos podem entrar em contato com o representante de entrega da TransUnion para mais informações.

Fluxo de trabalho para provedores de identidade

As seções a seguir mostram aos provedores de identidade como configurar a resolução de entidades no BigQuery. Para uma representação visual da configuração completa, consulte a arquitetura da resolução de entidades.

Antes de começar

  1. Crie um job do Cloud Run ou uma função do Cloud Run para integração com a função remota. As duas opções são adequadas para esse propósito.

  2. Observe o nome da conta de serviço associada ao Cloud Run ou à função do Cloud Run:

    1. No console Google Cloud , acesse a página Cloud Functions.

      Acesse o Cloud Functions

    2. Clique no nome da função e, em seguida, clique na guia Detalhes.

    3. No painel Informações gerais, localize e anote o nome da conta de serviço para a função remota.

  3. Crie uma função remota.

  4. Colete os principais do usuário final.

Funções exigidas

Para receber as permissões necessárias para executar jobs de resolução de entidades, peça ao administrador para conceder a você os seguintes papéis do IAM:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Compartilhar função remota de resolução de entidades

Modifique e compartilhe o código de interface remota a seguir com o usuário final. O usuário final precisa desse código para iniciar o job de resolução de entidades.

`PARTNER_PROJECT_ID.DATASET_ID`.match`(LIST_OF_PARAMETERS)

Substitua LIST_OF_PARAMETERS pela lista de parâmetros que são transmitidos à função remota.

Opcional: fornecer metadados do job

Como alternativa, forneça metadados do job usando uma função remota separada ou gravando uma nova tabela de status no conjunto de dados de saída do usuário. Exemplos de metadados incluem status e métricas do job.

Faturamento de provedores de identidade

Para simplificar o faturamento e a integração do cliente, recomendamos que você integre seu serviço de resolução de entidades ao Google Cloud Marketplace. Isso permite configurar um modelo de preços com base no uso do job de resolução de entidades, e o Google processa o faturamento para você. Para mais informações, consulte Como oferecer produtos de software como serviço (SaaS).