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 connecter 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 distante 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 préparez des ensembles de données d'entrée et de sortie dans BigQuery, accordez l'accès aux ensembles de données à votre fournisseur d'identité et appelez son service de mise en correspondance. Pour en savoir plus sur l'architecture, consultez Architecture de résolution d'entités.

Avant de commencer

  1. Contactez un fournisseur d'identité. BigQuery accepte la résolution d'entités avec 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 les entités avec un fournisseur d'identité

Après avoir créé vos ensembles de données et accordé les rôles requis, vous pouvez configurer vos tables et exécuter des jobs de mise en 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 d'état du job, table de sortie de correspondance 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

Prérequis pour LiveRamp

Avant de configurer la résolution d'entités LiveRamp dans BigQuery, assurez-vous de remplir 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 ultérieures, 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 renseignez-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 à LiveRamp l'accès à l'ensemble de données

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 LiveRampGoogle 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 table 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 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 des informations sur l'assistance et la facturation 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

Prérequis pour 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 au service. 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 incluant les schémas de sortie disponibles.

Configurer la résolution d'entités TransUnion

Lorsque vous utilisez le service de résolution et d'enrichissement d'identité TransUnion TruAudience dans BigQuery pour la première fois, procédez comme suit.

Créer une connexion externe

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

Après avoir créé la connexion, copiez l'ID de connexion et l'ID du compte de service, puis partagez ces identifiants avec l'équipe de livraison client 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 services TransUnion, créez une fonction distante. Lorsque vous créez la fonction distante, 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 fourni. 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 d'identité, 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 a partagé avec vous.

Créer une table d'état des jobs

Pour recevoir des mises à jour sur le traitement par lot, créez une table 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 cette table d'état des jobs. Le tableau enregistre les états suivants :

  • RUNNING : le service de résolution d'identité traite le lot.
  • COMPLETED : le service a terminé le traitement du 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 empaquette vos métadonnées de configuration et appelle le point de terminaison de la fonction Cloud Run TransUnion. 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 distante.
Créer la table de sortie correspondante

La table de sortie de correspondance stocke les résultats de résolution d'entités de TransUnion, y compris les indicateurs de correspondance, les scores de liaison, 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 a partagé avec vous. Ces métadonnées configurent également la manière dont le service génère des ID de collaboration, qui sont des identifiants partageables et non persistants que vous pouvez utiliser dans les salles blanches de données.

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

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 correspondance. Obtenez l'ID du compte de service de connexion Apache Spark auprès de l'équipe de livraison client TransUnion. Ensuite, attribuez à 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, par exemple "1".

Obtenir des informations sur l'assistance et la facturation TransUnion

Pour obtenir de l'aide concernant des problèmes techniques ou des questions de facturation liées à TruAudience Identity Resolution and Enrichment 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 les comptes 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 vous aide à protéger votre propriété intellectuelle, car vous n'exposez pas votre graphique d'identité propriétaire ni votre logique de correspondance.

Pour configurer votre service, vous déployez un point de terminaison d'orchestrateur, créez une fonction distante BigQuery, accordez les rôles requis et partagez la signature de la fonction distante avec vos utilisateurs finaux. Pour en savoir plus sur l'architecture, consultez Architecture de 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 de l'utilisateur final, tels que les adresses e-mail de l'utilisateur, du compte de service ou du groupe Google, que vous avez obtenues 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 requêtes 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 avec correspondance de votre fonction distante, créez un job Cloud Run ou une fonction Cloud Run. 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, procédez comme suit :

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

      Accédez à Cloud Run

    2. Cliquez sur le nom de votre fonction ou de votre job, puis sur l'onglet Sécurité.

    3. Dans le champ Compte de service, 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 à votre job Cloud Run ou au point de terminaison de votre fonction Cloud Run.

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

Après avoir créé la fonction distante et attribué les rôles requis à vos utilisateurs finaux, partagez avec eux la signature de fonction distante suivante. Les utilisateurs finaux appellent cette fonction distante pour lancer 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 distante.

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 des états d'exécution tels que RUNNING, COMPLETED ou ERROR, ainsi que des 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