Mit Knowledge Catalog (ehemals Dataplex Universal Catalog) können Sie Metadaten für die Verwendung in externen Systemen exportieren. Dazu verwenden Sie einen Metadatenexportjob. Sie können diese Metadaten dann mit Tools wie BigQuery analysieren, große Mengen programmatisch verarbeiten oder in benutzerdefinierte Anwendungen einbinden.
In diesem Dokument wird davon ausgegangen, dass Sie mit den Metadatenkonzepten des Knowledge 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
Knowledge 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 so:
- Wenn Sie den Jobbereich auf Organisationsebene festlegen, geschieht 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.
- 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 eine der Eintraggruppen gegen die Regeln von VPC Service Controls verstößt, schlägt der Job fehl.
Hinweis
Führen Sie die Aufgaben in diesem Abschnitt aus, bevor Sie Metadaten exportieren.
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 Metadaten-Exportjobs benötigen:
-
Metadaten-Exportjobs erstellen:
- Dataplex Entry Group Exporter (
roles/dataplex.entryGroupExporter) für die Organisation, die Projekte oder die Eintragsgruppen, die exportiert werden sollen - Dataplex Metadata Job Owner (
roles/dataplex.metadataJobOwner) für das Projekt, in dem Sie den Metadatenjob ausführen
- Dataplex Entry Group Exporter (
-
Auf die exportierten Ergebnisse zugreifen: Storage-Objekt-Betrachter (
roles/storage.objectViewer) für das Projekt oder den Bucket -
Metadaten-Jobs ansehen:
Dataplex Metadata Job Viewer (
roles/dataplex.metadataJobViewer) für das Projekt
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. Maximieren Sie den Abschnitt Erforderliche Berechtigungen, um die notwendigen Berechtigungen anzuzeigen:
Erforderliche Berechtigungen
Die folgenden Berechtigungen sind erforderlich, um Metadatenexportjobs zu verwalten:
-
Metadaten exportieren:
-
dataplex.metadataJobs.create -
dataplex.entryGroups.export -
dataplex.entryGroups.get -
resourcemanager.projects.get -
resourcemanager.projects.list
-
-
Greifen Sie auf die exportierten Ergebnisse zu:
storage.objects.get
Sie können diese Berechtigungen auch mit benutzerdefinierten Rollen oder anderen vordefinierten Rollen erhalten.
Erforderliche Rollen für das Knowledge Catalog-Dienstkonto
Damit das Knowledge Catalog-Dienstkonto die erforderlichen Berechtigungen für den Zugriff auf den Cloud Storage-Bucket hat, bitten Sie Ihren Administrator, dem Knowledge 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
Installieren Sie die Google Cloud CLI. Initialisieren Sie die Google Cloud CLI nach der Installation mit dem folgenden Befehl:
gcloud initWenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.
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.
Metadatenexportjob ausführen
In den folgenden Abschnitten wird beschrieben, wie Sie Metadaten mit unterschiedlichen Jobbereichen exportieren.
Metadaten aus Ihrer Organisation exportieren
Verwenden Sie die Methode metadataJobs.create, um die Metadaten aus Ihrer Organisation zu exportieren, und setzen Sie den booleschen Wert organizationLevel auf true.
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 Metadaten-Job-ID.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
Verwenden Sie die Methode metadataJobs.create, um Metadaten aus einem oder mehreren Projekten zu exportieren, und geben Sie eine Liste der Projekte 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 Metadaten-Job-ID.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 Eintraggruppen exportieren möchten, verwenden Sie die Methode metadataJobs.create und geben Sie eine Liste von Eintraggruppen an.
Ersetzen Sie diese Werte in den folgenden Anfragedaten:
JOB_PROJECT: Das Google CloudProjekt, 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 Metadaten-Job-ID.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. Die maximale Länge des benutzerdefinierten Präfixes beträgt 128 Zeichen.ENTRY_GROUP: der relative Ressourcenname einer Eintraggruppe, die im Bereich des Jobs liegt, im Formatprojects/PROJECT_ID_OR_NUMBER/locations/LOCATION_ID/entryGroups/ENTRY_GROUP_ID. Die Eintraggruppe 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 Eintragstypen oder Aspekttypen exportieren
Wenn Sie Metadaten aus bestimmten Eintragstypen 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 Eintragstyps, der für den Job relevant ist, im Formatprojects/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 Formatprojects/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
Verwenden Sie die Methode metadataJobs.get, um Informationen zu einem Metadatenjob abzurufen, z. B. den Status des Jobs und die Anzahl der exportierten Einträge.
Ergebnisse des Metadatenexports
Der Metadatenexportjob exportiert einen Snapshot Ihrer Knowledge Catalog-Metadaten zum Zeitpunkt der Erstellung des Metadatenjobs.
Inhalte der Exportdatei
Der Inhalt der Ausgabedatei entspricht dem Format der Metadaten-Importdatei, die für Metadaten-Importjobs verwendet wird. Sie können die Ausgabedatei direkt als Eingabe für einen Metadatenimportjob verwenden.
Speicherort der Exportdatei
Knowledge Catalog speichert die Export-Ergebnisdateien als Objekte in einem Cloud Storage-Bucket.
Der Objektpfad für jede Ausgabedatei wird aus dem Bucket-Namen und dem benutzerdefinierten Präfix, das Sie im Exportjob angegeben haben, gefolgt von einem systemgenerierten Pfad, erstellt. Der vom System generierte Pfad ist für die Integration 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 Standard-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_projectist das Projekt, in dem Sie den Metadatenexportjob ausführen. Der Parameterprojectist das Projekt, das die Metadaten enthält, die Sie exportieren. - Sie können eine Metadaten-Job-ID wiederverwenden, wenn der vorherige Job gelöscht wurde. Wenn Sie einen Job löschen, werden die von diesem Job exportierten Dateien 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, die eine Ganzzahl ab
1ist.Wenn ein Metadaten-Exportjob eine große Anzahl von Einträgen enthält, werden die Ergebnisse in mehrere Dateien aufgeteilt, um die Größe der einzelnen Ausgabedateien zu begrenzen. Die maximale Anzahl von Einträgen in jeder Ausgabedatei beträgt 1.000.000.
Beispiel für Ausgabedateien
Hier sehen Sie Beispielausgabedateien für einen Metadatenexportjob, der mehrere Projekte umfasste:
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 Beispielausgabedateien für einen Metadatenexportjob, der eine große Eintragsgruppe enthielt. Die Ergebnisse für die Eintragungsgruppe 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 für die exportierten Metadaten erstellen. Wenn Sie eine externe Tabelle erstellen, können Sie die exportierten Daten ohne zusätzliches Laden oder Transformieren von Daten abfragen. Sie können beispielsweise die Anzahl der Einträge nach Eintragstyp zählen, Einträge mit bestimmten Aspekten finden 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 Sternchenplatzhalter (
*). 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 an, 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 den Schieberegler 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" } ] } ] } ]
- 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 Sternchenplatzhalter (
In BigQuery wird eine externe Tabelle mit den exportierten Metadaten erstellt. Das Schema der Tabelle 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 Schema der Tabelle enthält auch die Partitionen der Exportdatei, wie im Abschnitt Speicherort der Exportdatei in diesem Dokument 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
- BigQuery-Tabellen mit der GoogleSQL-Syntax abfragen
- Metadaten mit einer Pipeline für verwaltete Verbindungen in Knowledge Catalog importieren.