Exécuter un job de rapprochement d'entités depuis la console Google Cloud

Preview

Ce produit est soumis aux "Conditions des Offres de pré-DG" de la section "Conditions générales du service" des Conditions spécifiques du service. Vous pouvez traiter des données à caractère personnel lorsque vous utilisez ce produit comme indiqué dans l'Avenant relatif au traitement des données dans le cloud, sous réserve de respecter les obligations et restrictions décrites dans le contrat en vertu duquel vous accédez à Google Cloud. Les produits de pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Ce guide de démarrage rapide vous présente l'API Entity Reconciliation. Dans ce guide de démarrage rapide, vous allez utiliser la console Google Cloud pour configurer votre projetGoogle Cloud et les autorisations, créer des fichiers de mappage de schéma, puis envoyer une requête à Enterprise Knowledge Graph pour exécuter un job de réconciliation d'entités.

Pour obtenir des instructions détaillées sur cette tâche directement dans la console Google Cloud , cliquez sur Visite guidée :

Visite guidée

Identifier votre source de données

L'API Entity Reconciliation n'accepte que les tables BigQuery comme entrée. Si vos données ne sont pas stockées dans BigQuery, nous vous recommandons de les y transférer avant que d'autres connecteurs ne soient disponibles. Assurez-vous également que le compte de service ou le client OAuth que vous avez configuré dispose d'un accès en lecture aux tables que vous prévoyez d'utiliser, ainsi que d'une autorisation d'écriture dans l'ensemble de données de destination.

Créer un fichier de mappage de schéma

Pour chacune de vos sources de données, vous devez créer un fichier de mappage de schéma pour indiquer à Enterprise Knowledge Graph comment ingérer les données.

Enterprise Knowledge Graph utilise un langage simple et lisible par l'homme appelé YARRRML pour définir les mappages entre le schéma source et les ontologies de graphe commun cible, schema.org.

Enterprise Knowledge Graph n'accepte que les mappages simples de type 1:1.

Les types d'entités suivants, qui correspondent aux types dans schema.org, sont acceptés :

Pour en savoir plus, consultez

Exemples de fichiers de mappage de schéma

Organisation

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/

mappings:
  Organization:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:company_$(record_id)
    po:
      - [a, schema:Organization]
      - [schema:name, $(company_name_in_source)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [ekg:recon.source_name, $(source_system)]
      - [ekg:recon.source_key, $(source_key)]

LocalBusiness

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  LocalBusiness:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:local_business_$(record_id)
    po:
      - [a, schema:LocalBusiness]
      - [schema:name, $(company_name_in_source)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [schema:url, $(url)]
      - [schema:telephone, $(telephone)]
      - [schema:latitude, $(latitude)]
      - [schema:longitude, $(longitude)]
      - [ekg:recon.source_name, $(source_system)]
      - [ekg:recon.source_key, $(source_key)]

Personne

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  Person:
    sources:
      - [example_project:example_dataset.example_table~bigquery]
    s: ekg:person_$(record_id)
    po:
      - [a, schema:Person]
      - [schema:postalCode, $(ZIP)]
      - [schema:birthDate, $(BIRTHDATE)]
      - [schema:name, $(NAME)]
      - [schema:gender, $(GENDER)]
      - [schema:streetAddress, $(ADDRESS)]
      - [ekg:recon.source_name, (Patients)]
      - [ekg:recon.source_key, $(source_key)]

Pour la chaîne source example_project:example_dataset.example_table~bigquery, ~bigquery est la chaîne fixe indiquant que la source de données provient de BigQuery.

Dans la liste des prédicats (po), ekg:recon.source_name et ekg:recon.source_key sont des noms de prédicats réservés utilisés par le système. Ils doivent toujours être mentionnés dans le fichier de mappage. Normalement, le prédicat ekg:recon.source_name prend une valeur constante pour la source ((Patients) dans cet exemple). Le prédicat ekg:recon.source_key prend la clé unique de la table source ($(source_key) dans cet exemple), qui représente la valeur de la variable à partir de l'ID de la colonne source.

Si vous devez définir plusieurs tables ou sources dans les fichiers de mappage, ou différents fichiers de mappage dans un même appel d'API, vous devez vous assurer que la valeur du sujet est unique pour chaque source. Vous pouvez utiliser la clé de colonne "préfixe + source" pour la rendre unique. Par exemple, si vous avez deux tables de personnes avec le même schéma, vous pouvez attribuer différents formats à la valeur du sujet (s) : ekg:person1_$(record_id) et ekg:person2_$(record_id).

Exemple de schéma de table

Voici un exemple de fichier de mappage :

prefixes:
  ekg: http://cloud.google.com/ekg/0.0.1#
  schema: https://schema.org/
mappings:
  organization:
    sources:
      - [ekg-api-test:demo.organization~bigquery]
    s: ekg:company_$(source_key)
    po:
      - [a, schema:Organization]
      - [schema:name, $(source_name)]
      - [schema:streetAddress, $(street)]
      - [schema:postalCode, $(postal_code)]
      - [schema:addressCountry, $(country)]
      - [schema:addressLocality, $(city)]
      - [schema:addressRegion, $(state)]
      - [ekg:recon.source_name, (org)]
      - [ekg:recon.source_key, $(primary_key)]

Dans cet exemple, le schéma de table lui-même ne contient pas le nom de cette source de données, qui correspond généralement au nom de la table ou de la base de données. Nous utilisons donc une chaîne statique "org" sans le signe dollar $.

Créer un job de rapprochement d'entités

Utilisez la console Google Cloud pour créer un job de rapprochement.

Ouvrez le tableau de bord Enterprise Knowledge Graph.

Accéder au tableau de bord Enterprise Knowledge Graph
Cliquez sur Mappage du schéma pour créer des fichiers de mappage à partir de notre modèle pour chacune de vos sources de données, puis enregistrez le fichier de mappage dans Cloud Storage.

Cliquez sur Job et Exécuter un job pour configurer les paramètres du job avant de le démarrer.

Type d'entité

Valeur	Nom du modèle	Description
`Organization`	`google_brasil`	Réconciliez les entités au niveau `Organization`. Par exemple, le nom d'une entreprise. Cela diffère de `LocalBusiness`, qui se concentre sur une branche, un point d'intérêt ou une présence physique en particulier (par exemple, l'un des nombreux campus d'une entreprise).
`LocalBusiness`	`google_cyprus`	Réconciliez une entité en fonction d'une branche, d'un point d'intérêt ou d'une présence physique spécifique. Il pourrait également prendre des coordonnées géographiques comme entrée de modèle.
`Person`	`google_atlantis`	Réconciliez l'entité personne en fonction d'un ensemble d'attributs prédéfinis dans `schema.org`.

Sources de données

Seules les tables BigQuery sont acceptées.

Destination

Le chemin de sortie doit être un ensemble de données BigQuery dans lequel Enterprise Knowledge Graph est autorisé à écrire.

Pour chaque job exécuté, Enterprise Knowledge Graph crée une table BigQuery avec un code temporel pour stocker les résultats.

Si vous utilisez l'API Entity Reconciliation, la réponse du job contient le nom et l'emplacement complets du tableau de sortie.

Si nécessaire, configurez les options avancées.
Pour démarrer le job, cliquez sur OK.

Surveiller l'état du job

Vous pouvez surveiller l'état du job depuis la console Google Cloud et l'API. L'exécution du job peut prendre jusqu'à 24 heures, selon le nombre d'enregistrements dans vos ensembles de données. Cliquez sur chaque job individuel pour afficher sa configuration détaillée.

UI de l'historique des jobs

Vous pouvez également inspecter l'état du job pour voir où se trouve l'étape actuelle.

État d'affichage du job	État du code	Description
En cours d'exécution	`JOB_STATE_RUNNING`	La tâche est en cours.
Extraction de connaissances	`JOB_STATE_KNOWLEDGE_EXTRACTION`	Enterprise Knowledge Graph extrait les données de BigQuery et crée des caractéristiques.
Prétraitement du rapprochement	`JOB_STATE_RECON_PREPROCESSING`	La tâche est à l'étape de prétraitement de la réconciliation.
Clustering	`JOB_STATE_CLUSTERING`	La tâche est à l'étape de clustering.
Exportation des clusters	`JOB_STATE_EXPORTING_CLUSTERS`	La tâche écrit la sortie dans l'ensemble de données de destination BigQuery.

La durée d'exécution de chaque job varie en fonction de nombreux facteurs, tels que la complexité des données, la taille de l'ensemble de données et le nombre d'autres jobs parallèles exécutés en même temps. Voici une estimation approximative du temps d'exécution des jobs par rapport à la taille de l'ensemble de données. La durée réelle d'exécution de votre job sera différente.

Nombre total d'enregistrements	Durée d'exécution
100 000	environ 2 heures
100 M	~16 heures
300M	~24 heures

Annuler un job de rapprochement

Vous pouvez cancel un job en cours d'exécution à la fois depuis la console Google Cloud (sur la page des détails du job) et depuis l'API. Enterprise Knowledge Graph arrête le job dès que possible, dans la mesure du possible. La réussite de la commande cancel n'est pas garantie.

Options avancées

Configuration	Description
Table BigQuery des résultats précédents	Si vous spécifiez une table de résultats précédente, l'ID de cluster reste stable dans différents jobs. Vous pouvez ensuite utiliser l'ID du cluster comme ID permanent.
Clustering d'affinité	Option recommandée dans la plupart des cas. Il s'agit d'une version parallèle du clustering hiérarchique agglomératif qui s'adapte très bien. Le nombre de tours de clustering (itérations) peut être spécifié dans la plage `[1, 5]`. Plus le nombre est élevé, plus l'algorithme a tendance à fusionner excessivement le cluster.
Regroupement des composants connectés	Option par défaut. Il s'agit d'une option alternative et ancienne. Ne l'essayez que si le clustering par affinité ne fonctionne pas bien sur votre ensemble de données. Le seuil de pondération peut être un nombre compris dans la plage `[0.6, 1]`.
Séparation de géocodage	Cette option permet de s'assurer que les entités de différentes régions géographiques ne sont pas regroupées.