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

A resolução de entidades no BigQuery permite que você faça correspondência, elimine duplicações e aumente registros em conjuntos de dados sem mover os dados subjacentes. Como usuário final, é possível 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 provedor de identidade, é possível 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 invocar o serviço de correspondência. 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. Consiga 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 seu projeto do 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 de 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 Solicitação por e-mail para o suporte do LiveRamp
TransUnion Função remota do TruAudience na conexão externa do BigQuery Tabela de entrada com atributos de entidade, tabela de metadados, tabela de status do job, tabela de saída correspondente Chamada de procedimento armazenado em SQL usando CALL

Selecione um provedor de identidade para ver as 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 entidades do LiveRamp

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

Criar uma tabela de entrada do 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 para a LiveRamp

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

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

Depois de configurar as tabelas e conceder acesso ao conjunto de dados, execute um job de resolução de entidade 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. Na solicitação, inclua o ID do projeto, o ID do conjunto de dados e todos os IDs de tabela aplicáveis para a tabela de entrada, a tabela de metadados e o conjunto de dados de saída.

A LiveRamp geralmente entrega os resultados correspondentes ao conjunto de dados de saída em até três dias úteis.

Receber suporte e informações de faturamento da 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 do job.
  • Faturamento: o LiveRamp cobra diretamente pelo 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 o suporte do TransUnion Cloud para assinar 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 do 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 da TransUnion TruAudience no BigQuery pela primeira vez, conclua as seguintes 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 da TransUnion Google Cloud , crie uma conexão a recursos do Cloud. Ao configurar a conexão, selecione Modelos remotos da Vertex AI, funções remotas, BigLake e Spanner (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 para o 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 que o serviço de resolução de identidade exige, 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 de processamento em lote, crie uma tabela de status de job no seu conjunto de dados. Para monitorar jobs e acionar processos downstream no pipeline, consulte essa tabela de status de jobs. 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 de correspondência 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 família. 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 para o esquema do aplicativo da TransUnion, siga as instruções no guia de implementação que a TransUnion compartilhou com você. 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 resultados correspondentes. Consiga o ID da conta de serviço de conexão do Apache Spark com a 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 entidades da TransUnion

Depois de configurar as tabelas e conceder acesso ao conjunto de dados, é possível iniciar uma execução em lote de 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 de configuração da execução em lote, como "1".

Receber suporte e informações de faturamento da TransUnion

Para receber assistência 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 do TransUnion Cloud para receber ajuda com a configuração, o mapeamento de esquemas ou a 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 mais 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 você não expõe seu gráfico de identidade reservado ou sua 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 projeto doGoogle Cloud ou em um banco de dados externo.
  • Identificadores principais de usuários finais, como endereços de e-mail de usuários, conta de serviço ou Grupos 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 de outros papéis predefinidos.

Configurar o endpoint da função remota

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

  1. Para processar solicitações atendidas da 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 job ou à função do Cloud Run, siga estas etapas:

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

      Acessar o Cloud Run

    2. Clique no nome da função ou do job e, em seguida, clique na guia Segurança.

    3. No campo Conta de serviço, 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 do Google Cloud 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 de jobs aos usuários finais, exponha uma função remota separada ou grave uma tabela de status de jobs no conjunto de dados de saída do usuário final. Por exemplo, é possível 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 do cliente 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, enquanto 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