Configurare e utilizzare la risoluzione delle entità in BigQuery

Questo documento descrive come implementare la risoluzione delle entità per gli utenti finali e i provider di identità.

Puoi utilizzare questo documento per connetterti a un provider di identità e utilizzare il suo servizio per trovare le corrispondenze tra i record. I provider di identità possono utilizzare questo documento per configurare i servizi da condividere con te su Google Cloud Marketplace.

Flusso di lavoro per gli utenti finali

Le sezioni seguenti mostrano come configurare la risoluzione delle entità in BigQuery. Per una rappresentazione visiva della configurazione completa, consulta l'architettura di risoluzione delle entità.

Prima di iniziare

  1. Contatta un provider di identità. TransUnion
  2. Richiedi al provider di identità i seguenti elementi:
    • Credenziali dell'account di servizio
    • Firma della funzione remota
  3. Crea due set di dati nel tuo Google Cloud progetto:
    • Set di dati di input
    • Set di dati di output

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire i job di risoluzione delle entità, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Affinché il account di servizio del provider di identità possa leggere il set di dati di input e scrivere nel set di dati di output:

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

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Tradurre o risolvere le entità

Per istruzioni specifiche del provider di identità, consulta le sezioni seguenti.

LiveRamp

Prerequisiti

Configurazione

I seguenti passaggi sono necessari quando utilizzi l'identità incorporata di LiveRamp per la prima volta. Dopo la configurazione, devi solo modificare la tabella di input e la tabella dei metadati tra le esecuzioni.

Creare una tabella di input

Crea una tabella nel set di dati di input. Compila la tabella con RampID, domini di destinazione e tipi di destinazione. Per dettagli ed esempi, consulta Colonne e descrizioni della tabella di input.

Creare una tabella dei metadati

La tabella dei metadati controlla l'esecuzione dell'identità incorporata di LiveRamp in BigQuery. Crea una tabella dei metadati nel set di dati di input. Compila la tabella dei metadati con ID client, modalità di esecuzione, domini di destinazione e tipi di destinazione. Per dettagli ed esempi, consulta Colonne e descrizioni della tabella dei metadati.

Condividere le tabelle con LiveRamp

Concedi all'account di servizio LiveRamp Google Cloud l'accesso per visualizzare ed elaborare i dati nel set di dati di input. Per dettagli ed esempi, consulta Condividere tabelle e set di dati con LiveRamp.

Eseguire un job di identità incorporata

Per eseguire un job di identità incorporata con LiveRamp in BigQuery:

  1. Verifica che tutti i RampID codificati nel tuo dominio siano nella tabella di input.
  2. Verifica che la tabella dei metadati sia ancora accurata prima di eseguire il job.
  3. Contatta LiveRampIdentitySupport@liveramp.com con una richiesta di elaborazione del job. Includi l'ID progetto, l'ID set di dati e l'ID tabella (se applicabile) per la tabella di input, la tabella dei metadati e il set di dati di output.

In genere, i risultati vengono forniti al set di dati di output entro tre giorni lavorativi.

Assistenza LiveRamp

Per problemi di assistenza, contatta l'assistenza per l'identità di LiveRamp.

Fatturazione LiveRamp

LiveRamp gestisce la fatturazione per la risoluzione delle entità.

TransUnion

Prerequisiti

  • Contatta l'assistenza cloud di TransUnion per firmare un contratto per accedere al servizio. Fornisci l'ID progetto, i tipi di dati di input, il caso d'uso e il volume di dati. Google Cloud
  • L'assistenza cloud di TransUnion abilita il servizio per il tuo Google Cloud progetto e condivide una guida all'implementazione dettagliata che include i dati di output disponibili.

Configurazione

I seguenti passaggi sono necessari quando utilizzi il servizio di risoluzione e arricchimento dell'identità TruAudience di TransUnion nel tuo ambiente BigQuery.

Creare una connessione esterna

Crea una connessione a un'origine dati esterna di tipo Modelli remoti di Vertex AI, funzioni remote e BigLake (risorsa Cloud). Utilizza questa connessione per attivare il servizio di risoluzione dell'identità ospitato nell'account TransUnion Google Cloud dal tuo Google Cloud account.

Copia l'ID connessione e l'ID account di servizio e condividi questi identificatori con il team di consegna clienti di TransUnion.

Creare una funzione remota

Crea una funzione remota per interagire con l'endpoint dell'orchestratore del servizio ospitato nel progetto TransUnion Google Cloud per passare i metadati necessari (inclusi i mapping dello schema) al servizio TransUnion. Utilizza l'ID connessione della connessione esterna che hai creato e l'endpoint della funzione Cloud ospitata da TransUnion condiviso dal team di consegna clienti di TransUnion.

Creare una tabella di input

Crea una tabella nel set di dati di input. TransUnion supporta come input nome, indirizzo postale, email, telefono, data di nascita, indirizzo IPv4 e ID dispositivo. Segui le linee guida di formattazione nella guida all'implementazione che TransUnion ha condiviso con te.

Creare una tabella dei metadati

Crea una tabella dei metadati per archiviare la configurazione richiesta dal servizio di risoluzione dell'identità per elaborare i dati, inclusi i mapping dello schema. Per dettagli ed esempi, consulta la guida all'implementazione che TransUnion ha condiviso con te.

Creare una tabella dello stato del job

Crea una tabella per ricevere aggiornamenti sull'elaborazione di un batch di input. Puoi eseguire query su questa tabella per attivare altri processi downstream nella pipeline. Gli stati possibili del job includono RUNNING, COMPLETED o ERROR.

Creare la chiamata al servizio

Utilizza la seguente procedura per chiamare il servizio di risoluzione dell'identità di TransUnion dopo aver raccolto tutti i metadati, averli impacchettati e averli passati all'endpoint della funzione Cloud di chiamata ospitata da TransUnion.

-- 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;
Creare la tabella di output di corrispondenza

Esegui il seguente script SQL per creare la tabella di output di corrispondenza. Si tratta dell'output standard dell'applicazione, che include flag di corrispondenza, punteggi, ID individuali persistenti e ID famiglia.

-- 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);
Configurare i metadati

Segui la guida all'implementazione che TransUnion ha condiviso con te per mappare lo schema di input allo schema dell'applicazione. Questi metadati configurano anche la generazione di ID di collaborazione, che sono identificatori non persistenti condivisibili che possono essere utilizzati nelle data clean room.

Concedere l'accesso in lettura e scrittura

Ottieni l'ID account di servizio della connessione Apache Spark dal team di consegna clienti di TransUnion e concedi l'accesso in lettura e scrittura al set di dati contenente le tabelle di input e output. Ti consigliamo di fornire l'ID account di servizio con un ruolo Editor dati BigQuery nel set di dati.

Richiamare l'applicazione

Puoi richiamare l'applicazione dal tuo ambiente eseguendo il seguente script.

call `<project_id>.<dataset_id>.TransUnion_get_identities`("<project_id>.<dataset_id>.TransUnion_er_metadata","1");
-- using metadata table, and 1 = config_id for the batch run

Assistenza

Per problemi tecnici, contatta l'assistenza cloud di TransUnion.

Fatturazione e utilizzo

TransUnion monitora l'utilizzo dell'applicazione e la utilizza a fini di fatturazione. I clienti attivi possono contattare il rappresentante di consegna di TransUnion per ulteriori informazioni.

Flusso di lavoro per i provider di identità

Le sezioni seguenti mostrano come configurare la risoluzione delle entità in BigQuery. Per una rappresentazione visiva della configurazione completa, consulta l'architettura di risoluzione delle entità.

Prima di iniziare

  1. Crea un job Cloud Run o una funzione Cloud Run da integrare con la funzione remota. Entrambe le opzioni sono adatte a questo scopo.

  2. Recupera il nome del account di servizio associato a Cloud Run o alla funzione Cloud Run:

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

      Vai a Cloud Functions

    2. Fai clic sul nome della funzione, quindi sulla scheda Dettagli.

    3. Nel riquadro Informazioni generali, trova e annota il nome del service account per la funzione remota.

  3. Crea una funzione remota.

  4. Recupera le entità utente finale dall'utente finale.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per eseguire i job di risoluzione delle entità, chiedi all'amministratore di concederti i seguenti ruoli IAM:

  • Affinché il account di servizio associato alla tua funzione possa leggere e scrivere nei set di dati associati e avviare i 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.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Condividere la funzione remota di risoluzione delle entità

Modifica e condividi il seguente codice dell'interfaccia remota con l'utente finale. L'utente finale ha bisogno di questo codice per avviare il job di risoluzione delle entità.

`PARTNER_PROJECT_ID.DATASET_ID`.match`(LIST_OF_PARAMETERS)

Sostituisci LIST_OF_PARAMETERS con l'elenco dei parametri che vengono passati alla funzione remota.

Facoltativo: fornire i metadati del job

Puoi fornire facoltativamente i metadati del job utilizzando una funzione remota separata o scrivendo una nuova tabella di stato nel set di dati di output dell'utente. Esempi di metadati includono stati e metriche dei job.

Fatturazione per i provider di identità

Per semplificare la fatturazione e l'onboarding dei clienti, integra il tuo servizio di risoluzione delle entità con il Google Cloud Marketplace. In questo modo puoi configurare un modello di prezzi basato sull'utilizzo del job di risoluzione delle entità, con Google che gestisce la fatturazione per te. Per ulteriori informazioni, consulta Offrire prodotti Software as a Service (SaaS).

Passaggi successivi