Configurer et utiliser la résolution d'entités dans BigQuery

La résolution d'entités dans BigQuery vous permet de faire correspondre, de dédupliquer et d'enrichir des enregistrements dans des ensembles de données sans déplacer vos données sous-jacentes. En tant qu'utilisateur final, vous pouvez associer vos ensembles de données BigQuery à un fournisseur d'identité tel que LiveRamp ou TransUnion, et appeler une fonction distante pour résoudre les identités sur place. En tant que fournisseur d'identité, vous pouvez configurer des points de terminaison de fonction à distance et publier vos services de résolution d'entités sur Google Cloud Marketplace.

Configurer la résolution d'entités pour les utilisateurs finaux

Pour résoudre des entités en tant qu'utilisateur final, vous devez préparer des ensembles de données d'entrée et de sortie dans BigQuery, accorder l'accès à l'ensemble de données à votre fournisseur d'identité et appeler son service de mise en correspondance. Pour en savoir plus sur l'architecture, consultez Architecture de la résolution d'entités.

Avant de commencer

  1. Contactez un fournisseur d'identité. BigQuery accepte la résolution d'entités avec les fournisseurs LiveRamp et TransUnion.
  2. Obtenez les éléments suivants auprès du fournisseur d'identité :
    • Identifiants du compte de service
    • Signature de fonction distante
  3. Créez les ensembles de données suivants dans votre projet Google Cloud  :
    • Ensemble de données d'entrée
    • Ensemble de données de sortie

Rôles requis

Pour vous assurer que le compte de service du fournisseur d'identité dispose des autorisations nécessaires pour lire l'ensemble de données d'entrée et écrire dans l'ensemble de données de sortie, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service du fournisseur d'identité :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Votre administrateur peut également attribuer au compte de service du fournisseur d'identité les autorisations requises à l'aide de rôles personnalisés ou d'autres rôles prédéfinis.

Résoudre des entités avec un fournisseur d'identité

Une fois que vous avez créé vos ensembles de données et attribué les rôles requis, vous pouvez configurer vos tables et exécuter des jobs de correspondance avec le fournisseur d'identité de votre choix. Le tableau suivant récapitule la méthode d'intégration et les tables requises pour chaque fournisseur d'identité compatible :

Fournisseur d'identité Méthode d'intégration Tables requises dans votre ensemble de données Appel de job
LiveRamp Identité intégrée LiveRamp Table d'entrée avec les RampID, table de métadonnées Envoyer une demande par e-mail à l'assistance LiveRamp
TransUnion Fonction distante TruAudience via une connexion externe BigQuery Table d'entrée avec les attributs d'entité, table de métadonnées, table de l'état du job, table de sortie correspondante Appel de procédure stockée SQL à l'aide de CALL

Sélectionnez un fournisseur d'identité pour afficher les instructions de configuration et d'exécution de job spécifiques :

LiveRamp

Conditions requises pour LiveRamp

Avant de configurer la résolution d'entités LiveRamp dans BigQuery, remplissez les conditions préalables suivantes :

Configurer la résolution d'entités LiveRamp

Lorsque vous utilisez l'identité intégrée LiveRamp pour la première fois, suivez la procédure de configuration ci-dessous. Pour les exécutions suivantes, il vous suffit de mettre à jour votre table d'entrée et votre table de métadonnées.

Créer une table d'entrée LiveRamp

Créez une table dans votre ensemble de données d'entrée et remplissez-la avec les colonnes suivantes :

  • RampIDs
  • Domaines cibles
  • Types de cibles

Pour en savoir plus sur le schéma de la table d'entrée, consultez Colonnes et descriptions des tables d'entrée.

Créer une table de métadonnées LiveRamp

Pour contrôler l'exécution de l'identité intégrée LiveRamp dans BigQuery, créez une table de métadonnées dans votre ensemble de données d'entrée. Remplissez la table de métadonnées avec les colonnes de configuration suivantes :

  • ID client
  • Modes d'exécution
  • Domaines cibles
  • Types de cibles

Pour en savoir plus sur le schéma de la table de métadonnées, consultez Colonnes et descriptions des tables de métadonnées.

Accorder l'accès à l'ensemble de données à LiveRamp

Après avoir créé les tables requises, accordez à LiveRamp l'accès permettant d'afficher et de traiter les données de votre ensemble de données d'entrée. Accordez l'accès à l'ensemble de données au compte de service LiveRamp Google Cloud . Pour en savoir plus sur le partage d'ensembles de données, consultez Partager des tables et des ensembles de données avec LiveRamp.

Exécuter un job de résolution d'entités LiveRamp

Après avoir configuré vos tables et accordé l'accès à l'ensemble de données, exécutez un job de résolution d'entités avec LiveRamp dans BigQuery :

  1. Dans votre tableau d'entrée, vérifiez que tous les RampID de votre domaine sont présents.
  2. Avant d'exécuter le job, vérifiez que la configuration de votre table de métadonnées est exacte.
  3. Pour envoyer une demande de traitement de job, envoyez un e-mail à LiveRampIdentitySupport@liveramp.com. Dans votre demande, incluez l'ID du projet, l'ID de l'ensemble de données et tous les ID de table applicables pour votre table d'entrée, votre table de métadonnées et votre ensemble de données de sortie.

LiveRamp envoie généralement les résultats de la mise en correspondance à votre ensemble de données de sortie dans un délai de trois jours ouvrés.

Obtenir de l'aide et des informations sur la facturation de LiveRamp

LiveRamp gère l'assistance technique et la facturation pour l'identité intégrée dans BigQuery :

  • Assistance technique : contactez l'assistance LiveRamp Identity pour obtenir de l'aide concernant la configuration ou l'exécution des jobs.
  • Facturation : LiveRamp vous facture directement l'utilisation de la résolution d'entités.

TransUnion

Conditions préalables de TransUnion

Avant de configurer la résolution d'entités TransUnion dans BigQuery, envoyez un e-mail à l'assistance Cloud TransUnion pour signer un contrat d'accès aux services. Dans votre demande, fournissez les informations suivantes :

  • ID de votre projet Google Cloud
  • Types de données d'entrée
  • Cas d'utilisation prévu
  • Volume de données estimé

Une fois que l'assistance TransUnion Cloud a approuvé votre demande, elle active le service pour votre projet Google Cloud et partage un guide d'implémentation qui inclut les schémas de sortie disponibles.

Configurer la résolution d'entités TransUnion

Lorsque vous utilisez le service TransUnion TruAudience Identity Resolution and Enrichment dans BigQuery pour la première fois, suivez les étapes de configuration ci-dessous.

Créer une connexion externe

Pour associer votre compte Google Cloud au service de résolution des identités hébergé dans le compte Google Cloud TransUnion, créez une connexion aux ressources Cloud. Lorsque vous configurez la connexion, sélectionnez Modèles distants Vertex AI, fonctions distantes et BigLake (Ressource Cloud) comme type de connexion.

Une fois la connexion créée, copiez l'ID de connexion et l'ID du compte de service, puis partagez ces identifiants avec l'équipe de livraison client de TransUnion.

Créer une fonction distante

Pour transmettre les mappages de schéma et les métadonnées de configuration au point de terminaison de l'orchestrateur de service TransUnion, créez une fonction à distance. Lorsque vous créez la fonction à distance, spécifiez l'ID de connexion de votre connexion externe et l'URL du point de terminaison de la fonction Cloud Run que l'équipe de livraison client TransUnion a partagée avec vous.

Créer une table d'entrée TransUnion

Créez une table d'entrée dans votre ensemble de données d'entrée. TransUnion accepte les attributs d'entité suivants comme colonnes d'entrée :

  • Nom
  • Adresse postale
  • Adresse e-mail
  • Numéro de téléphone
  • Date de naissance
  • Adresse IPv4
  • ID de l'appareil

Suivez les consignes de schéma et de mise en forme du guide d'implémentation que TransUnion vous a envoyé. Si vous mappez chaque table d'entrée à un paramètre config_id distinct dans votre table de métadonnées, vous pouvez utiliser plusieurs tables d'entrée.

Créer une table de métadonnées TransUnion

Pour stocker les mappages de schéma et la configuration requis par le service de résolution des identités, créez une table de métadonnées dans votre ensemble de données d'entrée. Pour en savoir plus sur le schéma de métadonnées, consultez le guide d'implémentation que TransUnion vous a fourni.

Créer un tableau de l'état des tâches

Pour recevoir des informations sur le traitement par lot, créez un tableau d'état des jobs dans votre ensemble de données. Pour surveiller les jobs et déclencher des processus en aval dans votre pipeline, interrogez ce tableau d'état des jobs. Le tableau enregistre les états suivants :

  • RUNNING : le service de résolution des identités traite le lot.
  • COMPLETED : le service a terminé de traiter le lot et a écrit les résultats dans la table de sortie.
  • ERROR : le service a rencontré une erreur lors du traitement du lot.
Créer la procédure d'appel de service

La procédure stockée TransUnion_get_identities regroupe les métadonnées de configuration et appelle le point de terminaison de la fonction TransUnion Cloud Run. Pour créer cette procédure stockée, exécutez l'instruction SQL suivante :

-- 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;

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • DATASET_ID : ID de l'ensemble de données dans lequel vous créez la procédure et la fonction à distance.
Créer la table de sortie correspondante

La table de sortie correspondante stocke les résultats de la résolution d'entités de TransUnion, y compris les indicateurs de correspondance, les scores d'association, les ID individuels persistants et les ID de foyer. Pour créer la table de sortie correspondante, exécutez l'instruction SQL suivante :

-- 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);

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • DATASET_ID : ID de l'ensemble de données dans lequel vous créez la table de sortie correspondante.
Configurer les métadonnées de mappage de schéma

Pour mapper votre schéma d'entrée au schéma d'application TransUnion, suivez les instructions du guide d'implémentation que TransUnion vous a envoyé. Ces métadonnées configurent également la façon dont le service génère des ID de collaboration, qui sont des identifiants non persistants et partageables que vous pouvez utiliser dans les data clean rooms.

Accorder l'accès à l'ensemble de données à TransUnion

Après avoir créé les tables et la procédure stockée requises, accordez à TransUnion l'accès en lecture à vos données d'entrée et en écriture aux résultats de la mise en correspondance. Obtenez l'ID du compte de service de connexion Apache Spark auprès de l'équipe TransUnion chargée de la livraison aux clients. Ensuite, accordez à ce compte de service le rôle Éditeur de données BigQuery (roles/bigquery.dataEditor) sur l'ensemble de données contenant vos tables d'entrée et de sortie.

Exécuter un job de résolution d'entités TransUnion

Une fois que vous avez configuré vos tables et accordé l'accès à l'ensemble de données, vous pouvez lancer une exécution par lot de résolution d'entités. Pour appeler le service de résolution d'entités, appelez la procédure stockée TransUnion_get_identities :

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

Remplacez les éléments suivants :

  • PROJECT_ID : ID de votre projet Google Cloud .
  • DATASET_ID : ID de l'ensemble de données contenant votre table de métadonnées et votre procédure stockée.
  • CONFIG_ID : ID de configuration de l'exécution par lot, tel que "1".

Obtenir de l'aide et des informations sur la facturation de TransUnion

Pour obtenir de l'aide concernant des problèmes techniques ou des questions de facturation liés à la résolution et à l'enrichissement de l'identité TruAudience dans BigQuery, contactez directement TransUnion :

  • Assistance technique : contactez l'assistance TransUnion Cloud pour obtenir de l'aide concernant la configuration, le mappage de schéma ou le dépannage.
  • Facturation : TransUnion suit l'utilisation du service à des fins de facturation. Contactez votre représentant TransUnion pour en savoir plus sur votre compte et les tarifs.

Configurer la résolution d'entités pour les fournisseurs d'identité

En tant que fournisseur d'identité, vous pouvez proposer votre service de résolution d'entités aux utilisateurs finaux de BigQuery. Cette architecture permet de protéger votre propriété intellectuelle, car vous n'exposez pas votre logique de correspondance ni votre graphique d'identité propriétaires.

Pour configurer votre service, vous devez déployer un point de terminaison d'orchestrateur, créer une fonction distante BigQuery, accorder les rôles requis et partager la signature de la fonction distante avec vos utilisateurs finaux. Pour en savoir plus sur l'architecture, consultez Architecture de la résolution d'entités.

Avant de commencer

Avant de configurer votre service de résolution d'entités dans BigQuery, assurez-vous de disposer des éléments suivants :

  • Un ensemble de données de graphe d'identité et une logique de mise en correspondance déployés dans votre projetGoogle Cloud ou dans une base de données externe.
  • Identifiants principaux des utilisateurs finaux, tels que les adresses e-mail des utilisateurs, des comptes de service ou des groupes Google, que vous avez obtenus auprès de vos utilisateurs finaux.

Rôles requis

Pour vous assurer que le compte de service du fournisseur d'identité dispose des autorisations nécessaires pour exécuter des jobs de résolution d'entités, demandez à votre administrateur d'accorder les rôles IAM suivants au compte de service du fournisseur d'identité :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Votre administrateur peut également attribuer au compte de service du fournisseur d'identité les autorisations requises à l'aide de rôles personnalisés ou d'autres rôles prédéfinis.

Configurer le point de terminaison de la fonction distante

Pour traiter les demandes de résolution d'entités des utilisateurs finaux, déployez un point de terminaison d'orchestrateur et connectez-le à une fonction distante BigQuery :

  1. Pour traiter les demandes de mise en correspondance de votre fonction distante, créez un job Cloud Run ou une fonction Cloud Run Functions. Vous pouvez utiliser l'une ou l'autre de ces options pour votre point de terminaison.

  2. Pour trouver l'adresse e-mail du compte de service associé à votre job Cloud Run ou à votre fonction Cloud Run Functions, procédez comme suit :

    1. Dans la console Google Cloud , accédez à la page Cloud Functions.

      Accéder à Cloud Functions

    2. Pour ouvrir les informations sur la fonction, cliquez sur son nom, puis sur l'onglet Détails.

    3. Dans le volet Informations générales, recherchez et notez l'adresse e-mail du compte de service pour la fonction distante.

  3. Dans votre ensemble de données du plan de contrôle, créez une fonction distante qui se connecte au point de terminaison de votre job Cloud Run ou de votre fonction Cloud Run.

Partager la fonction distante de résolution d'entités

Une fois que vous avez créé la fonction distante et attribué les rôles requis à vos utilisateurs finaux, partagez la signature de fonction distante suivante avec eux. Les utilisateurs finaux appellent cette fonction distante pour démarrer un job de résolution d'entités.

`PARTNER_PROJECT_ID.DATASET_ID.match`(LIST_OF_PARAMETERS)

Remplacez les éléments suivants :

  • PARTNER_PROJECT_ID : ID du projet Google Cloud du fournisseur d'identité.
  • DATASET_ID : ID de l'ensemble de données contenant la fonction distante.
  • LIST_OF_PARAMETERS : liste des paramètres à transmettre à la fonction à distance.

Facultatif : Fournir les métadonnées du job de résolution d'entités

Pour fournir des métadonnées de job à vos utilisateurs finaux, vous pouvez exposer une fonction distante distincte ou écrire une table d'état de job dans l'ensemble de données de sortie de l'utilisateur final. Par exemple, vous pouvez signaler les états d'exécution tels que RUNNING, COMPLETED ou ERROR, ainsi que les métriques de traitement.

Intégrer Cloud Marketplace pour la facturation

Pour gérer la facturation et l'intégration des clients via Google, intégrez votre service de résolution d'entités à Cloud Marketplace. Cette intégration vous permet de configurer un modèle de tarification basé sur l'utilisation du job de résolution d'entités, tandis que Google gère la facturation de votre service. Pour en savoir plus, consultez la section Proposer des produits SaaS (Software as a Service).

Étapes suivantes