Configura y usa la resolución de entidades en BigQuery

La resolución de entidades en BigQuery te permite hacer coincidir, anular la duplicación y aumentar los registros en los conjuntos de datos sin mover los 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 las 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, prepara conjuntos de datos de entrada y salida en BigQuery, otorga acceso al conjunto de datos a tu proveedor de identidad y llama a su servicio de coincidencia. 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 de 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 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 coincidencia 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 trabajos
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 sobre la conexión externa de BigQuery Tabla de entrada con atributos de entidad, tabla de metadatos, tabla de estado del trabajo, tabla de resultados de coincidencias Llamada al procedimiento almacenado de SQL con CALL

Selecciona un proveedor de identidad para ver las 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 necesitas 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 propágala con las siguientes columnas:

  • RampIDs
  • Dominios de destino
  • Tipos de segmentación

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 de destino
  • Tipos de segmentación

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 necesarias, otorga a LiveRamp acceso para ver y procesar datos en tu conjunto de datos de entrada. Otorga acceso al conjunto de datos a la cuenta de servicio de LiveRamp Google Cloud . Para obtener más información sobre cómo compartir conjuntos de datos, consulta Comparte 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 RampID de tu dominio.
  2. Antes de ejecutar el trabajo, confirma que la configuración de la tabla de metadatos sea correcta.
  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 cualquier ID de tabla aplicable para tu tabla de entrada, tabla de metadatos y conjunto de datos de salida.

Por lo general, LiveRamp entrega los resultados de coincidencia 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 Embedded Identity 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 de 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 enriquecimiento y resolución de identidad de TruAudience de TransUnion 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 identidad alojado en la cuenta de TransUnion Google Cloud , crea una conexión a recursos de Cloud. Cuando configures la conexión, selecciona Modelos remotos de Vertex AI, funciones remotas, BigLake y Spanner (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 cuenta de servicio y, luego, comparte estos identificadores con el equipo de entrega al cliente de TransUnion.

Crea una función remota

Para pasar las asignaciones de esquemas y los metadatos de configuración al extremo del organizador de servicios 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 entidad 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 de 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 de esquemas y la configuración 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 de los trabajos

Para recibir actualizaciones del procesamiento por lotes, crea una tabla de estado del trabajo en tu conjunto de datos. Para supervisar los trabajos y activar los procesos downstream 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 identidad 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

En la tabla de salida de coincidencias, se almacenan los resultados de la resolución de entidades de TransUnion, incluidos los indicadores de coincidencia, las puntuaciones de vinculación, los IDs individuales persistentes y los IDs de grupo familiar. Para crear la tabla de resultados de coincidencias, ejecuta la siguiente sentencia de 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: el ID del conjunto de datos en el que creas la tabla de resultados 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 que se pueden compartir y que puedes usar en salas limpias de datos.

Otorga acceso al conjunto de datos a TransUnion

Después de crear las tablas y el procedimiento almacenado necesarios, otorga a TransUnion acceso para leer tus datos de entrada y escribir los resultados de la coincidencia. Obtén el ID de cuenta del 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 la 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

Para obtener asistencia con problemas técnicos o consultas de facturación relacionadas con TruAudience Identity Resolution and Enrichment 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 entrega 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 patentado ni la lógica de coincidencia.

Para configurar tu servicio, implementa un extremo de organización, 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 el servicio de resolución de entidades en BigQuery, asegúrate de tener lo siguiente:

  • Un conjunto de datos de gráfico de identidad y una lógica de coincidencia que se implementan en tu proyecto deGoogle 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 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 de orquestador y conéctalo a una función remota de BigQuery:

  1. Para procesar las solicitudes coincidentes 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 consola de Google Cloud , ve a la página Cloud Run.

      Ir a Cloud Run

    2. Haz clic en el nombre de tu función o trabajo y, luego, en la pestaña Seguridad.

    3. En el campo Cuenta de servicio, busca y registra la dirección de correo electrónico de la cuenta de servicio para 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 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 de trabajos a tus usuarios finales, puedes exponer una función remota independiente o escribir una tabla de estado de trabajos 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 las métricas de procesamiento.

Integra con Cloud Marketplace para la facturación

Para administrar la facturación y la incorporació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 de trabajos de resolución de entidades, mientras que Google controla la facturación de tu servicio. Para obtener más información, consulta Ofrece productos de software como servicio (SaaS).

¿Qué sigue?