Configura y usa la resolución de entidades en BigQuery

La resolución de entidades en BigQuery te permite correlacionar, quitar duplicados y aumentar registros en conjuntos de datos sin mover tus datos subyacentes. Como usuario final, puedes conectar tus conjuntos de datos de BigQuery a un proveedor de identidad, como LiveRamp o TransUnion, y llamar a una función remota para resolver identidades en el lugar. Como proveedor de identidad, puedes configurar extremos de funciones remotas y publicar tus servicios de resolución de entidades en Google Cloud Marketplace.

Configura la resolución de entidades para los usuarios finales

Para resolver entidades como usuario final, debes preparar conjuntos de datos de entrada y salida en BigQuery, otorgar acceso al conjunto de datos a tu proveedor de identidad y, luego, invocar su servicio de correlación. Para obtener más información sobre la arquitectura, consulta Arquitectura de resolución de entidades.

Antes de comenzar

  1. Comunícate con un proveedor de identidad. BigQuery admite la resolución de entidades con LiveRamp y TransUnion.
  2. Obtén los siguientes elementos del proveedor de identidad:
    • Credenciales de cuenta de servicio
    • Firma de la función remota
  3. Crea los siguientes conjuntos de datos en tu proyecto Google Cloud :
    • Conjunto de datos de entrada
    • Conjunto de datos de salida

Roles obligatorios

Para garantizar que la cuenta de servicio del proveedor de identidad tenga los permisos necesarios para leer el conjunto de datos de entrada y escribir en el conjunto de datos de salida, pídele a tu administrador que le otorgue los siguientes roles de IAM a la cuenta de servicio del proveedor de identidad:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a la cuenta de servicio del proveedor de identidad los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Resuelve entidades con un proveedor de identidad

Después de crear tus conjuntos de datos y otorgar los roles necesarios, puedes configurar tus tablas y ejecutar trabajos de correlación con el proveedor de identidad que elijas. En la siguiente tabla, se resumen el método de integración y las tablas requeridas para cada proveedor de identidad compatible:

Proveedor de identidad Método de integración Tablas obligatorias en tu conjunto de datos Invocación de trabajo
LiveRamp Identidad incorporada de LiveRamp Tabla de entrada con RampIDs, tabla de metadatos Solicitud por correo electrónico al equipo de asistencia de LiveRamp
TransUnion Función remota de TruAudience a través de una conexión externa de BigQuery Tabla de entrada con atributos de entidades, tabla de metadatos, tabla de estado del trabajo y tabla de resultados de la correlación Llamada a un procedimiento almacenado de SQL con CALL

Selecciona un proveedor de identidad para ver instrucciones específicas de configuración y ejecución de trabajos:

LiveRamp

Requisitos previos de LiveRamp

Antes de configurar la resolución de entidades de LiveRamp en BigQuery, completa los siguientes requisitos previos:

Configura la resolución de entidades de LiveRamp

Cuando uses la identidad incorporada de LiveRamp por primera vez, completa los siguientes pasos de configuración. Para las ejecuciones posteriores, solo debes actualizar la tabla de entrada y la tabla de metadatos.

Crea una tabla de entrada de LiveRamp

Crea una tabla en tu conjunto de datos de entrada y complétala con las siguientes columnas:

  • RampIDs
  • Dominios objetivo
  • Tipos de objetivos

Para obtener más información sobre el esquema de la tabla de entrada, consulta Columnas y descripciones de la tabla de entrada.

Crea una tabla de metadatos de LiveRamp

Para controlar la ejecución de la identidad incorporada de LiveRamp en BigQuery, crea una tabla de metadatos en tu conjunto de datos de entrada. Propaga la tabla de metadatos con las siguientes columnas de configuración:

  • ID de cliente
  • Modos de ejecución
  • Dominios objetivo
  • Tipos de objetivos

Para obtener más información sobre el esquema de la tabla de metadatos, consulta Columnas y descripciones de la tabla de metadatos.

Otorga acceso al conjunto de datos a LiveRamp

Después de crear las tablas requeridas, otorga acceso a LiveRamp para ver y procesar los datos en tu conjunto de datos de entrada. Otorga acceso al conjunto de datos a la cuenta de servicio de LiveRampGoogle Cloud . Para obtener más información sobre cómo compartir conjuntos de datos, consulta Cómo compartir tablas y conjuntos de datos con LiveRamp.

Ejecuta un trabajo de resolución de entidades de LiveRamp

Después de configurar tus tablas y otorgar acceso al conjunto de datos, ejecuta un trabajo de resolución de entidades con LiveRamp en BigQuery:

  1. En tu tabla de entrada, confirma que estén presentes todos los RampIDs de tu dominio.
  2. Antes de ejecutar el trabajo, confirma que la configuración de la tabla de metadatos sea precisa.
  3. Para enviar una solicitud de procesamiento de trabajos, envía un correo electrónico a LiveRampIdentitySupport@liveramp.com. En tu solicitud, incluye el ID del proyecto, el ID del conjunto de datos y los IDs de tabla aplicables para tu tabla de entrada, la tabla de metadatos y el conjunto de datos de salida.

Por lo general, LiveRamp entrega los resultados de la correlación a tu conjunto de datos de salida en un plazo de tres días hábiles.

Obtén asistencia y datos de facturación de LiveRamp

LiveRamp administra la asistencia técnica y la facturación de la identidad incorporada en BigQuery:

TransUnion

Requisitos previos de TransUnion

Antes de configurar la resolución de entidades de TransUnion en BigQuery, envía un correo electrónico al equipo de asistencia de TransUnion Cloud para firmar un acuerdo de acceso al servicio. En tu solicitud, proporciona la siguiente información:

  • El ID de tu proyecto de Google Cloud
  • Tipos de datos de entrada
  • Caso de uso previsto
  • Volumen de datos estimado

Después de que el equipo de asistencia de TransUnion Cloud apruebe tu solicitud, habilitará el servicio para tu proyecto Google Cloud y compartirá una guía de implementación que incluye los esquemas de salida disponibles.

Configura la resolución de entidades de TransUnion

Cuando uses el servicio de resolución y enriquecimiento de identidades de TransUnion TruAudience en BigQuery por primera vez, completa los siguientes pasos de configuración.

Crea una conexión externa

Para conectar tu cuenta de Google Cloud al servicio de resolución de identidades alojado en la cuenta de Google Cloud de TransUnion, crea una conexión a recursos de Cloud. Cuando configures la conexión, selecciona Modelos remotos de Vertex AI, funciones remotas y BigLake (Cloud Resource) como el tipo de conexión.

Después de crear la conexión, copia el ID de conexión y el ID de la cuenta de servicio, y, luego, comparte estos identificadores con el equipo de entrega al cliente de TransUnion.

Crea una función remota

Para pasar asignaciones de esquemas y metadatos de configuración al extremo del orquestador del servicio de TransUnion, crea una función remota. Cuando crees la función remota, especifica el ID de conexión de tu conexión externa y la URL del extremo de la función de Cloud Run que el equipo de entrega al cliente de TransUnion compartió contigo.

Crea una tabla de entrada de TransUnion

Crea una tabla de entrada en tu conjunto de datos de entrada. TransUnion admite los siguientes atributos de entidades como columnas de entrada:

  • Nombre
  • Dirección postal
  • Dirección de correo electrónico
  • Número de teléfono
  • Fecha de nacimiento
  • Dirección IPv4
  • ID de dispositivo

Sigue los lineamientos de esquema y formato que se indican en la guía de implementación que TransUnion compartió contigo. Si asignas cada tabla de entrada a un parámetro config_id distinto en tu tabla de metadatos, puedes usar varias tablas de entrada.

Crea una tabla de metadatos de TransUnion

Para almacenar las asignaciones y la configuración del esquema que requiere el servicio de resolución de identidades, crea una tabla de metadatos en tu conjunto de datos de entrada. Para obtener más información sobre el esquema de metadatos, consulta la guía de implementación que TransUnion compartió contigo.

Crea una tabla de estado del trabajo

Para recibir actualizaciones sobre el procesamiento por lotes, crea una tabla de estado del trabajo en tu conjunto de datos. Para supervisar los trabajos y activar procesos posteriores en tu canalización, consulta esta tabla de estado de los trabajos. En la tabla, se registran los siguientes estados:

  • RUNNING: El servicio de resolución de identidades está procesando el lote.
  • COMPLETED: El servicio terminó de procesar el lote y escribió los resultados en la tabla de salida.
  • ERROR: El servicio encontró un error mientras procesaba el lote.
Crea el procedimiento de invocación del servicio

El procedimiento almacenado TransUnion_get_identities empaqueta los metadatos de configuración y, luego, invoca el extremo de la función de Cloud Run de TransUnion. Para crear este procedimiento almacenado, ejecuta la siguiente instrucción de 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;

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • DATASET_ID: Es el ID del conjunto de datos en el que creas el procedimiento y la función remota.
Crea la tabla de resultados de coincidencias

La tabla de salida de la correlación almacena los resultados de la resolución de entidades de TransUnion, incluidas las marcas de correlación, las puntuaciones de vinculación, los IDs individuales persistentes y los IDs de grupo familiar. Para crear la tabla de salida de coincidencias, ejecuta la siguiente instrucción en 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);

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • DATASET_ID: Es el ID del conjunto de datos en el que creas la tabla de salida coincidente.
Configura los metadatos de asignación de esquemas

Para asignar tu esquema de entrada al esquema de la aplicación de TransUnion, sigue las instrucciones de la guía de implementación que TransUnion compartió contigo. Estos metadatos también configuran cómo el servicio genera IDs de colaboración, que son identificadores no persistentes y compartibles que puedes usar en las salas limpias de datos.

Otorga acceso al conjunto de datos a TransUnion

Después de crear las tablas y el procedimiento almacenado necesarios, otorga acceso a TransUnion para leer tus datos de entrada y escribir los resultados de la correlación. Obtén el ID de la cuenta de servicio de conexión de Apache Spark del equipo de entrega al cliente de TransUnion. Luego, otorga a esa cuenta de servicio el rol de Editor de datos de BigQuery (roles/bigquery.dataEditor) en el conjunto de datos que contiene tus tablas de entrada y salida.

Ejecuta un trabajo de resolución de entidades de TransUnion

Después de configurar tus tablas y otorgar acceso al conjunto de datos, puedes iniciar una ejecución por lotes de resolución de entidades. Para invocar el servicio de resolución de entidades, llama al procedimiento almacenado TransUnion_get_identities:

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

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del proyecto de Google Cloud .
  • DATASET_ID: Es el ID del conjunto de datos que contiene tu tabla de metadatos y el procedimiento almacenado.
  • CONFIG_ID: Es el ID de configuración de la ejecución por lotes, como "1".

Obtén asistencia y datos de facturación de TransUnion

Si necesitas ayuda con problemas técnicos o consultas de facturación relacionadas con la resolución y el enriquecimiento de identidades de TruAudience en BigQuery, comunícate directamente con TransUnion:

  • Asistencia técnica: Comunícate con el equipo de asistencia de TransUnion Cloud para obtener ayuda con la configuración, la asignación de esquemas o la solución de problemas.
  • Facturación: TransUnion hace un seguimiento del uso del servicio para fines de facturación. Comunícate con tu representante de TransUnion para obtener detalles sobre la cuenta y los precios.

Configura la resolución de entidades para los proveedores de identidad

Como proveedor de identidad, puedes ofrecer tu servicio de resolución de entidades a los usuarios finales de BigQuery. Esta arquitectura ayuda a proteger tu propiedad intelectual, ya que no expones tu gráfico de identidad propietario ni tu lógica de correlación.

Para configurar tu servicio, implementa un extremo del orquestador, crea una función remota de BigQuery, otorga los roles necesarios y comparte la firma de la función remota con tus usuarios finales. Para obtener más información sobre la arquitectura, consulta Arquitectura de resolución de entidades.

Antes de comenzar

Antes de configurar tu servicio de resolución de entidades en BigQuery, asegúrate de tener lo siguiente:

  • Un conjunto de datos del gráfico de identidad y una lógica de coincidencia implementados en tu proyectoGoogle Cloud o en una base de datos externa
  • Identificadores de principales de usuarios finales, como direcciones de correo electrónico de usuarios, cuentas de servicio o Grupos de Google, que obtuviste de tus usuarios finales

Roles obligatorios

Para garantizar que la cuenta de servicio del proveedor de identidad tenga los permisos necesarios para ejecutar trabajos de resolución de entidades, pídele a tu administrador que le otorgue los siguientes roles de IAM a la cuenta de servicio del proveedor de identidad:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Es posible que tu administrador también pueda otorgar a la cuenta de servicio del proveedor de identidad los permisos necesarios a través de roles personalizados o de otros roles predefinidos.

Configura el extremo de la función remota

Para procesar las solicitudes de resolución de entidades de los usuarios finales, implementa un extremo del orquestador y conéctalo a una función remota de BigQuery:

  1. Para procesar las solicitudes de coincidencia de tu función remota, crea un trabajo de Cloud Run o una función de Cloud Run. Puedes usar cualquiera de las opciones para tu extremo.

  2. Para encontrar la dirección de correo electrónico de la cuenta de servicio asociada con tu trabajo o función de Cloud Run, completa estos pasos:

    1. En la Google Cloud consola, ve a la página de Cloud Functions.

      Ir a Cloud Functions

    2. Para abrir los detalles de la función, haz clic en su nombre y, luego, en la pestaña Detalles.

    3. En el panel General Information, busca y registra la dirección de correo electrónico de la cuenta de servicio de la función remota.

  3. En tu conjunto de datos del plano de control, crea una función remota que se conecte a tu trabajo de Cloud Run o al extremo de la función de Cloud Run.

Comparte la función remota de resolución de entidades

Después de crear la función remota y otorgar los roles necesarios a tus usuarios finales, comparte con ellos la siguiente firma de la función remota. Los usuarios finales llaman a esta función remota para iniciar un trabajo de resolución de entidades.

`PARTNER_PROJECT_ID.DATASET_ID.match`(LIST_OF_PARAMETERS)

Reemplaza lo siguiente:

  • PARTNER_PROJECT_ID: Es el ID del proyecto de Google Cloud del proveedor de identidad.
  • DATASET_ID: Es el ID del conjunto de datos que contiene la función remota.
  • LIST_OF_PARAMETERS: Es la lista de parámetros que se pasarán a la función remota.

Opcional: Proporciona metadatos del trabajo de resolución de entidades

Para proporcionar metadatos del trabajo a tus usuarios finales, puedes exponer una función remota independiente o escribir una tabla de estado del trabajo en el conjunto de datos de salida del usuario final. Por ejemplo, puedes informar estados de ejecución, como RUNNING, COMPLETED o ERROR, junto con métricas de procesamiento.

Integración con Cloud Marketplace para la facturación

Para administrar la facturación y la integración de clientes a través de Google, integra tu servicio de resolución de entidades en Cloud Marketplace. Esta integración te permite configurar un modelo de precios basado en el uso del trabajo de resolución de entidades, mientras que Google se encarga de la facturación de tu servicio. Para obtener más información, consulta Cómo ofrecer productos de software como servicio (SaaS).

¿Qué sigue?