Lab 3: Scoprire il carico smarrito con BigQuery Graph e l'analisi conversazionale

1. Introduzione

Benvenuto nella fase finale dell'indagine sul carico smarrito. Dopo aver seguito le tracce del container rubato di statuette Android da Londra fino a Sydney, la pista si è raffreddata. Disattivando il transponder, la cassaforte di sicurezza intelligente del container ha attivato un blocco di emergenza automatico.

Per recuperare il carico di valore prima che venga chiuso per sempre, la tua missione è trovare la posizione finale del container e recuperare il passcode di override manuale per sbloccare fisicamente la cassaforte.

Per trovare il container mancante e mettere in sicurezza il carico, creerai un grafico delle proprietà BigQuery per tracciare il percorso della spedizione. A questo punto, interrogherai questa rete in linguaggio naturale utilizzando Conversational Analytics e terminerai eseguendo una ricerca semantica nei metadati dei tuoi dati con Knowledge Catalog per individuare i codici di override.

💡 Hai perso Lab 1 o Lab 2? Non preoccuparti. Questo lab è completamente autonomo. I passaggi di configurazione dell'ambiente eseguiranno il provisioning di tutto ciò di cui hai bisogno, in modo che tu possa iniziare subito e completare l'operazione in autonomia.

In questo lab proverai a:

• Clona il repository ed esegui lo script di configurazione in Google Cloud Shell.
• Crea un grafico delle proprietà in BigQuery collegando i dati di società, navi e manifesti.
• Utilizza l'analisi conversazionale per eseguire query sul grafico in linguaggio naturale, tracciando il percorso del carico per identificare l'operatore responsabile.
• Individua la tabella contenente i codici di override finali utilizzando Knowledge Catalog.
• Utilizza il controllo dell'accesso a livello di colonna BigQuery per smascherare e rivelare il codice finale.

Che cosa ti serve

• Un browser web come Chrome
• Un progetto cloud Google Cloud con la fatturazione abilitata
• Accesso a Google Cloud Shell

Questo codelab è progettato per i professionisti dei dati di tutti i livelli.

Le risorse create in questo codelab dovrebbero costare meno di 5 $.

Durata stimata:il completamento di questo codelab richiede circa 45 minuti.

2. Prima di iniziare

Crea un progetto Google Cloud

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud.

Avvia Cloud Shell

Utilizzerai Google Cloud Shell per scaricare il codice, eseguire gli script di configurazione e implementare l'applicazione.

1. In una nuova scheda del browser, apri Cloud Shell:

2. Una volta connesso, imposta l'ID progetto e conferma l'ambiente:

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

Dovresti visualizzare un messaggio simile al seguente:

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

Abilita le API richieste

Esegui questo comando in Cloud Shell per abilitare le API richieste:

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

Se l'esecuzione va a buon fine, dovresti visualizzare un messaggio simile a questo:

Operation "operations/..." finished successfully.

3. Configura l'ambiente

Nei lab precedenti di questa serie, abbiamo gettato le basi per la nostra indagine.

1. Clona il repository

Clona il repository del codelab nel tuo ambiente 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. Configura tabelle di base e tag di policy

Esegui lo script di configurazione per popolare il set di dati BigQuery e applica i tag di sicurezza a livello di colonna per limitare i dati sensibili:

bash setup_lab.sh

Verifica che l'output nel terminale mostri l'inizializzazione riuscita:

🚀 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!

Ora che l'ambiente è stato configurato correttamente e i dati logistici sono stati inseriti in BigQuery, puoi creare un grafico delle proprietà per connettere le tabelle e tracciare il percorso del carico.

4. Connettere i dati utilizzando BigQuery Graph

Per analizzare i nostri dati della catena di fornitura, definiremo la relazione tra aziende, navi e manifesti. La creazione di un grafico delle proprietà ci consente di eseguire facilmente query su queste connessioni.

1. Come i grafici delle proprietà modellano le relazioni

Un grafico delle proprietà BigQuery modella le reti utilizzando:

• Nodi: le entità nella rete. In questo lab, i nodi rappresentano Aziende (che memorizzano direttamente i dati di contatto), Manifesti e Navi.
• Archi: le relazioni che collegano i nodi. Ad esempio:
  • Un bordo collega un Manifest a una Vessel (tramite le relazioni nella tabella manifests).
  • Un arco collega un Vessel a una Company (tramite le relazioni nella tabella vessels).
• Proprietà: metadati memorizzati su nodi o archi. Ad esempio, un nodo Company ha colonne come company_name e phone_number, mentre un nodo Manifest ha seal_integrity_status e coordinate (last_ping_lat, last_ping_long).
• Etichette: nomi dei tag assegnati a nodi (ad es. Company, Vessel, Manifest) e archi (ad es. CARRIED_BY, OPERATED_BY) in modo che gli strumenti di query possano riconoscere i tipi di nodi e relazioni.

2. Deployment del grafico delle proprietà in BigQuery

Il file setup_graph.sql contiene il DDL SQL per definire e creare il grafico delle proprietà, ma al momento è incompleto. Prima di compilare e implementare questo file di schema, devi definire le etichette dei bordi (relazioni):

1. Aprire l'editor di Cloud Shell.

2. Apri il file setup_graph.sql nell'editor di Cloud Shell.

3. Individua i segnaposto per le etichette degli archi:
   • Riga 22: sostituisci `EDGE_TABLE_PLACEHOLDER` con un tag significativo che rappresenti la relazione tra i manifest e le navi (ad es. CARRIED_BY).
   • Riga 27: sostituisci `EDGE_TABLE_PLACEHOLDER` con un tag che rappresenti il rapporto tra le navi e le società (ad es. OPERATED_BY).
4. Salva il file.

Ora, torna al terminale Cloud Shell e esegui il deployment del grafico delle proprietà aggiornato utilizzando lo script completato:

bq query --use_legacy_sql=false < setup_graph.sql

Dovresti vedere un output che indica che il job è stato completato:

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

Puoi visualizzare i dettagli del grafico delle proprietà nella console BigQuery:

Trova lost_cargo_dataset e seleziona Grafici:

Ora che il grafico della proprietà è stato compilato correttamente, possiamo passare a BigQuery Studio per eseguire query e visualizzare le connessioni.

5. Eseguire query sul grafico

Puoi eseguire query ed esplorare il grafico visivamente utilizzando il Graph Query Language (GQL) nativo direttamente in BigQuery Studio.

1. Esegui una query sulla catena contenitore -> nave -> azienda

Esploriamo le query GQL trovando chi gestisce le navi che trasportano merci. Per trovare l'operatore è necessario attraversare tre nodi di entità separati nella nostra rete logistica:

1. Inizia dal nodo del container Manifest.
2. Segui il bordo della relazione CARRIED_BY per trovare il valore di Vessel.
3. Segui il bordo della relazione OPERATED_BY da questa nave al Company responsabile e recupera il suo ID.

Innanzitutto, eseguiamo una query per visualizzare l'intera rete (senza filtri) per vedere il grafico completo.

1. Apri una nuova scheda nell'editor SQL di BigQuery Studio, incolla la seguente query GQL e fai clic su Esegui:

   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. Una volta completata la query, nel riquadro Risultati query in basso, fai clic sulla scheda Grafico (accanto alla scheda Tabella dei risultati).

3. BigQuery esegue il rendering dei risultati come rappresentazione grafica visiva interattiva. Aumenta lo zoom per visualizzare l'intera rete di container, navi e operatori connessi.

Anatomia di una query GQL

Analizziamo la query GQL che abbiamo appena eseguito:

• GRAPH_TABLE: indica a BigQuery di eseguire una query del grafico delle proprietà sul grafico logistics_network.
• MATCH: dichiara il pattern di attraversamento multihop. Partiamo da Manifest (m), abbiniamo la relazione edge :CARRIED_BY che punta a Vessel (v), quindi abbiniamo la relazione edge :OPERATED_BY che punta a Company (comp).
• GQL sostituisce la complessa logica di join con frecce di relazione ASCII-art intuitive e leggibili ()->[]->(), semplificando notevolmente la scrittura e l'ottimizzazione delle query multihop.
• RETURN: restituisce le proprietà o il percorso JSON degli elementi corrispondenti.

2. Filtrare i risultati delle query GQL

Ora filtriamo la query in modo da esaminare solo il percorso del nostro container compromesso di destinazione MV-CAPYBARA-003.

1. Incolla la seguente query nell'editor SQL e fai clic su Esegui:

   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. Fai clic sulla scheda Grafico sotto i risultati.

3. Il visualizzatore ora mostra solo il percorso di attraversamento attivo per MV-CAPYBARA-003. Aumenta lo zoom per visualizzare i nodi e le connessioni:
   • Fai doppio clic sul nodo Company per aprire il riquadro delle proprietà. In Proprietà, vedrai l'operatore company_id: 103 (Davy Jones Shipping). Prendi nota di questo ID società: ti servirà in seguito per recuperare la password di autorizzazione dal registro di sicurezza.
   • Fai doppio clic sul nodo Vessel per verificare che sia Flying Dutchman.

Controllo dello stato:

• Obiettivo raggiunto: abbiamo eseguito una query sulla nostra rete di grafici delle proprietà per individuare l'operatore della nave che trasportava la spedizione mancante (company_id: 103 / Davy Jones Shipping).
• Passaggi successivi: esplora ulteriormente il grafico per individuare la destinazione della nave compromessa.

6. Chattare con il grafico utilizzando Conversational Analytics

Ora che hai eseguito manualmente una query sul grafico per trovare l'ID azienda, utilizziamo Analisi conversazionale per comunicare direttamente con il grafico e individuare la destinazione del nostro container.

1. Avviare una sessione di Analisi conversazionale

1. Nella console Google Cloud, vai alla console BigQuery ed espandi il riquadro delle risorse per trovare il tuo set di dati (lost_cargo_dataset).
2. Fai clic sulla risorsa del grafico delle proprietà: logistics_network.
3. Nella barra degli strumenti del riquadro dei dettagli in alto, fai clic sul pulsante Chat. Si apre una sessione di Conversational Analytics precaricata con il contesto del grafico.

Suggerimento: l'agente di Analisi conversazionale legge automaticamente la struttura del grafico, precaricando il contesto quando fai clic su Chat.

2. Individua il porto di attracco più vicino per il container compromesso

Un aereo di pattugliamento marittimo ha appena avvistato un'imbarcazione corrispondente alla descrizione della nostra nave cargo che naviga off-grid (con il transponder disattivato) alle coordinate POINT(-122.48 37.55). Per intercettare il carico, dobbiamo trovare il porto di attracco più vicino in cui opera il sindacato ombra Davy Jones Shipping.

Anziché cercare manualmente tutti i porti globali, eseguiamo una query sulla nostra rete di grafici per estrarre i porti collegati alla flotta attiva del sindacato e misurare quale è fisicamente più vicino all'avvistamento.

1. Nella casella di chat di Analisi conversazionale, inserisci il seguente prompt:

   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. Esamina attentamente la risposta. L'agente attraversa il grafico e restituisce la struttura di attracco più vicina e la relativa distanza:
   • Porta di aggancio: Mountain View Terminal
   • Distanza: 39.42 kilometers
3. Poiché Conversational Analytics è basato su Gemini con integrazione geospaziale (GIS) nativa, può interpretare i punti delle coordinate geografiche e sfruttare la sua conoscenza del mondo per verificare la posizione:"La nave si trova a circa 39,42 chilometri dal terminal di Mountain View, in California, il che indica che si sta dirigendo lì per attraccare".

Confermiamo che il nostro carico è diretto a Mountain View.

Funzionamento interno: Graph Query Language (GQL) e GIS geospaziale

Dietro le quinte, l'agente Conversational Analytics ha compilato ed eseguito dinamicamente una query che combina la corrispondenza del percorso del grafico con i calcoli della distanza geospaziale. Ciò si ottiene utilizzando una clausola COLUMNS GQL nativa, calcolando la distanza geodetica in modo nativo all'interno della corrispondenza di attraversamento del grafico:

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;

Combinando le funzioni geospaziali (GIS) native (ST_DISTANCE, ST_GEOGPOINT) con una corrispondenza del grafico delle proprietà GQL, BigQuery risolve dinamicamente l'impronta operativa del sindacato e calcola la prossimità fisica nel mondo reale in un'unica query.

Controllo dello stato:

• Cosa abbiamo ottenuto: abbiamo utilizzato Conversational Analytics per tracciare i porti di attracco della flotta dell'operatore ombra (Manifest ➔ Vessel ➔ Company ➔ Docks) e abbiamo calcolato che la nave sospetta si sta dirigendo direttamente al terminale di Mountain View (a soli 39 km di distanza).
• Cosa dobbiamo fare ora: trovare il registro dei dati che contiene il codice di override manuale in modo che la nostra squadra di intervento tattico locale possa intercettare la spedizione e sbloccare manualmente il container una volta attraccato al terminal di Mountain View.

7. Trovare i dati mancanti con Knowledge Catalog

Il grafico delle proprietà mostra le relazioni, ma non contiene la tabella in cui sono memorizzati i codici di override effettivi.

In un ambiente aziendale reale con centinaia di set di dati e tabelle, trovare queste informazioni può essere difficile. Utilizzeremo Knowledge Catalog per eseguire una ricerca semantica e individuare la tabella corretta.

1. Ricerca semantica in Knowledge Catalog

1. Nella console Google Cloud, cerca e vai a Knowledge Catalog ➔ Ricerca.
2. Nella colonna filtro di ricerca in Sistemi, seleziona BigQuery per restringere i risultati.
3. Nella casella di ricerca, inserisci la seguente query:

   container override codes
   

4. Fai clic sulla risorsa tabella maritime_security_registry visualizzata nei risultati di ricerca:

Se esamini lo schema dei metadati, vedrai che la tabella contiene colonne per i dati di sicurezza del container, come l'azienda coordinatrice co_id, il token del custode cust_tok e, soprattutto, la colonna del passcode di override del container sicuro: clc_ovr_cd.

Abbiamo trovato sia il tavolo che la colonna sicura esatta di cui abbiamo bisogno per recuperare il carico.

Under the Hood: Semantic Matching: il nome della tabella (maritime_security_registry) e il nome della colonna chiave (clc_ovr_cd) sono completamente oscuri. Senza l'analisi della ricerca semantica di Knowledge Catalog della descrizione della colonna ("Secure container override passcode"), trovare questa tabella cercando "codici di override" sarebbe stato quasi impossibile.

🔓 Governance reale: in un ambiente aziendale di produzione, i team di sicurezza e governance sfruttano anche:

• Aspetti e modelli di tag: per allegare metadati aziendali (ad esempio Proprietario dei dati, Periodo di conservazione o Classificazione PII) agli schemi delle tabelle.
• Data Lineage: per generare automaticamente diagrammi di flusso visivi che rappresentano il modo in cui le tabelle come maritime_security_registry vengono interrogate e utilizzate dai sistemi downstream.

2. Ispeziona la sicurezza delle colonne in BigQuery

1. Torna alla console BigQuery.
2. Nella scheda Explorer, seleziona lost_cargo_dataset e fai clic sulla tabella maritime_security_registry.
3. Fai clic sulla scheda Schema.

4. Tieni presente che la colonna clc_ovr_cd è protetta da un tag di policy denominato MaskShippingDetails (elencato nella colonna Tag di policy).
5. Apri una nuova scheda dell'editor SQL in BigQuery e prova a visualizzare i codici di override del registro eseguendo la seguente query:

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

6. Poiché il tuo account non dispone ancora delle autorizzazioni per leggere le colonne taggate con MaskShippingDetails, la query avrà esito negativo immediato con un errore di sicurezza del database Accesso negato:

Controllo dello stato:

• Obiettivo raggiunto: abbiamo trovato la tabella sicura (maritime_security_registry) e la colonna (clc_ovr_cd) contenente il codice di override.
• Passaggi successivi: concedi al tuo account le autorizzazioni di lettura per la colonna protetta.

8. Violazione della sicurezza delle colonne per recuperare il passcode

Per leggere il codice di override finale in testo non crittografato, dobbiamo concedere al nostro account utente l'autorizzazione per leggere le colonne taggate con MaskShippingDetails.

1. Concedi autorizzazioni per i tag di policy

1. Nel riquadro di navigazione a sinistra della console BigQuery, vai a Tag di policy.
2. Seleziona la tassonomia denominata LostCargoSecurity_.
3. Nell'elenco dei tag, fai clic su MaskShippingDetails.
4. Nel riquadro Informazioni sul lato destro dello schermo, fai clic su Aggiungi entità. Se il pannello è nascosto, fai clic su Mostra riquadro informazioni in alto a destra.
5. Nel campo Nuove entità, inserisci l'email dell'utente Google Cloud attivo.
6. Nel menu a discesa Seleziona un ruolo, cerca e seleziona Lettore granulare, poi fai clic su Salva.

2. Query per il codice di override

Torna all'editor dello spazio di lavoro BigQuery. Ora che hai un accesso in lettura granulare, dovremmo essere in grado di eseguire di nuovo la query e visualizzare i dati non mascherati:

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

🔓 Risultato

La query restituisce il codice di override non mascherato:

SHIVER-ME-TIMBERS-888

Missione compiuta. 🚢

Complimenti! Combinando i grafi delle proprietà di BigQuery e l'analisi conversazionale con Knowledge Catalog e la sicurezza a livello di colonna, hai monitorato correttamente il parco risorse ombra ed estratto il codice di override del container sicuro.

La squadra di intercettazione tattica è stata inviata al terminale di Mountain View. Armata del codice di override decriptato, è pronta ad aprire il container dei capibara, mettere in sicurezza il carico e recuperare con successo i nostri beni smarriti.

9. Esegui la pulizia

Per evitare addebiti, libera spazio dalle risorse sandbox create durante questo lab.

Torna al terminale Cloud Shell ed elimina il set di dati BigQuery contenente le tabelle di logistica:

bq rm -r -f -d lost_cargo_dataset

Rimuovi i file del repository clonato:

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

10. Complimenti

Hai risolto correttamente l'indagine e recuperato il codice di override dell'autorizzazione.

Cosa hai imparato

• Come creare un grafico delle proprietà in BigQuery per rappresentare entità e relazioni complesse.
• Come vengono configurati nodi, archi, proprietà ed etichette per acquisire le connessioni di dati.
• Come eseguire query sui grafici delle proprietà utilizzando il linguaggio naturale con Analisi conversazionale di BigQuery.
• Come sono strutturate le espressioni Graph Query Language (GQL) per attraversare i percorsi relazionali.
• Come scoprire gli asset protetti utilizzando Knowledge Catalog e accedere ai dati con limitazioni a livello di colonna utilizzando i tag di policy.

Link delle risorse

• Panoramica dell'analisi conversazionale di BigQuery
• Riferimento per la sintassi dei grafici delle proprietà di BigQuery
• Integrazione di Knowledge Catalog