Importa i metadati utilizzando una pipeline personalizzata

Questo documento descrive come importare i metadati Dataplex Catalog da un sistema di terze parti a Dataplex usando l'API di importazione dei metadati e la tua pipeline. I metadati di Dataplex Catalog sono costituiti da voci e relativi aspetti.

Se invece vuoi utilizzare una pipeline di orchestrazione gestita da Google Cloud per estrarre e importare i metadati, consigliamo di utilizzare una pipeline di connettività gestita. Con una pipeline di connettività gestita, puoi utilizzare il tuo connettore che estrae i metadati e genera un output in un formato che può essere utilizzato come input dai metodi dell'API di importazione dei metadati (il file di importazione dei metadati). Poi, utilizza i flussi di lavoro per orchestrare le attività della pipeline.

Passi di alto livello

Per importare i metadati utilizzando l'API di importazione dei metadati, segui questi passaggi di alto livello:

  1. Determina l'ambito del job.

    Inoltre, capire come Dataplex applica la logica di confronto e la modalità di sincronizzazione per voci e aspetti.

  2. Crea uno o più file di importazione dei metadati che definiscono i dati da importare.

  3. Salva i file di importazione dei metadati in un bucket Cloud Storage.

  4. Esegui un job di importazione dei metadati.

I passaggi in questa pagina presuppongono che tu abbia familiarità con i concetti di Dataplex Catalog, inclusi gruppi di voci, tipi di voci e tipi di aspetti. Per saperne di più, consulta la panoramica di Dataplex Catalog.

Prima di iniziare

Prima di importare i metadati, completa le attività in questa sezione.

Ruoli obbligatori

Per assicurarti che Account di servizio Dataplex disponga delle autorizzazioni necessarie per accedere al bucket Cloud Storage, all'amministratore di concedere all'account di servizio Dataplex Ruolo IAM Visualizzatore oggetti Storage (roles/storage.objectViewer) e l'autorizzazione storage.buckets.get sul bucket.

Per ottenere le autorizzazioni necessarie per gestire i job dei metadati, chiedi all'amministratore di concederti seguenti ruoli IAM:

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creare risorse Google Cloud

Prepara le seguenti risorse Google Cloud:

  1. Crea un gruppo di voci per le voci da importare.
  2. Creare tipi di aspetto per gli aspetti che vuoi importare.
  3. Crea tipi di voci per le voci che vuoi importare.
  4. Crea un bucket Cloud Storage per archiviare i file di importazione dei metadati.

Componenti di un job di metadati

Quando importi i metadati, tieni conto dei seguenti componenti di un job di metadati:

  • Ambito job: gruppo di voci, tipi di voce e tipi di aspetto da includere in il job.
  • Modalità di sincronizzazione: indica se eseguire un aggiornamento completo o incrementale delle voci e degli aspetti nel job.
  • File di importazione dei metadati: un file che definisce i valori da impostare per le voci e gli aspetti del lavoro. Puoi fornire più file di importazione di metadati nella lo stesso job di metadati. Salva i file in Cloud Storage.
  • Logica di confronto: il modo in cui Dataplex determina quali voci e aspetti modificare.

Ambito job

L'ambito del job definisce il gruppo di voci, i tipi di voce e, facoltativamente, il parametro i tipi di aspetto da includere in un job di metadati. Quando importi metadati, puoi modificare le voci e gli aspetti appartenenti alle risorse all'interno nell'ambito del job.

Per definire l'ambito del job, segui queste linee guida:

  • Gruppo di voci: specifica un singolo gruppo di voci da includere nel job. Il job modifica solo le voci che appartengono a questo gruppo di voci. Il gruppo di voci e il job devono trovarsi nella stessa regione.

  • Tipi di voce: specifica uno o più tipi di voce da includere nel job. Il job modifica solo le voci che appartengono a questi tipi di voci. La posizione di un tipo di voce deve corrispondere a quella del job oppure il tipo di voce deve essere globale.

  • Tipi di aspetti: facoltativi. Specifica uno o più tipi di aspetto da includere nel lavoro. Se specifichi un ambito per i tipi di aspetto, il job modifica solo gli aspetti che appartengono a questi tipi di aspetto. La posizione di un tipo di aspetto deve corrispondere a quella del job. il tipo di aspetto deve essere globale.

Specifichi l'ambito del job quando crei un job di metadati.

Modalità di sincronizzazione

La modalità di sincronizzazione specifica se eseguire un aggiornamento completo o un aggiornamento incrementale sulle voci e sugli aspetti di un job di metadati.

  • FULL: supportato per le voci. Tutte le voci nell'ambito del job vengono modificate.

    Se una voce esiste in Dataplex, ma non è inclusa nel file di importazione dei metadati, viene eliminata quando esegui il job dei metadati.

    La sincronizzazione completa non è supportata per gli aspetti.

  • INCREMENTAL: supportato per gli aspetti. Viene modificato solo un aspetto se il file di importazione dei metadati include un riferimento all'aspetto nel campo updateMask e il campo aspectKeys. Per ulteriori informazioni nel file di importazione dei metadati, consulta le Sezione Struttura di un elemento importato di questo documento.

    La sincronizzazione incrementale non è supportata per le voci.

Specifichi la modalità di sincronizzazione quando crei un job di metadati.

File di importazione dei metadati

Il file di importazione dei metadati è una raccolta delle voci e degli aspetti che che si desidera modificare. Definisce i valori da impostare per tutti i campi che appartengono a queste voci e aspetti. Prepara il file prima di eseguire un job di metadati.

Si applicano le seguenti linee guida generali:

  • Puoi fornire più file di importazione dei metadati nello stesso job dei metadati.

  • Le voci fornite nel file sostituiscono completamente tutte le voci esistenti per le risorse che rientrano nell'ambito del job. Ciò significa che devi includere i valori per tutte le voci di un job, non solo quelli che vuoi aggiungere o aggiornare. Per ottenere un elenco delle voci correnti del progetto da utilizzare come punto di partenza, utilizza il metodo dell'API entries.list.

  • Devi fornire un file di importazione dei metadati nell'ambito di un job di metadati. Se vuoi per eliminare tutti i dati esistenti per le voci che rientrano nell'ambito del job, fornisce un file di importazione dei metadati vuoto.

  • Tutte le voci e gli aspetti che includi nel file devono appartenere al gruppi di voci, tipi di voci e tipi di aspetto da te definiti nell'ambito del job.

Utilizza le linee guida dettagliate nelle sezioni seguenti per creare un metadato importa il file.

Struttura del file

Ogni riga del file di importazione dei metadati contiene un oggetto JSON che corrisponde a un elemento di importazione. Un elemento di importazione è un oggetto che descrive i valori da modificare per una voce e i relativi aspetti associati.

Puoi fornire più elementi di importazione in un unico file di importazione dei metadati. Tuttavia, non fornire lo stesso elemento di importazione più di una volta in un job di metadati. Utilizza un carattere di riga nuova (0x0a) per separare ogni elemento di importazione.

Viene visualizzato un file di importazione di metadati con un carattere di nuova riga tra un elemento e l'altro come nell'esempio seguente:

{ "entry": { "name": "entry 1", #Information about entry 1 }
{ "entry": { "name": "entry 2", #Information about entry 2 }

Struttura di un elemento di importazione

Ogni elemento di importazione nel file di importazione dei metadati include i seguenti campi (vedi ImportItem). L'esempio seguente è formattato con interruzioni di riga per la leggibilità, ma quando salvi il file, includi un carattere di a capo solo dopo ogni elemento di importazione. Non includere interruzioni di riga tra i campi di un singolo elemento di importazione.

{
  "entry": {
    "name": "ENTRY_NAME",
    "entryType": "ENTRY_TYPE",
    "entrySource": {
      "resource": "RESOURCE",
      "system": "SYSTEM",
      "platform": "PLATFORM",
      "displayName": "DISPLAY_NAME",
      "description": "DESCRIPTION",
      "createTime": "ENTRY_CREATE_TIMESTAMP",
      "updateTime": "ENTRY_UPDATE_TIMESTAMP"
    }
    "aspects": {
      "ASPECT": {
        "data": {
          "KEY": "VALUE"
        },
        "aspectSource": {
          "createTime": "ASPECT_CREATE_TIMESTAMP"
          "updateTime": "ASPECT_UPDATE_TIMESTAMP"
        }
      },
      # Additional aspect maps
    },
    "parentEntry": "PARENT_ENTRY",
    "fullyQualifiedName": "FULLY_QUALIFIED_NAME"
  },
  "updateMask": "UPDATE_MASK_FIELDS",
  "aspectKeys": [
    "ASPECT_KEY",
    # Additional aspect keys
  ],
}

Sostituisci quanto segue:

  • ENTRY_NAME: nome della risorsa relativa della voce, nel formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID.
  • ENTRY_TYPE: il nome della risorsa relativa del tipo di voce utilizzato per creare questa voce, nel formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.
  • entrySource: informazioni del sistema di origine sulla risorsa di dati che è rappresentata dalla voce:
    • RESOURCE: il nome della risorsa nel sistema di origine.
    • SYSTEM: il nome del sistema di origine.
    • PLATFORM: la piattaforma contenente il sistema di origine.
    • DISPLAY_NAME: un nome visualizzato semplice.
    • DESCRIPTION: una descrizione della voce.
    • ENTRY_CREATE_TIMESTAMP: l'ora in cui la voce è stata creato nel sistema di origine.
    • ENTRY_UPDATE_TIMESTAMP: l'ora in cui la voce è stata aggiornata nel sistema di origine.

  • aspects: gli aspetti associati alla voce. L'oggetto aspect e i suoi dati sono chiamati mappa degli aspetti.

    • ASPECT: un aspetto allegato alla voce. A seconda di come l'aspetto è associato alla voce, utilizza uno dei seguenti formati:

      • Se l'aspetto è collegato direttamente alla voce, fornisci la risorsa relativa nome del suo tipo di aspetto, nel formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.
      • Se l'aspetto è associato al percorso della voce, fornisci il percorso del tipo di aspetto nel formatoPROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH.

    • KEY e VALUE: i contenuti dell'aspetto, in base al relativo modello di metadati del tipo di aspetto. I contenuti devono essere con codifica UTF-8. La dimensione massima del campo è 120 KB. data un dizionario è obbligatorio, anche se è vuoto.

    • ASPECT_CREATE_TIMESTAMP: l'ora in cui l'aspetto è stato creato nel sistema di origine.

    • ASPECT_UPDATE_TIMESTAMP: l'ora in cui l'aspetto è stato aggiornato in il sistema di origine.

    • PARENT_ENTRY: il nome della risorsa della voce principale.

    • FULLY_QUALIFIED_NAME: un nome per la voce che può essere a cui fa riferimento un sistema esterno. Consulta Nomi completi.

  • UPDATE_MASK_FIELDS: i campi da aggiornare nei percorsi che sono rispetto alla risorsa Entry. Separa ogni campo con una virgola.

    Nella modalità di sincronizzazione delle voci FULL, Dataplex include i percorsi di tutti i campi di una voce che possono essere modificati, inclusi gli aspetti.

    Il campo updateMask viene ignorato quando viene creata o ricreata una voce.

  • ASPECT_KEY: gli aspetti da modificare. Supporta le seguenti sintassi:

    • ASPECT_TYPE_REFERENCE: corrisponde al tipo di aspetto per gli aspetti collegati direttamente alla voce.
    • ASPECT_TYPE_REFERENCE@PATH: corrisponde al tipo di aspetto e al percorso specificato.
    • ASPECT_TYPE_REFERENCE@*: corrisponde al tipo di aspetto per tutti i percorsi.

    Sostituisci ASPECT_TYPE_REFERENCE con un riferimento alla tipo di aspetto, nel formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.

    Se lasci vuoto questo campo, viene considerato come se specifichi esattamente gli aspetti presenti nella voce specificata.

    Nella modalità di sincronizzazione delle voci FULL, Dataplex aggiunge implicitamente le chiavi per tutti gli aspetti richiesti di una voce.

Requisiti dei file

Il file di importazione dei metadati prevede i seguenti requisiti:

  • Il file deve essere formattato come file JSON Lines, ovvero un file JSON delimitato da nuova riga. Utilizza un carattere di nuova riga (0x0a) per separare ciascun elemento di importazione.
  • Il file deve utilizzare la codifica dei caratteri UTF-8.
  • Le estensioni dei file supportate sono .jsonl e .json.
  • La dimensione di ciascun file di importazione dei metadati deve essere inferiore a 1 GiB. La dimensione totale massima per tutti i dati nel job dei metadati è 3 GB. Sono inclusi tutti i file e i metadati associati al job.
  • Le voci e gli aspetti specificati nel file devono far parte del nell'ambito del job di metadati.
  • Il file deve essere caricato in un bucket Cloud Storage. Non salvare in una cartella denominata CLOUD_STORAGE_URI/deletions/.

Logica di confronto

Dataplex determina quali voci e aspetti modificare confrontando i valori e i timestamp forniti nel file di importazione dei metadati con i valori e i timestamp esistenti nel progetto.

A livello generale, Dataplex aggiorna i valori nel tuo progetto Quando almeno una modifica proposta nel file di importazione dei metadati viene modificata lo stato del progetto quando viene eseguito il job, senza introdurre e i dati di Google Cloud. È necessario fare riferimento alla modifica proposta nel campo della maschera di aggiornamento o nell'aspetto nel file di importazione dei metadati.

Per ogni voce che fa parte dell'ambito del job, Dataplex esegue una delle seguenti opzioni:

  • Crea una voce e aspetti allegati. Se il file di importazione dei metadati include una voce che non esiste nel tuo progetto, Dataplex crea la voce e gli aspetti allegati.
  • Elimina una voce e gli aspetti allegati. Se una voce esiste in progetto, ma il file di importazione dei metadati non include la voce, Dataplex elimina la voce e gli aspetti collegati dal tuo progetto.

  • Aggiorna una voce e gli aspetti collegati. Se una voce esiste in entrambi sul file di importazione dei metadati e nel tuo progetto Dataplex valuta i timestamp dell'origine voce e i timestamp dell'origine dell'aspetto che sono associati alla voce per determinare quali valori modificare. Quindi, Dataplex esegue una o più delle seguenti operazioni:

    • Rigenera la voce. Se l'origine della voce crea il timestamp nel sia più recente del timestamp corrispondente nel file di importazione dei metadati progetto, Dataplex ricrea la voce nel progetto.
    • Aggiorna la voce. Se il timestamp dell'aggiornamento dell'origine della voce nei metadati di importazione sia più recente del timestamp corrispondente nel progetto Dataplex aggiorna la voce nel tuo progetto.
    • Crea un aspetto. Se un aspetto non esiste nel progetto ed è incluso nell'oggetto entry, nel campo della maschera di aggiornamento e nel campo delle chiavi dell'aspetto nel file di importazione dei metadati, Dataplex lo crea.
    • Elimina un aspetto. Se nel progetto esiste un aspetto ed è incluso nel campo della maschera di aggiornamento e nel campo delle chiavi dell'aspetto nel file di importazione dei metadati, ma non è incluso nell'oggetto entry, Dataplex lo elimina.

    • Aggiorna un aspetto. Se un aspetto esiste nel progetto ed è incluso nel campo dell'oggetto entry, nel campo della maschera di aggiornamento e nel campo delle chiavi di aspetto il file di importazione dei metadati e il timestamp di aggiornamento dell'origine dell'aspetto nel sia più recente del timestamp corrispondente in il tuo progetto, Dataplex aggiorna l'aspetto.

      Se nell'importazione dei metadati non viene fornito un timestamp dell'aggiornamento dell'origine dell'aspetto ma la voce corrispondente è contrassegnata per un aggiornamento, Dataplex aggiorna anche l'aspetto.

      Tuttavia, se almeno un aspetto nel file di importazione dei metadati ha un timestamp precedente rispetto al timestamp corrispondente nel progetto, Dataplex non apporta aggiornamenti per la voce allegata.

Crea un file di importazione dei metadati

Prima di importare i metadati, crea un file di importazione dei metadati per il tuo job. Segui questi passaggi:

  1. Prepara un file di importazione dei metadati seguendo le linee guida descritte in precedenza in questo documento.
  2. Carica il file in un bucket Cloud Storage.

Puoi fornire più file di importazione di metadati nello stesso job di metadati. A fornire più file, salvarli nello stesso file di Cloud Storage di sincronizzare la directory di una VM con un bucket. Quando esegui il job devi specificare un bucket, non un file specifico. Dataplex importa i metadati da tutti i file salvati nel bucket, inclusi i file nelle sottocartelle.

Esegui un job di importazione dei metadati

Dopo aver creato un file di importazione dei metadati, esegui un job di importazione dei metadati utilizzando tramite Google Cloud CLI o tramite l'API Compute Engine.

REST

Per importare i metadati, utilizza la classe Metodo metadataJobs.create.

Prima di utilizzare i dati della richiesta, apporta le seguenti sostituzioni:

  • PROJECT_NUMBER: il numero o l'ID del tuo progetto Google Cloud.
  • LOCATION_ID: la località di Google Cloud, ad esempio us-central1.
  • METADATA_JOB_ID: facoltativo. L'ID job dei metadati.

  • CLOUD_STORAGE_URI: l'URI del bucket o della cartella Cloud Storage contenente i file di importazione dei metadati. Per maggiori informazioni informazioni sui requisiti dei file, consulta File di importazione dei metadati.

  • ENTRY_GROUP: il nome della risorsa relativo del gruppo di voci che rientra nell'ambito del job, nel formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Fornisci un solo gruppo di voci. Per ulteriori informazioni, consulta Ambito del job.

  • ENTRY_TYPE: il nome della risorsa relativo di un tipo di voce che è nell'ambito del job, nel formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID. Per ulteriori informazioni, consulta Ambito del job.

  • ASPECT_TYPE: facoltativo. Il nome della risorsa relativa di un tipo di aspetto incluso nell'ambito del job, nel formato projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID. Per ulteriori informazioni, consulta Ambito del job.
  • LOG_LEVEL: il livello dei log da acquisire, ad esempio INFO o DEBUG. Per ulteriori informazioni, consulta Visualizzare i log dei job e risolvere i problemi.

Metodo HTTP e URL: 

POST https://dataplex.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID/metadataJobs?metadataJobId=METADATA_JOB_ID

Corpo JSON della richiesta: 

{
  "type": IMPORT,
  "import_spec": {
    "source_storage_uri": gs://CLOUD_STORAGE_URI/,
    "scope": {
      "entryGroups": [
        ENTRY_GROUP
      ],
      "entry_types": [
        ENTRY_TYPE
      ],
      "aspect_types": [
        ASPECT_TYPE
      ]
    },
    "entry_sync_mode": FULL,
    "aspect_sync_mode": INCREMENTAL,
    "log_level": LOG_LEVEL
  }
}

Per inviare la richiesta, espandi una di queste opzioni:

La risposta identifica un'operazione a lunga esecuzione.

Visualizza i dettagli di un job di metadati

Per ottenere informazioni su un job di metadati, ad esempio lo stato del job e il numero di voci modificate, svolgi i passaggi che seguono. Per ulteriori informazioni su come risolvere i problemi di un job non riuscito, consulta la sezione Visualizzare i log dei job e risolvere i problemi di questo documento.

REST

Per ottenere informazioni su un job di metadati, utilizza il metodo metadataJobs.get.

Ottieni un elenco di job di metadati

Puoi ottenere un elenco dei job di metadati più recenti. Offerte di lavoro meno recenti con allo stato di terminale vengono periodicamente eliminati dal sistema.

REST

Per ottenere un elenco dei job di metadati più recenti, utilizza il metodo metadataJobs.list.

Annullamento di un job di metadati

Puoi annullare un job di metadati che non vuoi eseguire.

REST

Per annullare un job di metadati, utilizza Metodo metadataJobs.cancel.

Visualizza i log dei job e risolvi i problemi

Utilizza Cloud Logging per visualizzare i log di un job di metadati. Per ulteriori informazioni, consulta Monitorare i log di Dataplex.

Il livello di log viene configurato quando crei un job di metadati. Il log seguente sono disponibili i seguenti livelli:

  • INFO: fornisce i log a livello di job complessivo. Include log aggregati relativi a importare gli elementi, ma non specifica quale elemento di importazione presenta un errore.

  • DEBUG: fornisce log dettagliati per ogni elemento di importazione. Utilizza la registrazione a livello di debug per risolvere i problemi relativi a elementi di importazione specifici. Ad esempio, utilizza logging a livello di debug per identificare le risorse mancanti nel job ambito, voci o aspetti non conformi al tipo di voce associato o tipo di aspetto o altri errori di configurazione del file di importazione dei metadati.

Errori di convalida

Dataplex convalida i file di importazione dei metadati in base ai metadati correnti nel progetto. Se si verifica un problema di convalida, lo stato del job potrebbe restituiscono uno dei seguenti stati:

  • FAILED: si verifica quando si verifica un errore nel file di importazione dei metadati. Dataplex non importa metadati e il job non va a buon fine. Ecco alcuni esempi di errori nel file di importazione dei metadati:
    • Un elemento del file non può essere analizzato in un elemento di importazione valido
    • Una voce o un aspetto nel file appartiene a un gruppo di voci, a un tipo di voce o tipo di aspetto che non fa parte dell'ambito del job
    • Lo stesso nome di voce è specificato più di una volta nel job
    • Un tipo di aspetto specificato nella mappa aspetto o nelle chiavi aspetto non utilizza il formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@OPTIONAL_PATH
  • SUCCEEDED_WITH_ERRORS: si verifica quando il file di importazione dei metadati può essere analizzato correttamente, ma l'importazione di un elemento nel file causa una voce in il tuo progetto sia in uno stato incoerente. Dataplex ignora queste voci, ma importa il resto dei metadati dal file.

Utilizza i log dei job per risolvere il problema.

Passaggi successivi