Gestire i metadati di lake, zone e asset

Questa guida descrive i metadati di Knowledge Catalog (in precedenza Dataplex Universal Catalog) per lake, zone e asset e come utilizzare l'API Dataplex per gestirli.

Attenzione:l'importazione di entità Knowledge Catalog in laghi e zone in Data Catalog (incluse quelle create come output di Knowledge Catalog Discovery) è deprecata e non funzionerà più entro il 30 settembre 2025. Le tabelle esterne in BigQuery pubblicate da Discovery verranno importate in Knowledge Catalog come voci.

Panoramica

Knowledge Catalog esegue la scansione di quanto segue:

• Asset di dati strutturati e semi-strutturati all'interno dei data lake, per estrarre i metadati della tabella nelle entità tabella
• Dati non strutturati, come immagini e testi, per estrarre i metadati del fileset nelle entità fileset

Puoi utilizzare l'API Dataplex Metadata per:

• Visualizzare, modificare ed eliminare i metadati delle entità tabella e set di file
• Creare metadati di entità di tabella o fileset

Puoi analizzare i metadati di Knowledge Catalog utilizzando quanto segue:

• Data Catalog (deprecato) per la ricerca e il tagging
• Dataproc Metastore e BigQuery per l'elaborazione di query e analisi dei metadati delle tabelle

API Dataplex

Questa sezione riassume le risorse lake, zona e asset nell'API Dataplex e le risorse chiave associate.

API Control Plane

L'API del control plane Dataplex consente la creazione e la gestione delle risorse lake, zona e asset.

• Lake: Un'istanza del servizio Knowledge Catalog che consente di gestire le risorse di archiviazione in tutti i progetti di un'organizzazione.

• Zona: Un raggruppamento logico di asset all'interno di un lake. Utilizza più zone all'interno di un lake per organizzare i dati in base alla preparazione, al carico di lavoro o alla struttura dell'organizzazione.

• Asset: Risorse di archiviazione, con dati archiviati in bucket Cloud Storage o set di dati BigQuery, collegati a una zona all'interno di un lake.

API Metadata

Utilizza l'API Dataplex Metadata per creare e gestire i metadati all'interno di entità e partizioni di tabelle e set di file. Knowledge Catalog analizza gli asset di dati, in un lake o forniti da te, per creare entità e partizioni. Entità e partizioni mantengono i riferimenti alle risorse associate e alle posizioni di archiviazione fisica.

Concetti fondamentali

Entità tabella:

Metadati per dati strutturati con schemi ben definiti. Le entità tabella sono identificate in modo univoco dall'ID entità e dalla posizione dei dati. I metadati delle entità tabella sono interrogabili in BigQuery e Dataproc Metastore:

• Oggetti Cloud Storage:metadati per gli oggetti Cloud Storage, a cui si accede tramite le API Cloud Storage.
• Tabelle BigQuery:metadati per le tabelle BigQuery, a cui si accede tramite le API BigQuery.

Entità Fileset:

Metadati relativi a dati non strutturati, in genere senza schema. I set di file sono identificati in modo univoco dall'ID entità e dalla posizione dei dati. Ogni insieme di file ha un formato dei dati.

Partizioni:

Metadati per un sottoinsieme di dati all'interno di un'entità tabella o fileset, identificati da un insieme di coppie chiave-valore e da una posizione dei dati.

Prova l'API

Utilizza le pagine della documentazione di riferimento delle API Knowledge Catalog lakes.zones.entities e lakes.zones.partitions per visualizzare i parametri e i campi associati a ogni API. Utilizza il riquadro Prova questa API che accompagna la documentazione di riferimento per ogni metodo API per effettuare richieste API utilizzando parametri e campi diversi. Puoi creare, visualizzare e inviare le richieste senza dover generare credenziali e quindi visualizzare le risposte restituite dal servizio.

Le sezioni seguenti forniscono informazioni utili per comprendere e utilizzare le API Knowledge Catalog Metadata.

Entità

Elenco entità

Consulta la documentazione di lakes.zones.entities.list per informazioni complete sull'API.

Per limitare l'elenco delle entità restituite dal servizio, aggiungi i parametri di ricerca filter all'URL della richiesta list entities.

Recupera entità

Per informazioni complete sull'API, consulta la documentazione di lakes.zones.entities.get.

Per impostazione predefinita, la risposta Get Entity contiene i metadati di base dell'entità. Per recuperare metadati dello schema aggiuntivi, aggiungi il parametro di query view all'URL della richiesta.

Dettagli di compatibilità:mentre i metadati di Knowledge Catalog vengono registrati centralmente nell'API di metadati, solo i metadati delle tabelle delle entità compatibili con BigQuery e Apache Hive Metastore vengono pubblicati in BigQuery e Dataproc Metastore. L'API Get Entity restituisce un messaggio CompatibilityStatus, che indica se i metadati della tabella sono compatibili con BigQuery e Hive Metastore e, in caso contrario, il motivo dell'incompatibilità.

Aggiorna entità

Consulta la documentazione di lakes.zones.entities.update per informazioni complete sull'API.

Utilizza questa API per modificare i metadati delle entità, incluso se tu o Knowledge Catalog gestiranno i metadati delle entità.

• Questa API esegue una sostituzione completa di tutti i campi modificabili Entity. I seguenti campi dell'entità sono immutabili e, se li specifichi in una richiesta di aggiornamento, verranno ignorati:
  • asset
  • dataPath
  • type
  • system
• Specifica un valore per tutti i campi dell'entità modificabili, inclusi tutti i campi schema, anche se i valori non vengono modificati.
• Fornisci il campo etag. Puoi ottenere l'etag inviando prima una richiesta entities.get, che restituisce etag dell'entità nella risposta.
• Aggiornamento dei campi dello schema:puoi aggiornare lo schema della tabella rilevato da Knowledge Catalog per migliorarne l'accuratezza:
  I campi dello schema sono elencati nella scheda Scopri dell'interfaccia web di Knowledge Catalog nella console Google Cloud .
  • Se lo schema è un set di file, lascia vuoti tutti i campi dello schema.
  • Per definire un campo ripetuto, imposta la modalità su REPEATED. Per definire un campo della struttura, imposta type su RECORD.
  • Puoi impostare il campo userManaged dello schema per specificare se i metadati della tabella sono gestiti da te o da Knowledge Catalog. L'impostazione predefinita è Knowledge Catalog gestito. Se userManaged è impostato su true, questa impostazione è inclusa nelle informazioni restituite da una richiesta entities.get se EntityView è impostato su SCHEMA o FULL.
• Aggiornamento dei campi di partizione:
  • Per i dati partizionati in stile non Hive, il rilevamento di Knowledge Catalog genera automaticamente le chiavi di partizione. Ad esempio, per il percorso dei dati gs://root/2020/12/31, vengono generate le chiavi di partizione p0, p1 e p2. Per rendere le query più intuitive, puoi aggiornare p0, p1 e p2 a year, month e day rispettivamente.
  • Se aggiorni lo stile di partizione a HIVE style, il campo della partizione è immutabile.
• Aggiornamento di altri campi dei metadati: puoi aggiornare i campi mimeType, CompressionFormat, CsvOptions e JsonOptions generati automaticamente per facilitare l'individuazione di Knowledge Catalog. L'individuazione del catalogo delle conoscenze utilizzerà nuovi valori alla prossima esecuzione.

Crea entità

Consulta la documentazione di lakes.zones.entities.create per informazioni complete sull'API.

Utilizza l'API entities.create per creare entità di metadati di tabelle o fileset. Compila i campi obbligatori e facoltativi pertinenti oppure lascia che il servizio di rilevamento del catalogo delle conoscenze compili i campi facoltativi.

Elimina entità

Per informazioni complete sull'API, consulta la documentazione di lakes.zones.entities.delete.

• Fornisci il campo etag. Puoi ottenere l'etag inviando prima una richiesta entities.get, che restituisce etag dell'entità nella risposta.

Se i dati sottostanti di una tabella o di un set di file in una zona grezza vengono eliminati, i metadati della tabella o del set di file vengono eliminati automaticamente alla successiva scansione di rilevamento. Se i dati sottostanti di una tabella in una zona curata vengono eliminati, i metadati della tabella non vengono eliminati di conseguenza, ma viene segnalata un'azione di dati mancanti. Per risolvere il problema, elimina esplicitamente l'entità metadati della tabella tramite l'API Metadata.

Nota: quando i dati sottostanti esistono ancora, la scelta della funzione Elimina tabelle rimuove temporaneamente solo l'entità di metadati. L'entità verrà rigenerata alla successiva esecuzione del rilevamento.

Partizioni

Elenco delle partizioni

Consulta la documentazione di lakes.zones.partitions.list per informazioni complete sull'API.

Per limitare l'elenco delle partizioni restituite dal servizio, aggiungi i parametri di ricerca filter all'URL della richiesta list partitions.

Esempi:

• ?filter="Country=US AND State=CA AND City=Sunnyvale"
• ?filter="year < 2000 AND month > 12 AND Date > 10"

Ottieni partizione

Consulta la documentazione di lakes.zones.partitions.get per informazioni complete sull'API.

Per ottenere una partizione, devi completare l'URL della richiesta aggiungendo i valori della chiave di partizione alla fine dell'URL, formattati in modo da essere letti come partitions/value1/value2/…./value10.

Esempio: se una partizione ha valori, {Country=US, State=CA, City=Sunnyvale}, l'URL della richiesta GET deve terminare con /partitions/US/CA/Sunnyvale.

Importante:i valori URL aggiunti devono essere codificati due volte. Ad esempio, url_encode(url_encode(value)) può essere utilizzato per codificare "US:CA/CA#Sunnyvale" in modo che l'URL della richiesta termini con /partitions/US%253ACA/CA%2523Sunnyvale. Il campo del nome nella risposta mantiene il formato codificato.

Crea partizione

Consulta la documentazione di lakes.zones.partitions.create per informazioni complete sull'API.

Per creare una partizione personalizzata per l'origine dati, utilizza l'API partitions.create. Specifica il campo posizione obbligatorio con un percorso Cloud Storage.

Puoi fornire fino a 20 chiavi di partizione, ma solo le prime 10 possono essere utilizzate per il filtraggio.

Elimina partizione

Per informazioni complete sull'API, consulta la documentazione di lakes.zones.partitions.delete.

Completa l'URL della richiesta aggiungendo i valori della chiave di partizione alla fine dell'URL della richiesta, formattati in modo da essere letti come partitions/value1/value2/…./value10.

Esempio: se una partizione ha valori, {Country=US, State=CA, City=Sunnyvale}, l'URL della richiesta deve terminare con /partitions/US/CA/Sunnyvale.

Importante:i valori URL aggiunti devono essere conformi a RFC-1034 o devono essere codificati due volte, ad esempio US:/CA#/Sunnyvale come US%3A/CA%3A/Sunnyvale.

Passaggi successivi

• Scopri di più sull'accesso ai metadati in Apache Spark.