Configura e utilizza la risoluzione delle entità in BigQuery

La risoluzione delle entità in BigQuery consente di abbinare, deduplicare e migliorare i record nei set di dati senza spostare i dati sottostanti. In qualità di utente finale, puoi connettere i tuoi set di dati BigQuery a un provider di identità come LiveRamp o TransUnion e chiamare una funzione remota per risolvere le identità in loco. In qualità di provider di identità, puoi configurare gli endpoint delle funzioni remote e pubblicare i tuoi servizi di risoluzione delle entità su Google Cloud Marketplace.

Configura la risoluzione delle entità per gli utenti finali

Per risolvere le entità come utente finale, prepara i set di dati di input e output in BigQuery, concedi l'accesso al set di dati al tuo provider di identità e richiama il suo servizio di corrispondenza. Per saperne di più sull'architettura, consulta Architettura di risoluzione delle entità.

Prima di iniziare

  1. Contatta un provider di identità. BigQuery supporta la risoluzione delle entità con LiveRamp e TransUnion.
  2. Recupera i seguenti elementi dal provider di identità:
    • Credenziali del service account
    • Firma della funzione remota
  3. Crea i seguenti set di dati nel tuo progetto Google Cloud :
    • Set di dati di input
    • Set di dati di output

Ruoli obbligatori

Per assicurarti che il account di servizio del provider di identità disponga delle autorizzazioni necessarie per leggere il set di dati di input e scrivere nel set di dati di output, chiedi all'amministratore di concedere i seguenti ruoli IAM al account di servizio del provider di identità:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche essere in grado di concedere al account di servizio del provider di identità le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Risolvi le entità con un provider di identità

Dopo aver creato i set di dati e concesso i ruoli richiesti, puoi configurare le tabelle ed eseguire job di corrispondenza con il provider di identità scelto. La tabella seguente riepiloga il metodo di integrazione e le tabelle richieste per ogni provider di identità supportato:

Provider di identità Metodo di integrazione Tabelle obbligatorie nel set di dati Chiamata job
LiveRamp LiveRamp Embedded Identity Tabella di input con RampID, tabella dei metadati Invia un'email di richiesta all'assistenza LiveRamp
TransUnion Funzione remota TruAudience tramite connessione esterna BigQuery Tabella di input con attributi delle entità, tabella dei metadati, tabella dello stato del job, tabella di output corrispondente Chiamata della stored procedure SQL utilizzando CALL

Seleziona un provider di identità per visualizzare le istruzioni specifiche per la configurazione e l'esecuzione dei job:

LiveRamp

Prerequisiti di LiveRamp

Prima di configurare la risoluzione delle entità LiveRamp in BigQuery, completa i seguenti prerequisiti:

Configura la risoluzione delle entità LiveRamp

Quando utilizzi LiveRamp Embedded Identity per la prima volta, completa i seguenti passaggi di configurazione. Per le esecuzioni successive, devi solo aggiornare la tabella di input e la tabella dei metadati.

Crea una tabella di input LiveRamp

Crea una tabella nel set di dati di input e compilala con le seguenti colonne:

  • RampIDs
  • Domini di destinazione
  • Tipi di target

Per ulteriori informazioni sullo schema della tabella di input, consulta Colonne e descrizioni della tabella di input.

Crea una tabella di metadati LiveRamp

Per controllare l'esecuzione di LiveRamp Embedded Identity in BigQuery, crea una tabella di metadati nel set di dati di input. Compila la tabella dei metadati con le seguenti colonne di configurazione:

  • ID client
  • Modalità di esecuzione
  • Domini di destinazione
  • Tipi di target

Per saperne di più sullo schema della tabella dei metadati, consulta Colonne e descrizioni della tabella dei metadati.

Concedi l'accesso al set di dati a LiveRamp

Dopo aver creato le tabelle richieste, concedi a LiveRamp l'accesso per visualizzare ed elaborare i dati nel set di dati di input. Concedi l'accesso al set di dati al service account LiveRampGoogle Cloud . Per saperne di più sulla condivisione dei set di dati, consulta Condividi tabelle e set di dati con LiveRamp.

Esegui un job di risoluzione delle entità LiveRamp

Dopo aver configurato le tabelle e concesso l'accesso al set di dati, esegui un job di risoluzione delle entità con LiveRamp in BigQuery:

  1. Nella tabella di input, verifica che siano presenti tutti i RampID del tuo dominio.
  2. Prima di eseguire il job, verifica che la configurazione della tabella dei metadati sia corretta.
  3. Per inviare una richiesta di elaborazione dei job, invia un'email a LiveRampIdentitySupport@liveramp.com. Nella richiesta, includi l'ID progetto, l'ID set di dati e gli eventuali ID tabella applicabili per la tabella di input, la tabella dei metadati e il set di dati di output.

In genere, LiveRamp fornisce i risultati della corrispondenza al set di dati di output entro tre giorni lavorativi.

Ricevi assistenza e dati di fatturazione di LiveRamp

LiveRamp gestisce l'assistenza tecnica e la fatturazione per Embedded Identity in BigQuery:

  • Assistenza tecnica: contatta l'assistenza di LiveRamp Identity per ricevere assistenza con la configurazione o l'esecuzione dei job.
  • Fatturazione: LiveRamp ti addebita direttamente l'utilizzo della risoluzione delle entità.

TransUnion

Prerequisiti di TransUnion

Prima di configurare la risoluzione delle entità TransUnion in BigQuery, invia un'email all'assistenza cloud di TransUnion per firmare un contratto di accesso al servizio. Nella richiesta, fornisci le seguenti informazioni:

  • Il tuo ID progetto Google Cloud
  • Tipi di dati di input
  • Caso d'uso previsto
  • Volume di dati stimato

Dopo aver approvato la tua richiesta, l'assistenza cloud di TransUnion abilita il servizio per il tuo progetto Google Cloud e condivide una guida all'implementazione che include gli schemi di output disponibili.

Configura la risoluzione delle entità TransUnion

Quando utilizzi il servizio TransUnion TruAudience Identity Resolution and Enrichment in BigQuery per la prima volta, completa i seguenti passaggi di configurazione.

Crea una connessione esterna

Per connettere il tuo account Google Cloud al servizio di risoluzione delle identità ospitato nell'account TransUnion Google Cloud , crea una connessione alle risorse Cloud. Quando configuri la connessione, seleziona Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud) come tipo di connessione.

Dopo aver creato la connessione, copia l'ID connessione e l'ID account di servizio, quindi condividi questi identificatori con il team di assistenza clienti di TransUnion.

Crea una funzione remota

Per passare le mappature dello schema e i metadati di configurazione all'endpoint dell'orchestratore del servizio TransUnion, crea una funzione remota. Quando crei la funzione remota, specifica l'ID connessione della tua connessione esterna e l'URL dell'endpoint della funzione Cloud Run condiviso con te dal team di assistenza clienti di TransUnion.

Crea una tabella di input TransUnion

Crea una tabella di input nel set di dati di input. TransUnion supporta i seguenti attributi delle entità come colonne di input:

  • Nome
  • Indirizzo postale
  • Indirizzo email
  • Numero di telefono
  • Data di nascita
  • Indirizzo IPv4
  • ID dispositivo

Segui le linee guida per lo schema e la formattazione riportate nella guida all'implementazione che TransUnion ha condiviso con te. Se mappi ogni tabella di input a un parametro config_id distinto nella tabella dei metadati, puoi utilizzare più tabelle di input.

Crea una tabella di metadati TransUnion

Per archiviare le mappature e la configurazione dello schema richieste dal servizio di risoluzione delle identità, crea una tabella dei metadati nel set di dati di input. Per ulteriori informazioni sullo schema dei metadati, consulta la guida all'implementazione che TransUnion ha condiviso con te.

Crea una tabella dello stato dei job

Per ricevere aggiornamenti sull'elaborazione batch, crea una tabella dello stato dei job nel tuo set di dati. Per monitorare i job e attivare i processi downstream nella pipeline, esegui una query su questa tabella dello stato dei job. La tabella registra i seguenti stati:

  • RUNNING: il servizio di risoluzione delle identità sta elaborando il batch.
  • COMPLETED: il servizio ha terminato l'elaborazione del batch e ha scritto i risultati nella tabella di output.
  • ERROR: il servizio ha riscontrato un errore durante l'elaborazione del batch.
Crea la procedura di chiamata del servizio

La stored procedure TransUnion_get_identities pacchettizza i metadati di configurazione e richiama l'endpoint della funzione Cloud Run di TransUnion. Per creare questa stored procedure, esegui la seguente istruzione 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;

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • DATASET_ID: l'ID del set di dati in cui crei la procedura e la funzione remota.
Crea la tabella di output corrispondente

La tabella di output corrispondente memorizza i risultati della risoluzione delle entità di TransUnion, inclusi i flag di corrispondenza, i punteggi di collegamento, gli ID individuali permanenti e gli ID nucleo familiare. Per creare la tabella di output corrispondente, esegui la seguente istruzione 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);

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • DATASET_ID: l'ID del set di dati in cui crei la tabella di output corrispondente.
Configura i metadati della mappatura dello schema

Per mappare lo schema di input allo schema dell'applicazione TransUnion, segui le istruzioni riportate nella guida all'implementazione che TransUnion ha condiviso con te. Questi metadati configurano anche il modo in cui il servizio genera gli ID collaborazione, ovvero identificatori condivisibili e non persistenti che puoi utilizzare nelle data clean room.

Concedi l'accesso al set di dati a TransUnion

Dopo aver creato le tabelle e la stored procedure richieste, concedi a TransUnion l'accesso per leggere i dati di input e scrivere i risultati della corrispondenza. Ottieni l'ID account di servizio di connessione Apache Spark dal team di assistenza clienti di TransUnion. Poi, concedi a questo account di servizio il ruolo BigQuery Data Editor (roles/bigquery.dataEditor) nel set di dati che contiene le tabelle di input e output.

Esegui un job di risoluzione delle entità TransUnion

Dopo aver configurato le tabelle e concesso l'accesso al set di dati, puoi avviare un'esecuzione batch di risoluzione delle entità. Per richiamare il servizio di risoluzione delle entità, chiama la stored procedure TransUnion_get_identities:

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

Sostituisci quanto segue:

  • PROJECT_ID: il tuo ID progetto Google Cloud .
  • DATASET_ID: l'ID del set di dati che contiene la tabella dei metadati e la stored procedure.
  • CONFIG_ID: l'ID di configurazione per l'esecuzione batch, ad esempio "1".

Ricevi assistenza e dati di fatturazione da TransUnion

Per assistenza in merito a problemi tecnici o domande sulla fatturazione relative a TruAudience Identity Resolution and Enrichment in BigQuery, contatta direttamente TransUnion:

  • Assistenza tecnica: contatta l'assistenza TransUnion Cloud per ricevere assistenza con la configurazione, la mappatura dello schema o la risoluzione dei problemi.
  • Fatturazione: TransUnion monitora l'utilizzo del servizio ai fini della fatturazione. Contatta il tuo rappresentante TransUnion per i dettagli sull'account e sui prezzi.

Configura la risoluzione delle entità per i provider di identità

In qualità di provider di identità, puoi offrire il tuo servizio di risoluzione delle entità agli utenti finali di BigQuery. Questa architettura contribuisce a proteggere la tua proprietà intellettuale perché non esponi il tuo grafico di identità proprietario o la logica di corrispondenza.

Per configurare il servizio, esegui il deployment di un endpoint dell'orchestratore, crei una funzione remota BigQuery, concedi i ruoli richiesti e condividi la firma della funzione remota con gli utenti finali. Per saperne di più sull'architettura, consulta Architettura di risoluzione delle entità.

Prima di iniziare

Prima di configurare il servizio di risoluzione delle entità in BigQuery, assicurati di disporre di quanto segue:

  • Un set di dati del grafico delle identità e una logica di corrispondenza di cui è stato eseguito il deployment nel tuo progettoGoogle Cloud o in un database esterno.
  • Identificatori delle entità utente finale, come indirizzi email di utenti, account di servizio o gruppi Google, che hai ottenuto dai tuoi utenti finali.

Ruoli obbligatori

Per assicurarti che il account di servizio del provider di identità disponga delle autorizzazioni necessarie per eseguire i job di risoluzione delle entità, chiedi all'amministratore di concedere i seguenti ruoli IAM al account di servizio del provider di identità:

  • Per consentire al account di servizio associato alla tua funzione di leggere e scrivere nei set di dati associati e avviare job:
  • Affinché l'entità utente finale possa visualizzare e connettersi alla funzione remota:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

L'amministratore potrebbe anche essere in grado di concedere al account di servizio del provider di identità le autorizzazioni richieste tramite ruoli personalizzati o altri ruoli predefiniti.

Configura l'endpoint della funzione remota

Per elaborare le richieste di risoluzione delle entità degli utenti finali, esegui il deployment di un endpoint dell'orchestratore e collegalo a una funzione remota di BigQuery:

  1. Per elaborare le richieste con corrispondenza dalla funzione remota, crea un job Cloud Run o una funzione Cloud Run. Puoi utilizzare una delle due opzioni per l'endpoint.

  2. Per trovare l'indirizzo email del account di servizio associato al tuo job Cloud Run o alla tua funzione Cloud Run, segui questi passaggi:

    1. Nella console Google Cloud , vai alla pagina Cloud Run.

      Vai a Cloud Run

    2. Fai clic sul nome della funzione o del job, quindi sulla scheda Sicurezza.

    3. Nel campo Service account, individua e registra l'indirizzo email del service account per la funzione remota.

  3. Nel set di dati del control plane, crea una funzione remota che si connetta al job Cloud Run o all'endpoint della funzione Cloud Run.

Condividi la funzione remota di risoluzione delle entità

Dopo aver creato la funzione remota e aver concesso i ruoli richiesti agli utenti finali, condividi con loro la seguente firma della funzione remota. Gli utenti finali chiamano questa funzione remota per avviare un job di risoluzione delle entità.

`PARTNER_PROJECT_ID.DATASET_ID.match`(LIST_OF_PARAMETERS)

Sostituisci quanto segue:

  • PARTNER_PROJECT_ID: l'ID progetto Google Cloud dell'identity provider.
  • DATASET_ID: l'ID del set di dati che contiene la funzione remota.
  • LIST_OF_PARAMETERS: l'elenco dei parametri da passare alla funzione remota.

(Facoltativo) Fornisci i metadati del job di risoluzione delle entità

Per fornire i metadati del job agli utenti finali, puoi esporre una funzione remota separata o scrivere una tabella dello stato del job nel set di dati di output dell'utente finale. Ad esempio, puoi segnalare stati di esecuzione come RUNNING, COMPLETED o ERROR, insieme alle metriche di elaborazione.

Integrazione con Cloud Marketplace per la fatturazione

Per gestire la fatturazione e l'onboarding dei clienti tramite Google, integra il tuo servizio di risoluzione delle entità con Cloud Marketplace. Questa integrazione ti consente di configurare un modello di prezzi basato sull'utilizzo dei job di risoluzione delle entità, mentre Google gestisce la fatturazione per il tuo servizio. Per saperne di più, consulta Offerta di prodotti Software as a Service (SaaS).

Passaggi successivi