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

Com a resolução de entidades no BigQuery, é possível corresponder, remover duplicidades e aumentar registros em conjuntos de dados sem mover os dados subjacentes. Como usuário final, você pode conectar seus conjuntos de dados do BigQuery a um provedor de identidade, como LiveRamp ou TransUnion, e chamar uma função remota para resolver identidades no local. Como um provedor de identidade, você pode configurar endpoints de função remota e publicar seus serviços de resolução de entidades no Google Cloud Marketplace.

Configurar a resolução de entidades para usuários finais

Para resolver entidades como usuário final, prepare conjuntos de dados de entrada e saída no BigQuery, conceda acesso ao conjunto de dados ao provedor de identidade e invoque o serviço de correspondência dele. Para mais informações sobre a arquitetura, consulte Arquitetura de resolução de entidades.

Antes de começar

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

Funções exigidas

Para garantir que a conta de serviço do provedor de identidade tenha as permissões necessárias para ler o conjunto de dados de entrada e gravar no conjunto de dados de saída, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço do provedor de identidade:

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

O administrador também pode conceder à conta de serviço do provedor de identidade as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Resolver entidades com um provedor de identidade

Depois de criar os conjuntos de dados e conceder os papéis necessários, é possível configurar as tabelas e executar jobs de correspondência com o provedor de identidade escolhido. A tabela a seguir resume o método de integração e as tabelas necessárias para cada provedor de identidade compatível:

Provedor de identidade Método de integração Tabelas obrigatórias no conjunto de dados Invocação de job
LiveRamp Identidade incorporada do LiveRamp Tabela de entrada com RampIDs, tabela de metadados Enviar solicitação por e-mail ao suporte do LiveRamp
TransUnion Função remota do TruAudience em uma conexão externa do BigQuery Tabela de entrada com atributos de entidade, tabela de metadados, tabela de status do job e tabela de saída de correspondência Chamada de procedimento armazenado em SQL usando CALL

Selecione um provedor de identidade para conferir instruções específicas de configuração e execução de jobs:

LiveRamp

Pré-requisitos do LiveRamp

Antes de configurar a resolução de entidades do LiveRamp no BigQuery, conclua os seguintes pré-requisitos:

Configurar a resolução de entidade do LiveRamp

Ao usar a identidade incorporada do LiveRamp pela primeira vez, siga as etapas de configuração abaixo. Para execuções subsequentes, basta atualizar as tabelas de entrada e de metadados.

Criar uma tabela de entrada da LiveRamp

Crie uma tabela no conjunto de dados de entrada e preencha-a com as seguintes colunas:

  • RampIDs
  • Domínios de destino
  • Tipos de segmentação

Para mais informações sobre o esquema da tabela de entrada, consulte Colunas e descrições da tabela de entrada.

Criar uma tabela de metadados da LiveRamp

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 as seguintes colunas de configuração:

  • IDs de cliente
  • Modos de execução
  • Domínios de destino
  • Tipos de segmentação

Para mais informações sobre o esquema da tabela de metadados, consulte Colunas e descrições da tabela de metadados.

Conceder acesso ao conjunto de dados à LiveRamp

Depois de criar as tabelas necessárias, conceda ao LiveRamp acesso para ver e processar dados no conjunto de entrada. Conceda acesso ao conjunto de dados à conta de serviço do LiveRamp Google Cloud . Para mais informações sobre o compartilhamento de conjuntos de dados, consulte Compartilhar tabelas e conjuntos de dados com o LiveRamp.

Executar um job de resolução de entidade do LiveRamp

Depois de configurar as tabelas e conceder acesso ao conjunto de dados, execute um job de resolução de entidades com o LiveRamp no BigQuery:

  1. Na tabela de entrada, confirme se todos os RampIDs do seu domínio estão presentes.
  2. Antes de executar o job, confirme se a configuração da tabela de metadados está correta.
  3. Para enviar uma solicitação de processamento de job, envie um e-mail para LiveRampIdentitySupport@liveramp.com. Inclua na solicitação os ID do projeto, do conjunto de dados e de todas as tabelas aplicáveis referentes às tabelas de entrada, de metadados e de saída.

Normalmente, a LiveRamp entrega os resultados da correspondência ao conjunto de dados de saída em até três dias úteis.

Receber suporte e informações de faturamento do LiveRamp

O LiveRamp gerencia o suporte técnico e o faturamento da identidade incorporada no BigQuery:

  • Suporte técnico: entre em contato com o Suporte de identidade do LiveRamp para receber ajuda com a configuração ou a execução de jobs.
  • Faturamento: o LiveRamp cobra diretamente o uso da resolução de entidades.

TransUnion

Pré-requisitos da TransUnion

Antes de configurar a resolução de entidades da TransUnion no BigQuery, envie um e-mail para TransUnion Cloud Support (em inglês) e assine um contrato de acesso ao serviço. Na solicitação, forneça as seguintes informações:

  • O ID do projeto do Google Cloud .
  • Tipos de dados de entrada
  • Caso de uso pretendido
  • Volume de dados estimado

Depois que o suporte do TransUnion Cloud aprovar sua solicitação, ele vai ativar o serviço para seu projeto Google Cloud e compartilhar um guia de implementação que inclui os esquemas de saída disponíveis.

Configurar a resolução de entidades da TransUnion

Ao usar o serviço de resolução e enriquecimento de identidade TruAudience da TransUnion no BigQuery pela primeira vez, siga estas etapas de configuração.

Criar uma conexão externa

Para conectar sua conta do Google Cloud ao serviço de resolução de identidade hospedado na conta do Google Cloud da TransUnion, crie uma conexão a recursos do Cloud. Ao configurar a conexão, selecione Modelos remotos da Vertex AI, funções remotas e BigLake (recurso do Cloud) como o tipo de conexão.

Depois de criar a conexão, 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

Para transmitir mapeamentos de esquema e metadados de configuração ao endpoint do orquestrador de serviços da TransUnion, crie uma função remota. Ao criar a função remota, especifique o ID da conexão externa e o URL do endpoint da função do Cloud Run que a equipe de entrega ao cliente da TransUnion compartilhou com você.

Criar uma tabela de entrada da TransUnion

Crie uma tabela de entrada no conjunto de dados de entrada. A TransUnion aceita os seguintes atributos de entidade como colunas de entrada:

  • Nome
  • Endereço postal
  • Endereço de e-mail
  • Número de telefone
  • Data de nascimento
  • Endereço IPv4
  • ID do dispositivo

Siga as diretrizes de esquema e formatação no guia de implementação que a TransUnion compartilhou com você. Se você mapear cada tabela de entrada para um parâmetro config_id distinto na tabela de metadados, poderá usar várias tabelas de entrada.

Criar uma tabela de metadados da TransUnion

Para armazenar os mapeamentos de esquema e a configuração exigidos pelo serviço de resolução de identidade, crie uma tabela de metadados no conjunto de dados de entrada. Para mais informações sobre o esquema de metadados, consulte o guia de implementação que a TransUnion compartilhou com você.

Criar uma tabela de status do job

Para receber atualizações sobre o processamento em lote, crie uma tabela de status de job no seu conjunto de dados. Para monitorar jobs e acionar processos downstream no seu pipeline, consulte esta tabela de status do job. A tabela registra os seguintes status:

  • RUNNING: o serviço de resolução de identidade está processando o lote.
  • COMPLETED: o serviço terminou de processar o lote e gravou os resultados na tabela de saída.
  • ERROR: o serviço encontrou um erro ao processar o lote.
Criar o procedimento de invocação de serviço

O procedimento armazenado TransUnion_get_identities empacota os metadados de configuração e invoca o endpoint da função do Cloud Run da TransUnion. Para criar esse procedimento armazenado, execute a seguinte instrução SQL:

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

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • DATASET_ID: o ID do conjunto de dados em que você cria o procedimento e a função remota.
Criar a tabela de saída correspondente

A tabela de saída correspondente armazena os resultados da resolução de entidades da TransUnion, incluindo flags de correspondência, pontuações de vinculação, IDs individuais persistentes e IDs de domicílio. Para criar a tabela de saída correspondente, execute a seguinte instrução SQL:

-- 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);

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • DATASET_ID: o ID do conjunto de dados em que você cria a tabela de saída correspondente.
Configurar metadados de mapeamento de esquema

Para mapear seu esquema de entrada com o esquema de inscrição da TransUnion, siga as instruções no guia de implementação compartilhado com você pela TransUnion. Esses metadados também configuram como o serviço gera IDs de colaboração, que são identificadores compartilháveis e não persistentes que podem ser usados em data clean rooms.

Conceder acesso ao conjunto de dados à TransUnion

Depois de criar as tabelas e o procedimento armazenado necessários, conceda à TransUnion acesso para ler seus dados de entrada e gravar os resultados da correspondência. Receba o ID da conta de serviço de conexão do Apache Spark da equipe de entrega ao cliente da TransUnion. Em seguida, conceda a essa conta de serviço o papel de editor de dados do BigQuery (roles/bigquery.dataEditor) no conjunto de dados que contém as tabelas de entrada e saída.

Executar um job de resolução de entidade da TransUnion

Depois de configurar as tabelas e conceder acesso ao conjunto de dados, você pode iniciar uma execução em lote da resolução de entidades. Para invocar o serviço de resolução de entidades, chame o procedimento armazenado TransUnion_get_identities:

CALL `PROJECT_ID.DATASET_ID.TransUnion_get_identities`(
  "PROJECT_ID.DATASET_ID.TransUnion_er_metadata",
  "CONFIG_ID");

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • DATASET_ID: o ID do conjunto de dados que contém a tabela de metadados e o procedimento armazenado.
  • CONFIG_ID: o ID da configuração para a execução em lote, como "1".

Receber suporte e informações de faturamento da TransUnion

Para receber ajuda com problemas técnicos ou dúvidas sobre faturamento relacionadas à resolução e ao enriquecimento de identidade da TruAudience no BigQuery, entre em contato diretamente com a TransUnion:

  • Suporte técnico: entre em contato com o suporte da TransUnion Cloud para receber ajuda com configuração, mapeamento de esquema ou solução de problemas.
  • Faturamento: a TransUnion rastreia o uso do serviço para fins de faturamento. Entre em contato com seu representante de entrega da TransUnion para saber detalhes sobre a conta e os preços.

Configurar a resolução de entidades para provedores de identidade

Como provedor de identidade, você pode oferecer seu serviço de resolução de entidades aos usuários finais do BigQuery. Essa arquitetura ajuda a proteger sua propriedade intelectual porque não expõe seu gráfico de identidade proprietário nem a lógica de correspondência.

Para configurar o serviço, implante um endpoint de orquestrador, crie uma função remota do BigQuery, conceda os papéis necessários e compartilhe a assinatura da função remota com os usuários finais. Para mais informações sobre a arquitetura, consulte Arquitetura de resolução de entidades.

Antes de começar

Antes de configurar o serviço de resolução de entidades no BigQuery, verifique se você tem o seguinte:

  • Um conjunto de dados de gráfico de identidade e uma lógica de correspondência implantados no seu projetoGoogle Cloud ou em um banco de dados externo.
  • Identificadores principais do usuário final, como endereços de e-mail de usuário, conta de serviço ou Grupo do Google, que você recebeu dos usuários finais.

Funções exigidas

Para garantir que a conta de serviço do provedor de identidade tenha as permissões necessárias para executar jobs de resolução de entidades, peça ao administrador para conceder os seguintes papéis do IAM à conta de serviço do provedor de identidade:

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

O administrador também pode conceder à conta de serviço do provedor de identidade as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

Configurar o endpoint da função remota

Para processar solicitações de resolução de entidades de usuários finais, implante um endpoint de orquestrador e conecte-o a uma função remota do BigQuery:

  1. Para processar solicitações correspondentes da sua função remota, crie um job do Cloud Run ou uma função do Cloud Run. Você pode usar qualquer uma das opções para seu endpoint.

  2. Para encontrar o endereço de e-mail da conta de serviço associada ao seu job ou função do Cloud Run, siga estas etapas:

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

      Acesse o Cloud Functions

    2. Para abrir os detalhes da função, clique no nome dela e depois na guia Detalhes.

    3. No painel Informações gerais, localize e registre o endereço de e-mail da conta de serviço para a função remota.

  3. No conjunto de dados do plano de controle, crie uma função remota que se conecte ao job do Cloud Run ou ao endpoint da função do Cloud Run.

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

Depois de criar a função remota e conceder os papéis necessários aos usuários finais, compartilhe a seguinte assinatura de função remota com eles. Os usuários finais chamam essa função remota para iniciar um job de resolução de entidades.

`PARTNER_PROJECT_ID.DATASET_ID.match`(LIST_OF_PARAMETERS)

Substitua:

  • PARTNER_PROJECT_ID: o ID do projeto Google Cloud do provedor de identidade.
  • DATASET_ID: o ID do conjunto de dados que contém a função remota.
  • LIST_OF_PARAMETERS: a lista de parâmetros a serem transmitidos para a função remota.

Opcional: fornecer metadados do job de resolução de entidades

Para fornecer metadados do job aos usuários finais, exponha uma função remota separada ou grave uma tabela de status do job no conjunto de dados de saída do usuário final. Por exemplo, você pode informar status de execução como RUNNING, COMPLETED ou ERROR, além de métricas de processamento.

Integrar com o Cloud Marketplace para faturamento

Para gerenciar o faturamento e a integração de clientes pelo Google, integre seu serviço de resolução de entidades ao Cloud Marketplace. Essa integração permite configurar um modelo de preços com base no uso do job de resolução de entidades, e o Google processa o faturamento do seu serviço. Para mais informações, consulte Como oferecer produtos de software como serviço (SaaS).

A seguir