Metadaten exportieren

Sie können Metadaten aus Dataplex Universal Catalog exportieren, um sie in externen Systemen zu verwenden. Dazu führen Sie einen Metadatenexportjob aus.

In den folgenden Fällen kann es sinnvoll sein, Metadaten zu exportieren:

  • Metadaten mit BigQuery oder anderen Datenanalysetools abfragen und analysieren
  • Große Mengen an Metadaten programmatisch verarbeiten, die Sie später wieder in Dataplex Universal Catalog importieren können
  • Metadaten in benutzerdefinierte Anwendungen oder Drittanbietertools einbinden

Bei einem Metadatenexportjob wird ein Snapshot Ihrer Dataplex Universal Catalog-Metadaten exportiert. Dataplex Universal Catalog-Metadaten bestehen aus Einträgen und ihren Aspekten. Bei den Schritten auf dieser Seite wird davon ausgegangen, dass Sie mit den Metadatenkonzepten von Dataplex Universal Catalog vertraut sind, einschließlich Eintragsgruppen, Eintragstypen und Aspekttypen.

Jobumfang

Der Jobbereich definiert die zu exportierenden Metadaten. Sie müssen für jeden Metadaten-Exportjob einen der folgenden Jobbereiche angeben:

  • Organisation: Exportiert die Metadaten, die zu Ihrer Organisation gehören.
  • Projekte: Exportiert die Metadaten, die zu den angegebenen Projekten gehören.
  • Eintragsgruppen: Exportiert die Metadaten, die zu den angegebenen Eintragsgruppen gehören.

Sie können den Umfang weiter einschränken, indem Sie die im Job zu berücksichtigenden Eintragstypen oder Aspekttypen angeben. Beim Job werden nur die Einträge und Aspekte exportiert, die zu diesen Eintragstypen und Aspekttypen gehören.

VPC Service Controls

Dataplex Universal Catalog verwendet VPC Service Controls, um zusätzliche Sicherheit für Metadatenexportjobs zu bieten. Das Projekt, zu dem der Job gehört, bestimmt den VPC Service Controls-Perimeter:

  • Wenn Sie den Aufgabenbereich auf Organisationsebene festlegen, passiert Folgendes:
    • Der Exportbereich ist die Organisation, zu der der Job gehört.
    • Es werden nur die Einträge exportiert, die sich innerhalb des VPC Service Controls-Perimeters befinden.
    • Alle Projekte, die sich innerhalb der Organisation des Jobs, aber außerhalb des VPC Service Controls-Perimeters befinden, werden ausgeschlossen.
  • Wenn Sie den Jobbereich auf Projekte oder Eintragsgruppen festlegen, müssen sich die Projekte oder Eintragsgruppen im selben VPC Service Controls-Perimeter wie der Job befinden. Wenn eines der Projekte oder der Eintragsgruppen gegen die Regeln von VPC Service Controls verstößt, schlägt der Job fehl.

Hinweise

Bevor Sie Metadaten exportieren, müssen Sie die Aufgaben in diesem Abschnitt ausführen.

Erforderliche Rollen für Endnutzer

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zur Verwaltung von Metadatenexportjobs benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Diese vordefinierten Rollen enthalten die Berechtigungen, die zum Verwalten von Metadatenexportjobs erforderlich sind. Erweitern Sie den Abschnitt Erforderliche Berechtigungen, um die erforderlichen Berechtigungen anzuzeigen:

Erforderliche Berechtigungen

Die folgenden Berechtigungen sind erforderlich, um Metadaten-Exportjobs zu verwalten:

  • Metadaten exportieren:
    • dataplex.metadataJobs.create
    • dataplex.entryGroups.export
    • dataplex.entryGroups.get
    • resourcemanager.projects.get
    • resourcemanager.projects.list
  • Auf die exportierten Ergebnisse zugreifen: storage.objects.get

Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.

Erforderliche Rollen für das Dataplex Universal Catalog-Dienstkonto

Damit das Dataplex Universal Catalog-Dienstkonto die erforderlichen Berechtigungen für den Zugriff auf den Cloud Storage-Bucket hat, bitten Sie Ihren Administrator, dem Dataplex Universal Catalog-Dienstkonto die folgenden Berechtigungen für den Bucket zu gewähren: storage.buckets.get, storage.objects.get und storage.objects.create.

Google Cloud -Ressourcen konfigurieren

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Erstellen Sie einen Cloud Storage-Bucket zum Speichern der exportierten Ergebnisse.

    Der Bucket muss sich am selben Standort und im selben VPC Service Controls-Perimeter wie der Metadatenjob befinden.

Metadaten-Exportjob ausführen

In den folgenden Abschnitten wird beschrieben, wie Sie Metadaten mit verschiedenen Jobbereichen exportieren.

Metadaten aus Ihrer Organisation exportieren

Verwenden Sie zum Exportieren der Metadaten aus Ihrer Organisation die metadataJobs.create-Methode und legen Sie den booleschen Wert organizationLevel auf true fest.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • JOB_PROJECT: das Google Cloud-Projekt, in dem Sie den Metadatenjob ausführen. Geben Sie eine Projektnummer oder Projekt-ID an.
  • LOCATION_ID: der Google Cloud Standort, z. B. us-central1.
  • METADATA_JOB_ID: Optional. Die ID des Metadatenjobs.

  • BUCKET: Der Cloud Storage-Bucket, in den die Metadaten exportiert werden sollen.

    Optional können Sie nach dem Bucket-Namen ein benutzerdefiniertes Präfix im Format gs://BUCKET/PREFIX/ einfügen. Das benutzerdefinierte Präfix darf maximal 128 Zeichen lang sein.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
    },
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort identifiziert einen Vorgang mit langer Ausführungszeit. Die exportierten Metadaten werden in einem Cloud Storage-Bucket gespeichert.

Metadaten aus bestimmten Projekten exportieren

Wenn Sie Metadaten aus einem oder mehreren Projekten exportieren möchten, verwenden Sie die Methode metadataJobs.create und geben Sie eine Liste von Projekten an.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • JOB_PROJECT: das Google Cloud-Projekt, in dem Sie den Metadatenjob ausführen. Geben Sie eine Projektnummer oder Projekt-ID an.
  • LOCATION_ID: der Google Cloud Standort, z. B. us-central1.
  • METADATA_JOB_ID: Optional. Die ID des Metadatenjobs.

  • BUCKET: Der Cloud Storage-Bucket, in den die Metadaten exportiert werden sollen.

    Optional können Sie nach dem Bucket-Namen ein benutzerdefiniertes Präfix im Format gs://BUCKET/PREFIX/ einfügen. Das benutzerdefinierte Präfix darf maximal 128 Zeichen lang sein.

  • METADATA_SOURCE_PROJECT: Ein Projekt, dessen Metadaten Sie exportieren möchten. Geben Sie eine Projektnummer oder Projekt-ID an. Das Projekt muss sich in derselben Organisation und demselben VPC Service Controls-Perimeter wie der Metadatenjob befinden.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "projects": [
        "projects/METADATA_SOURCE_PROJECT",
        # Additional projects
      ],
    },
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort identifiziert einen Vorgang mit langer Ausführungszeit. Die exportierten Metadaten werden in einem Cloud Storage-Bucket gespeichert.

Metadaten aus bestimmten Eintragsgruppen exportieren

Wenn Sie Metadaten aus bestimmten Eintragssammlungen exportieren möchten, verwenden Sie die metadataJobs.create-Methode und geben Sie eine Liste der Eintragssammlungen an.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • JOB_PROJECT: das Google Cloud-Projekt, in dem Sie den Metadatenjob ausführen. Geben Sie eine Projektnummer oder Projekt-ID an.
  • LOCATION_ID: der Google Cloud Standort, z. B. us-central1.
  • METADATA_JOB_ID: Optional. Die ID des Metadatenjobs.

  • BUCKET: Der Cloud Storage-Bucket, in den die Metadaten exportiert werden sollen.

    Optional können Sie nach dem Bucket-Namen ein benutzerdefiniertes Präfix im Format gs://BUCKET/PREFIX/ einfügen. Das benutzerdefinierte Präfix darf maximal 128 Zeichen lang sein.

  • ENTRY_GROUP: Der relative Ressourcenname einer Eintragsgruppe, die für den Job relevant ist, im Format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Die Eintragsgruppe muss sich im selben Projekt wie der Metadatenjob befinden.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "entryGroups": [
        "ENTRY_GROUP",
        # Additional entry groups
      ],
    },
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort identifiziert einen Vorgang mit langer Ausführungszeit. Die exportierten Metadaten werden in einem Cloud Storage-Bucket gespeichert.

Metadaten aus bestimmten Eintrags- oder Aspekttypen exportieren

Wenn Sie Metadaten aus bestimmten Eintrags- oder Aspekttypen exportieren möchten, legen Sie den primären Jobbereich fest, z. B. auf Organisationsebene, wie im folgenden Beispiel gezeigt. Geben Sie dann eine Liste mit Eintragstypen, Aspekttypen oder beidem an.

Ersetzen Sie diese Werte in den folgenden Anfragedaten:

  • ENTRY_TYPE: Optional. Der relative Ressourcenname eines Eintrags, der für den Job infrage kommt, im Format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryTypes/ENTRY_TYPE_ID.

  • ASPECT_TYPE: Optional. Der relative Ressourcenname eines Aspekttyps, der für den Job relevant ist, im Format projects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/aspectTypes/ASPECT_TYPE_ID.

HTTP-Methode und URL:

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

JSON-Text anfordern:

{
  "type": EXPORT,
  "export_spec": {
    "output_path": "gs://BUCKET/",
    "scope": {
      "organizationLevel": true,
      "entry_types": [
        "ENTRY_TYPE",
        # Additional entry types
      ],
      "aspect_types": [
        "ASPECT_TYPE",
        # Additional aspect types
      ]
    },
  }
}

Wenn Sie die Anfrage senden möchten, maximieren Sie eine der folgenden Optionen:

Die Antwort identifiziert einen Vorgang mit langer Ausführungszeit. Die exportierten Metadaten werden in einem Cloud Storage-Bucket gespeichert.

Details zu einem Metadatenjob abrufen

Wenn Sie Informationen zu einem Metadatenjob abrufen möchten, z. B. den Status des Jobs und die Anzahl der exportierten Einträge, verwenden Sie die Methode metadataJobs.get.

Ergebnisse des Metadatenexports

Beim Metadatenexportjob wird ein Snapshot Ihrer Dataplex Universal Catalog-Metadaten zum Zeitpunkt der Erstellung des Metadatenjobs exportiert.

Dateiinhalte exportieren

Der Inhalt der Ausgabedatei hat dasselbe Format wie die Datei zum Importieren von Metadaten, die für Metadatenimportjobs verwendet wird. Sie können die Ausgabedatei direkt als Eingabe für einen Metadaten-Importjob verwenden.

Speicherort der Exportdatei

Dataplex Universal Catalog speichert die Exportresultate als Objekte in einem Cloud Storage-Bucket.

Der Objektpfad für jede Ausgabedatei wird aus dem Bucket-Namen und dem benutzerdefinierten Präfix, die Sie im Exportjob angegeben haben, gefolgt von einem systemgenerierten Pfad erstellt. Der vom System generierte Pfad ist für die Einbindung in BigQuery vorgesehen. Der Objektpfad hat das folgende Format:

gs://BUCKET/PREFIX/year=YYYY/month=MM/day=DD/consumer_project=JOB_PROJECT/job=METADATA_JOB_ID/project=METADATA_SOURCE_PROJECT/entry_group=ENTRY_GROUP/FILE_NUMBER.jsonl

Wichtige Hinweise:

  • Der vom System generierte Pfad beginnt mit dem standardmäßigen Hive-Partitionsformat für das Erstellungsdatum des Exportjobs. Dieses Format wird von BigQuery unterstützt. Weitere Informationen finden Sie unter Extern partitionierte Daten laden.
  • Der Parameter consumer_project ist das Projekt, in dem Sie den Metadatenexportjob ausführen. Der Parameter project ist das Projekt, das die Metadaten enthält, die Sie exportieren.
  • Sie können eine Metadatenjob-ID wiederverwenden, wenn der vorherige Job gelöscht wurde. Wenn Sie einen Job löschen, werden die Dateien, die durch diesen Job exportiert wurden, jedoch nicht gelöscht. Wenn Sie eine gelöschte Job-ID wiederverwenden, werden in den Ausgabedateipfaden möglicherweise doppelte Job-IDs angezeigt.

  • Jede Ausgabedatei wird mit einer Dateinummer benannt, einer Ganzzahl, die mit 1 beginnt.

    Wenn ein Metadaten-Exportjob eine große Anzahl von Einträgen enthält, werden die Ergebnisse in mehrere Dateien aufgeteilt, um die Größe jeder Ausgabedatei zu begrenzen. Die maximale Anzahl von Einträgen in jeder Ausgabedatei beträgt 1.000.000.

Beispiel für Ausgabedateien

Hier sind Beispielausgabedateien für einen Metadatenexportjob mit mehreren Projekten:

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-1/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-2/entrygroup=entry-group-1/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=example-job/project=metadata-project-3/entrygroup=entry-group-2/1.jsonl

Hier sehen Sie Beispieldateien für einen Metadatenexportjob, der eine große Eintragsgruppe enthielt. Die Ergebnisse für die Eintragsgruppe wurden in mehrere Dateien aufgeteilt.

gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/1.jsonl
gs://export-bucket/example-folder/year=2025/month=04/day=13/consumer_project=admin-project/job=another-example-job/project=example-metadata-project/entrygroup=big-entry-group/2.jsonl

Exportierte Metadaten in BigQuery analysieren

Wenn Sie die exportierten Metadaten in BigQuery analysieren möchten, können Sie eine externe Tabelle dafür erstellen. Wenn Sie eine externe Tabelle erstellen, können Sie die exportierten Daten abfragen, ohne dass zusätzliche Daten geladen oder transformiert werden müssen. Sie können beispielsweise die Anzahl der Einträge nach Eintragsgruppe zählen, Einträge mit bestimmten Aspekten suchen oder zusätzliche Analysen in BigQuery durchführen.

Gehen Sie dazu so vor:

  • Externe Tabelle für Hive-partitionierte Daten erstellen. Geben Sie die folgenden Informationen an:

    • Datei aus Cloud Storage-Bucket auswählen: Geben Sie den Pfad zum Cloud Storage-Ordner an, der die exportierten Metadatendateien enthält. Wenn Sie alle Dateien im Bucket einbeziehen möchten, verwenden Sie den Platzhalter „Sternchen“ (*). Beispiel: gs://export-bucket/example-folder/*.
    • Dateiformat: Wählen Sie JSONL (durch Zeilenumbruch getrenntes JSON) aus.
    • Klicken Sie auf das Kästchen Quelldatenpartitionierung und geben Sie dann für Quell-URI-Präfix auswählen das Cloud Storage-URI-Präfix für die BigQuery-Tabelle ein, um Partitionen zu definieren. Beispiel: gs://export-bucket/example-folder/.
    • Partitionsinferenzmodus: Wählen Sie die Option Typen automatisch ableiten aus.
    • Tabellentyp: Wählen Sie die Option Externe Tabelle aus.

    • Schema: Klicken Sie auf das Optionsfeld Als Text bearbeiten und geben Sie dann die folgende Schemadefinition für die Exportdateien ein:

      [
  {
    "name": "entry",
    "type": "RECORD",
    "mode": "NULLABLE",
    "fields": [
      {
        "mode": "NULLABLE",
        "name": "name",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entryType",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "createTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "updateTime",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "aspects",
        "type": "JSON"
      },
      {
        "mode": "NULLABLE",
        "name": "parentEntry",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "fullyQualifiedName",
        "type": "STRING"
      },
      {
        "mode": "NULLABLE",
        "name": "entrySource",
        "type": "RECORD",
        "fields": [
          {
            "mode": "NULLABLE",
            "name": "resource",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "system",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "platform",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "displayName",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "description",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "labels",
            "type": "JSON"
          },
          {
            "mode": "REPEATED",
            "name": "ancestors",
            "type": "RECORD",
            "fields": [
              {
                "mode": "NULLABLE",
                "name": "name",
                "type": "STRING"
              },
              {
                "mode": "NULLABLE",
                "name": "type",
                "type": "STRING"
              }
            ]
          },
          {
            "mode": "NULLABLE",
            "name": "createTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "updateTime",
            "type": "STRING"
          },
          {
            "mode": "NULLABLE",
            "name": "location",
            "type": "STRING"
          }
        ]
      }
    ]
  }
]

In BigQuery wird eine externe Tabelle mit den exportierten Metadaten erstellt. Das Tabellenschema enthält eine Schemaspalte entry, in der jede Zeile einen Eintrag darstellt. Weitere Informationen zu den Feldern für einen Eintrag finden Sie unter ImportItem. Das Tabellenschema enthält auch die Partitionen der Exportdatei, wie im Abschnitt Speicherort der Exportdatei dieses Dokuments beschrieben.

Nachdem Sie die externe Tabelle erstellt haben, können Sie sie mit der GoogleSQL-Syntax abfragen. Wenn Sie beispielsweise abfragen möchten, welche Eintragstypen exportiert wurden, verwenden Sie die folgende Anweisung:

SELECT entry.entryType FROM `example-project.example-dataset.example-table` LIMIT 1000

Nächste Schritte