Atelier 3 : Découvrir les marchandises perdues avec BigQuery Graph et Conversational Analytics

1. Introduction

Bienvenue dans la dernière étape de l'enquête sur la cargaison perdue ! Après avoir suivi la trace du conteneur volé de figurines Android de Londres à Sydney, l'enquête n'a pas abouti. En désactivant son transpondeur, le coffre-fort sécurisé intelligent du conteneur a déclenché un verrouillage d'urgence automatique.

Pour récupérer la cargaison de grande valeur avant qu'elle ne soit verrouillée pour toujours, votre mission consiste à trouver l'emplacement final du conteneur et à récupérer le code secret de déverrouillage manuel pour déverrouiller physiquement la soute.

Pour retrouver le conteneur manquant et sécuriser la cargaison, vous allez créer un graphique de propriétés BigQuery afin de suivre le parcours de l'envoi. Vous interrogerez ensuite ce réseau en langage naturel à l'aide de Conversational Analytics, puis vous effectuerez une recherche sémantique dans les métadonnées de vos données avec Knowledge Catalog pour localiser les codes de remplacement.

💡 Vous avez manqué l'atelier 1 ou l'atelier 2 ? Pas de panique ! Cet atelier est entièrement autonome. Les étapes de configuration de l'environnement provisionnent tout ce dont vous avez besoin pour que vous puissiez vous lancer directement et le faire de manière autonome.

Objectifs de l'atelier

• Clonez le dépôt et exécutez le script de configuration dans Google Cloud Shell.
• Créez un graphique de propriétés dans BigQuery en associant les données sur les entreprises, les navires et les manifestes.
• Utilisez Conversational Analytics pour interroger le graphique en langage naturel et suivre le parcours de la cargaison afin d'identifier l'opérateur responsable.
• Localisez le tableau contenant les codes de remplacement finaux à l'aide deKnowledge Catalog.
• Utilisez le contrôle des accès au niveau des colonnes de BigQuery pour démasquer et révéler le code final.

Prérequis

• Un navigateur Web (par exemple, Chrome)
• Un projet Google Cloud avec facturation activée
• Accès à Google Cloud Shell

Cet atelier de programmation s'adresse aux spécialistes des données de tous niveaux.

Les ressources créées dans cet atelier de programmation devraient coûter moins de 5 $.

Durée estimée : cet atelier de programmation prend environ 45 minutes.

2. Avant de commencer

Créer un projet Google Cloud

1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud.

Démarrer Cloud Shell

Vous utiliserez Google Cloud Shell pour télécharger le code, exécuter les scripts de configuration et déployer l'application.

1. Dans un nouvel onglet de navigateur, ouvrez Cloud Shell :

2. Une fois connecté, définissez votre ID de projet et confirmez votre environnement :

gcloud config set project <<YOUR_PROJECT_ID>>
export PROJECT_ID=$(gcloud config get-value project)
export REGION=us-central1

Un message de ce type doit s'afficher :

Your active configuration is: [cloudshell-####]
Updated property [core/project]

Activer les API requises

Exécutez la commande suivante dans Cloud Shell pour activer les API requises :

gcloud services enable \
 bigquery.googleapis.com \
 aiplatform.googleapis.com \
 datacatalog.googleapis.com  \
 geminidataanalytics.googleapis.com \
 cloudaicompanion.googleapis.com 

Si l'exécution réussit, un message semblable à celui-ci s'affiche :

Operation "operations/..." finished successfully.

3. Configurer votre environnement

Dans les ateliers précédents de cette série, nous avons préparé le terrain pour notre enquête.

1. Cloner le dépôt

Clonez le dépôt de l'atelier de programmation dans votre environnement Cloud Shell :

cd ~/
git clone --filter=blob:none --no-checkout https://github.com/GoogleCloudPlatform/devrel-demos.git
cd ~/devrel-demos
git sparse-checkout init --cone
git sparse-checkout set codelabs/bigquery-graph-analytics
git checkout main
cd codelabs/bigquery-graph-analytics/

2. Configurer des tables de base et des tags avec stratégie

Exécutez le script de configuration pour remplir votre ensemble de données BigQuery et appliquer des tags de sécurité au niveau des colonnes afin de restreindre les données sensibles :

bash setup_lab.sh

Vérifiez que la sortie dans votre terminal indique que l'initialisation a réussi :

🚀 Provisioning foundational tables and deploying Policy Tag security bindings...
🎯 Active Project: your-project-id
...
🎉 Success! Foundational tables initialized and Column-Level Policy Tags fully mapped out of the box!

Maintenant que votre environnement est configuré et que les données logistiques sont renseignées dans BigQuery, vous pouvez créer un graphique de propriétés pour connecter vos tables et suivre le parcours de la cargaison.

4. Connecter vos données à l'aide de BigQuery Graph

Pour analyser nos données sur la chaîne d'approvisionnement, nous allons définir la relation entre les entreprises, les navires et les manifestes. La création d'un graphique de propriétés nous permet d'interroger facilement ces connexions.

1. Comment les graphiques de propriétés modélisent-ils les relations ?

Un graphique de propriétés BigQuery modélise les réseaux à l'aide des éléments suivants :

• Nœuds : entités du réseau. Dans cet atelier, les nœuds représentent les entreprises (qui stockent directement les coordonnées), les manifestes et les navires.
• Arêtes : relations qui relient les nœuds. Par exemple :
  • Une arête relie un manifeste à un navire (via les relations dans la table manifests).
  • Une arête relie un navire à une entreprise (via les relations dans le tableau vessels).
• Propriétés : métadonnées stockées sur les nœuds ou les arêtes. Par exemple, un nœud Company comporte des colonnes telles que company_name et phone_number, et un nœud Manifest comporte seal_integrity_status et des coordonnées (last_ping_lat, last_ping_long).
• Libellés : noms de tags attribués aux nœuds (par exemple, Company, Vessel, Manifest) et aux arêtes (par exemple, CARRIED_BY, OPERATED_BY) afin que les outils de requête puissent reconnaître les types de nœuds et de relations.

2. Déployer le graphique de propriété dans BigQuery

Le fichier setup_graph.sql contient le langage de définition de données (LDD) SQL permettant de définir et de créer le graphique de propriétés, mais il est actuellement incomplet. Vous devez définir les libellés d'arête (relations) dans ce fichier de schéma avant de le compiler et de le déployer :

1. Ouvrir l'éditeur Cloud Shell

2. Ouvrez le fichier setup_graph.sql dans l'éditeur Cloud Shell.

3. Localisez les espaces réservés pour les libellés Edge :
   • Ligne 22 : remplacez `EDGE_TABLE_PLACEHOLDER` par un tag pertinent représentant la relation entre les manifestes et les navires (par exemple, CARRIED_BY).
   • Ligne 27 : remplacez `EDGE_TABLE_PLACEHOLDER` par un tag représentant la relation entre les navires et les entreprises (par exemple, OPERATED_BY).
4. Enregistrez le fichier.

Revenez maintenant au terminal Cloud Shell et déployez le graphique de propriétés mis à jour à l'aide du script terminé :

bq query --use_legacy_sql=false < setup_graph.sql

Vous devriez voir un résultat indiquant que le job est terminé :

Waiting on bqjob_r... ... (0s) Current status: DONE

Vous pouvez afficher les détails du graphique de propriété dans la console BigQuery :

Recherchez lost_cargo_dataset et sélectionnez "Graphs" (Graphiques) :

Maintenant que notre graphique de propriétés est compilé, passons à BigQuery Studio pour interroger et visualiser les connexions.

5. Interroger votre graphique

Vous pouvez interroger et explorer le graphe visuellement à l'aide du Graph Query Language (GQL) natif directement dans BigQuery Studio.

1. Interroger la chaîne conteneur > navire > entreprise

Explorons les requêtes GQL en recherchant qui exploite les navires transportant des marchandises. Pour trouver l'opérateur, vous devez parcourir trois nœuds d'entité distincts dans notre réseau logistique :

1. Commencez par le nœud de conteneur Manifest.
2. Suivez l'arête de relation CARRIED_BY pour trouver le Vessel de transport.
3. Suivez l'arête de relation OPERATED_BY de ce navire jusqu'à l'Company responsable et récupérez son ID.

Commençons par exécuter une requête pour visualiser l'ensemble du réseau (sans aucun filtre) afin d'afficher le graphique complet.

1. Ouvrez un nouvel onglet dans l'éditeur SQL de BigQuery Studio, collez la requête GQL suivante, puis cliquez sur Exécuter :

   SELECT * FROM GRAPH_TABLE(
     `lost_cargo_dataset.logistics_network`
     MATCH p = (m:Manifest)-[:CARRIED_BY]->(v:Vessel)-[:OPERATED_BY]->(comp:Company)
     RETURN TO_JSON(p) AS path
   );
   

2. Une fois la requête terminée, dans le volet Résultats de la requête en bas de l'écran, cliquez sur l'onglet Graphique (à côté de l'onglet Tableau de résultats).

3. BigQuery affiche les résultats sous forme de graphique visuel interactif. Faites un zoom avant pour afficher l'ensemble du réseau de conteneurs, de navires et d'opérateurs connectés.

Anatomie d'une requête GQL

Analysons la requête GQL que nous venons d'exécuter :

• GRAPH_TABLE : indique à BigQuery d'exécuter une requête de graphique de propriété sur le graphique logistics_network.
• MATCH : déclare le modèle de traversée multihop. Nous commençons par un Manifest (m), faisons correspondre la relation d'arête :CARRIED_BY pointant vers Vessel (v), puis faisons correspondre la relation d'arête :OPERATED_BY pointant vers Company (comp).
• GQL remplace la logique de jointure complexe par des flèches de relation intuitives en ASCII-art lisibles par l'homme ()->[]->(), ce qui simplifie considérablement l'écriture et l'optimisation des requêtes multihops.
• RETURN : renvoie les propriétés ou le chemin JSON des éléments correspondants.

2. Filtrer les résultats des requêtes GQL

Maintenant, filtrons la requête pour n'examiner que le chemin d'accès au conteneur compromis cible MV-CAPYBARA-003.

1. Collez la requête suivante dans l'éditeur SQL, puis cliquez sur Exécuter :

   SELECT * FROM GRAPH_TABLE(
     `lost_cargo_dataset.logistics_network`
     MATCH p = (m:Manifest {shipment_id: 'MV-CAPYBARA-003'})-[:CARRIED_BY]->(v:Vessel)-[:OPERATED_BY]->(comp:Company)
     RETURN TO_JSON(p) AS path
   );
   

2. Cliquez sur l'onglet Graphique sous les résultats.

3. Le lecteur n'affiche désormais que le chemin de traversée actif pour MV-CAPYBARA-003. Faites un zoom avant pour afficher les nœuds et les connexions :
   • Double-cliquez sur le nœud Company pour ouvrir le panneau des propriétés. Sous Propriétés, vous verrez l'opérateur company_id : 103 (Davy Jones Shipping). Notez cet ID d'entreprise, car vous en aurez besoin plus tard pour récupérer le code secret d'autorisation dans le registre de sécurité.
   • Double-cliquez sur le nœud Vessel pour vérifier qu'il s'agit bien de Flying Dutchman.

Vérification de l'état :

• Ce que nous avons fait : nous avons interrogé notre réseau de graphiques de propriétés pour localiser l'opérateur du navire transportant l'envoi manquant (company_id: 103 / Davy Jones Shipping).
• Prochaine étape : explorez davantage notre graphique pour déterminer la destination du navire piraté.

6. Discuter avec votre graphique à l'aide de Conversational Analytics

Maintenant que vous avez interrogé manuellement votre graphique pour trouver l'ID de l'entreprise, utilisons Conversational Analytics pour discuter directement avec notre graphique et identifier la destination de notre conteneur.

1. Démarrer une session Conversational Analytics

1. Dans la console Google Cloud, accédez à la console BigQuery, puis développez le panneau des ressources pour trouver votre ensemble de données (lost_cargo_dataset).
2. Cliquez sur votre ressource Property Graph : logistics_network.
3. Dans la barre d'outils du panneau de détails en haut de l'écran, cliquez sur le bouton Chat. Une session Conversational Analytics s'ouvre, préchargée avec le contexte de votre graphique.

Conseil : L'agent Conversational Analytics lit automatiquement la structure de votre graphique et précharge son contexte lorsque vous cliquez sur "Chat".

2. Localisez le port d'amarrage le plus proche du conteneur piraté.

Un avion de patrouille maritime vient de repérer un navire correspondant à la description de notre cargo, qui navigue hors réseau (avec son transpondeur désactivé) aux coordonnées POINT(-122.48 37.55). Pour intercepter la cargaison, nous devons trouver le port d'amarrage le plus proche où opère le syndicat de l'ombre Davy Jones Shipping.

Au lieu de rechercher manuellement tous les ports du monde, nous interrogerons notre réseau de graphiques pour extraire les ports connectés à la flotte active du syndicat et déterminer celui qui est physiquement le plus proche de l'observation.

1. Dans la zone de discussion Conversational Analytics, saisissez le prompt suivant :

   Find all ports associated with Davy Jones Shipping vessels. Which port is closest to coordinate POINT(-122.48 37.55), show the distance in km, and display it on a map.
   

2. Examinez attentivement la réponse. L'agent parcourt le graphique et renvoie l'installation d'accueil la plus proche et sa distance :
   • Port de recharge : Mountain View Terminal
   • Distance : 39.42 kilometers
3. Comme Conversational Analytics est optimisé par Gemini avec une intégration géospatiale (SIG) native, il peut interpréter les points de coordonnées géographiques et exploiter ses connaissances du monde pour vérifier l'emplacement :"Le navire se trouve à environ 39,42 kilomètres du terminal de Mountain View, en Californie, ce qui indique qu'il s'y dirige pour accoster."

Cela confirme que notre cargaison est en route pour Mountain View !

En coulisses : Graph Query Language (GQL) et SIG géospatial

En coulisses, l'agent d'analyse conversationnelle a compilé et exécuté de manière dynamique une requête combinant la correspondance du chemin du graphique et les calculs de distance géospatiale. Pour ce faire, utilisez une clause COLUMNS GQL native, en calculant la distance géodésique de manière native dans la correspondance de parcours du graphe :

SELECT port_id, port_name, country, latitude, longitude, distance_km 
FROM GRAPH_TABLE(
  `lost_cargo_dataset.logistics_network`
  MATCH (c:Company)<-[]-(v:Vessel)-[]->(p:Port)
  WHERE LOWER(c.company_name) = 'davy jones shipping'
  COLUMNS (
    p.port_id, 
    p.port_name, 
    p.country, 
    p.latitude, 
    p.longitude, 
    ROUND(ST_DISTANCE(ST_GEOGPOINT(p.longitude, p.latitude), ST_GEOGPOINT(-122.48, 37.55)) / 1000, 2) AS distance_km
  )
)
ORDER BY distance_km ASC;

En combinant les fonctions géospatiales (SIG) natives (ST_DISTANCE, ST_GEOGPOINT) avec une correspondance de graphique de propriétés GQL, BigQuery résout dynamiquement l'empreinte opérationnelle du syndicat et calcule la proximité physique réelle dans une seule requête.

Vérification de l'état :

• Ce que nous avons accompli : nous avons utilisé Conversational Analytics pour suivre les ports d'amarrage de la flotte de l'opérateur fantôme (Manifest ➔ Vessel ➔ Company ➔ Docks) et avons calculé que le vaisseau suspect se dirigeait directement vers le terminal de Mountain View (à seulement 39 km).
• Ce que nous devons faire ensuite : trouver le registre de données qui contient le code de remplacement manuel afin que notre équipe d'intervention tactique locale puisse intercepter l'envoi et déverrouiller manuellement le conteneur une fois qu'il sera à quai au terminal de Mountain View.

7. Retrouver vos données manquantes avec Knowledge Catalog

Le graphique de propriétés affiche les relations, mais ne contient pas le tableau dans lequel les codes de remplacement réels sont stockés.

Dans un véritable environnement d'entreprise avec des centaines d'ensembles de données et de tables, il peut être difficile de trouver ces informations. Nous allons utiliser Knowledge Catalog pour effectuer une recherche sémantique et localiser la table appropriée.

1. Recherche sémantique dans Knowledge Catalog

1. Dans la console Google Cloud, recherchez Knowledge Catalog ➔ Rechercher et accédez-y.
2. Dans la colonne des filtres de recherche, sous Systèmes, cochez BigQuery pour affiner les résultats.
3. Dans le champ de recherche, saisissez la requête suivante :

   container override codes
   

4. Cliquez sur la ressource de table maritime_security_registry qui apparaît dans les résultats de recherche :

En inspectant le schéma des métadonnées, vous verrez que le tableau contient des colonnes pour les données de sécurité des conteneurs, telles que l'entreprise coordinatrice co_id, le jeton de dépositaire cust_tok et, surtout, la colonne du code secret de remplacement du conteneur sécurisé clc_ovr_cd.

Nous avons réussi à localiser la table et la colonne sécurisée exactes dont nous avons besoin pour récupérer notre cargaison.

Dans les coulisses : mise en correspondance sémantique : le nom de la table (maritime_security_registry) et celui de sa colonne clé (clc_ovr_cd) sont complètement obscurs. Sans l'analyse de la recherche sémantique de Knowledge Catalog pour la description de la colonne ("Code secret de remplacement du conteneur sécurisé"), il aurait été presque impossible de trouver ce tableau en recherchant "codes de remplacement".

🔓 Gouvernance dans le monde réel : dans un environnement de production d'entreprise, les équipes de sécurité et de gouvernance utilisent également :

• Aspects et modèles de tag : pour associer des métadonnées métier (comme Propriétaire des données, Période de conservation ou Classification des informations permettant d'identifier personnellement l'utilisateur) aux schémas de table.
• Traçabilité des données : pour générer automatiquement des organigrammes visuels représentant la façon dont les tables telles que maritime_security_registry sont interrogées et utilisées par les systèmes en aval.

2. Inspecter la sécurité des colonnes dans BigQuery

1. Revenez à la console BigQuery.
2. Dans l'onglet Explorateur, sélectionnez lost_cargo_dataset, puis cliquez sur la table maritime_security_registry.
3. Cliquez sur l'onglet Schéma.

4. Notez que la colonne clc_ovr_cd est sécurisée par un tag avec stratégie nommé MaskShippingDetails (listé dans la colonne "Tags avec stratégie").
5. Ouvrez un nouvel onglet de l'éditeur SQL dans BigQuery et essayez d'afficher les codes de remplacement du registre en exécutant la requête suivante :

   SELECT * FROM `lost_cargo_dataset.maritime_security_registry` 
   WHERE co_id = 103;
   

6. Étant donné que votre compte ne dispose pas encore des autorisations nécessaires pour lire les colonnes taguées avec MaskShippingDetails, la requête échouera immédiatement et générera une erreur de sécurité de base de données Accès refusé :

Vérification de l'état :

• Ce que nous avons accompli : nous avons trouvé la table sécurisée (maritime_security_registry) et la colonne (clc_ovr_cd) contenant le code de remplacement.
• Procédure à suivre : accordez à votre compte des autorisations de lecture pour la colonne sécurisée.

8. Forcer la sécurité des colonnes pour récupérer le code secret

Pour lire le code de remplacement final en texte clair, nous devons accorder à notre compte utilisateur l'autorisation de lire les colonnes taguées avec MaskShippingDetails.

1. Accorder des autorisations sur les tags avec stratégie

1. Dans le panneau de navigation de gauche de la console BigQuery, accédez à Tags avec stratégie.
2. Sélectionnez la taxonomie nommée LostCargoSecurity_.
3. Dans la liste des balises, cliquez sur MaskShippingDetails.
4. Dans le panneau d'informations à droite de l'écran, cliquez sur Ajouter un compte principal. (Si le panneau est masqué, cliquez sur Afficher le panneau d'informations en haut à droite.)
5. Dans le champ Nouveaux comptes principaux, saisissez l'adresse e-mail de votre utilisateur Google Cloud actif.
6. Dans le menu déroulant Sélectionner un rôle, recherchez et sélectionnez Lecteur ultraprécis, puis cliquez sur Enregistrer.

2. Demander le code de remplacement

Revenez à l'éditeur de l'espace de travail BigQuery. Étant donné que vous disposez désormais d'un accès Lecteur détaillé, nous devrions pouvoir exécuter à nouveau la requête et afficher les données non masquées :

SELECT *  FROM `lost_cargo_dataset.maritime_security_registry` 
WHERE co_id = 103;

🔓 Résultat

La requête renvoie le code de remplacement non masqué :

SHIVER-ME-TIMBERS-888

Mission accomplie ! 🚢

Félicitations ! En combinant les graphiques de propriétés BigQuery et l'analyse conversationnelle avec Knowledge Catalog et la sécurité au niveau des colonnes, vous avez réussi à suivre la flotte fantôme et à extraire le code de remplacement du conteneur sécurisé.

L'équipe d'interception tactique a été dépêchée au terminal de Mountain View. Une fois le code secret déchiffré, ils sont prêts à déverrouiller le conteneur Capybara, à sécuriser la cargaison et à récupérer nos biens perdus.

9. Effectuer un nettoyage

Pour éviter que des frais ne vous soient facturés, nettoyez les ressources du bac à sable créées pendant cet atelier.

Revenez au terminal Cloud Shell et supprimez l'ensemble de données BigQuery contenant les tables logistiques :

bq rm -r -f -d lost_cargo_dataset

Supprimez les fichiers du dépôt cloné :

cd ..
rm -rf data-cloud-roadshow-26

10. Félicitations

Vous avez réussi à résoudre le problème et à récupérer le code de remplacement de l'autorisation.

Connaissances acquises

• Découvrez comment créer un graphique de propriétés dans BigQuery pour représenter des entités et des relations complexes.
• Comment les nœuds, les arêtes, les propriétés et les libellés sont configurés pour capturer les connexions de données.
• Découvrez comment interroger des graphiques de propriétés en langage naturel avec Conversational Analytics dans BigQuery.
• Structure des expressions Graph Query Language (GQL) pour parcourir les chemins relationnels.
• Découvrez comment trouver des composants sécurisés à l'aide de Knowledge Catalog et accéder aux données dont l'accès au niveau des colonnes est limité à l'aide de tags avec stratégie.

Liens vers les ressources

• Présentation de BigQuery Conversational Analytics
• Documentation de référence sur la syntaxe des graphiques de propriétés BigQuery
• Intégration de Knowledge Catalog