Importa metadati

Puoi importare metadati Dataplex Catalog, le voci e i loro aspetti, da un sistema di terze parti a Dataplex.

Per importare i metadati, segui questi passaggi generali:

  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 di 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 Concetti di Dataplex Catalog, tra cui gruppi di voci, tipi di voci e tipi di aspetto. Per ulteriori informazioni, vedi 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.

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

Creazione di risorse Google Cloud

Prepara le seguenti risorse Google Cloud:

  1. Crea un gruppo di voci per le voci che vuoi importare.
  2. Creare tipi di aspetto per gli aspetti che vuoi importare.
  3. Crea tipi di voce 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, considera i 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 un aggiornamento incrementale le voci e gli aspetti del 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: in che modo Dataplex determina quali voci e aspetti da 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 alla località del lavoro oppure il tipo di voce deve essere globale.

  • Tipi di aspetto: 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.

Puoi specificare 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 modificato.

    Se una voce esiste in Dataplex ma non è inclusa nel file di importazione dei metadati, la voce viene eliminata quando esegui il job di 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.

Puoi specificare 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 questi aspetti e voci. Devi preparare il file prima di eseguire un job di metadati.

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

Le voci fornite nel file sostituiscono completamente tutte le voci esistenti per tutte le risorse che rientrano nell'ambito del job. Ciò significa che Deve includere i valori per tutte le voci di un job, non solo i valori che che vuoi aggiungere o aggiornare. per ottenere un elenco delle voci attuali nel tuo progetto. da usare come punto di partenza, utilizza Metodo API entries.list.

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.

Attieniti alle linee guida nelle sezioni seguenti per creare un file di importazione dei metadati.

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 a modificare una voce e gli 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 nuova riga (0x0a) per separare ciascun elemento da importare.

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 da importare nel file di importazione dei metadati include i seguenti campi. Il seguente esempio è formattato con interruzioni di riga per una migliore leggibilità, ma quando salvi il file, includi un carattere di nuova riga solo dopo ogni importazione molto utile. 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 relativo 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 nell'origine di un sistema operativo completo.
    • 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 aggiornati 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 associato alla voce. A seconda di come l'aspetto è collegato alla voce, utilizza una delle seguenti opzioni 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 è collegato al percorso della voce, fornisci il valore di destinazione, nel formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID@PATH.

    • KEY e VALUE: i contenuti di aspetto, in base allo schema del tipo di aspetto. I contenuti devono essere codificati come UTF-8. La dimensione massima del campo è 120 kB.

    • ASPECT_CREATE_TIMESTAMP: l'ora in cui è stato creato l'aspetto il 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 padre.

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

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

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

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

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

    • ASPECT_TYPE_REFERENCE: corrisponde al tipo di aspetto per 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 nel formato PROJECT_ID_OR_NUMBER.LOCATION_ID.ASPECT_TYPE_ID.

    Lasciando vuoto questo campo, viene considerato come specificare esattamente quei valori presenti all'interno della voce specificata.

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

Requisiti dei file

Il file di importazione dei metadati prevede i seguenti requisiti:

  • Il file deve essere formattato come Linee JSON che è 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.
  • Le dimensioni del file devono essere inferiori a 1 GiB.
  • Le voci e gli aspetti specificati nel file devono far parte del nell'ambito del job di importazione.
  • 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 valori e timestamp forniti nel file di importazione dei metadati con i valori e i timestamp esistenti nel tuo 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 allegati. 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. Poi, Dataplex esegue una o più delle seguenti operazioni:

    • Ricrea la voce. Se l'origine della voce crea il timestamp nel del file di importazione dei metadati sia più recente del timestamp corrispondente nella 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 è incluso nell'oggetto entry nella del file di importazione dei metadati, ma non è incluso nel campo della maschera di aggiornamento, Dataplex crea l'aspetto.
    • Elimina un aspetto. Se un aspetto non è incluso nell'oggetto entry in il file di importazione dei metadati, ma è incluso nel campo della maschera di aggiornamento, Dataplex elimina l'aspetto.

    • Aggiorna un aspetto. Se il timestamp dell'aggiornamento dell'origine dell'aspetto nei metadati di importazione sia più recente del timestamp corrispondente nel progetto Dataplex aggiorna l'aspetto del progetto. Dataplex aggiorna anche l'aspetto se la voce collegata viene manca un timestamp di aggiornamento dell'origine della voce o se il timestamp dell'origine della voce nel file di importazione dei metadati sia più recente del timestamp corrispondente nel progetto.

      Tuttavia, se almeno un aspetto del file di importazione dei metadati ha un valore meno recente rispetto a quello corrispondente nel progetto, Dataplex non esegue aggiornamenti per la voce collegata.

Creare un file di importazione dei metadati

Prima di importare i metadati, crea un file di importazione dei metadati per il 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 in nel bucket, inclusi i file che si trovano in 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, effettua le seguenti sostituzioni:

  • PROJECT_NUMBER: il numero del tuo progetto Google Cloud o ID progetto.
  • 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 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 relativo di un aspetto che rientra 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, vedi Visualizza i log dei job e risolvi 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 delle seguenti 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 di voci modificate, segui questi passaggi. Per ulteriori informazioni su come risolvere i problemi di un job non riuscito, consulta Sezione Visualizza i log dei job e risolvi i problemi di questo documento.

REST

Per ottenere informazioni su un job di metadati, utilizza il metodo 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 Metodo metadataJobs.list.

Annullare 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 per un job di metadati. Per ulteriori informazioni, vedi 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 generale del job. 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 importato. Usa il logging a livello di debug per risolvere i problemi relativi a specifici elementi di importazione. 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 rispetto ai file di importazione metadati nel tuo 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 nessun metadato e il job ha esito negativo. Esempi di errori nel file di importazione dei metadati includono quanto segue:
    • Un elemento nel 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 con queste voci, ma importa il resto dei metadati dal file.

Utilizza i log del job per risolvere l'errore.

Passaggi successivi