Unternehmensglossare und Eintragslinks mit JSON-Dateien importieren

Mit Knowledge Catalog (früher Dataplex Universal Catalog) können Sie Glossare, Kategorien, Begriffe und Eintragslinks im Bulk über die Dataplex API importieren. Mit diesem Prozess können Sie Metadaten aus anderen Katalogisierungstools migrieren oder Bulk-Updates für Ihre vorhandenen Glossare durchführen.

Hinweis

Bevor Sie mit dem Import beginnen, müssen die folgenden Voraussetzungen erfüllt sein:

Cloud Storage-Bucket erstellen

Erstellen Sie einen Cloud Storage-Bucket, der als Staging-Bereich dient, in den Sie JSON-Dateien für den Import hochladen.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Importieren von Glossaren und Eintragslinks mithilfe von JSON-Dateien benötigen:

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

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

APIs aktivieren

Wenn Sie Glossare und Eintragslinks importieren möchten, aktivieren Sie die Dataplex API in Ihrem Projekt.

Rollen, die zum Aktivieren von APIs erforderlich sind

Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Inhaberrolle (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen

APIs aktivieren

Glossarbegriffe im Vergleich zu physischen Einträgen

Die Struktur Ihres Katalogs basiert auf den folgenden Komponenten:

  • Glossarbegriffe: Geschäftskonzepte wie der Jahresumsatz, die in Glossaren und Kategorien organisiert sind.
  • Einträge: Physische Daten-Assets, z. B. eine BigQuery-Tabelle oder -Spalte.

Bei Glossar-Importjobs werden neue Glossarkategorien und ‑begriffe erstellt und vorhandene überschrieben. Bei Importjobs für Eintragsverknüpfungen werden Verknüpfungen entweder zwischen Glossarbegriffen (z. B. Synonymen oder verwandten Begriffen) oder zwischen Glossarbegriffen und physischen Einträgen (z. B. zwischen einem Begriff und einem physischen Daten-Asset) erstellt. Weitere Informationen zum Strukturieren Ihres Katalogs finden Sie auf der Seite Unternehmensglossar verwalten.

Verhalten beim Bulk-Import

Der Import von Unternehmensglossaren und Eintragsverknüpfungen sind separate Prozesse und haben unterschiedliche Standardkontingente. Weitere Informationen finden Sie auf der Seite Kontingente und Limits.

Jobs für den Bulk-Import von Glossaren verwenden "entry_sync_mode": "FULL" und werden im vollständigen Überschreibungsmodus ausgeführt. Wenn Sie einen Importjob für ein vorhandenes Glossar ausführen, löscht Knowledge Catalog alle vorhandenen Kategorien und Begriffe und erstellt sie aus Ihren hochgeladenen JSON-Dateien neu. Wenn Sie Glossarbegriffe neu erstellen, werden ihnen neue eindeutige IDs zugewiesen und alle vorhandenen Eintragslinks, die mit diesen Begriffen verknüpft sind, werden gelöscht, z. B. Links zu BigQuery-Spalten. Wenn Sie diese Beziehungen wiederherstellen möchten, müssen Sie die Eintragslinks nach Abschluss des Glossarimportjobs noch einmal importieren. Beim Importieren von Eintragslinks werden nur neue Eintragslinks erstellt. Vorhandene Links werden nicht überschrieben oder gelöscht.

Glossare mithilfe von JSON-Dateien importieren

Führen Sie die folgenden Aufgaben aus, um Glossare, Kategorien und Begriffe durch Hochladen von JSON-Dateien in Cloud Storage zu importieren.

Zielglossar erstellen

Erstellen Sie ein Zielglossar, um Metadaten zu importieren.

alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

gcurl -X POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/glossaries?glossary_id=GLOSSARY_ID -d "$(cat<<EOF

{
   "displayName": "DISPLAY_NAME",
   "description": "DESCRIPTION"
}
EOF
)"

Ersetzen Sie Folgendes:

  • PROJECT_ID: die Projekt-ID, in der Sie das Glossar erstellen
  • LOCATION_ID: der Standort, an dem Sie das Glossar erstellen möchten
  • GLOSSARY_ID: die Glossar-ID
  • DISPLAY_NAME: der Anzeigename des Glossars
  • DESCRIPTION: die Beschreibung des Glossars

JSON-Dateien vorbereiten

Erstellen Sie eine JSON-Datei mit Zeilenumbrüchen, die das Glossar, die Kategorien und die Begriffe enthält, die Sie in den Cloud Storage-Bucket hochladen möchten.

Verwenden Sie das folgende JSON-Schema, um Ihre Importdateien zu strukturieren:

   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-category","aspects":{"dataplex-types.global.glossary-category-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","displayName":"CATEGORY_NAME","description":"CATEGORY_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"}]}}}
   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM1_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-term","aspects":{"dataplex-types.global.glossary-term-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"TERM1_CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM1_ID","displayName":"TERM1_DISPLAY_NAME","description":"TERM1_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"},{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary-category"}]}}}
   {"entry":{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM2_ID","entryType":"projects/dataplex-types/locations/global/entryTypes/glossary-term","aspects":{"dataplex-types.global.glossary-term-aspect":{"data":{}},"dataplex-types.global.overview":{"data":{"content":"TERM1_CONTENT"}},"dataplex-types.global.contacts":{"data":{"identities":[{role: "steward", name: "CONTACT_DISPLAY_NAME", id: "CONTACT_EMAIL"}]}}},"parentEntry":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","entrySource":{"resource":"projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM2_ID","displayName":"TERM2_DISPLAY_NAME","description":"TERM2_DESCRIPTION","ancestors":[{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary"},{"name":"projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID","type":"projects/dataplex-types/locations/global/entryTypes/glossary-category"}]}}}

Glossar, Kategorien und Begriffe importieren

Importieren Sie das Glossar, die Kategorien und die Begriffe in den Cloud Storage-Bucket:

# Set GCURL alias
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'

gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
{
   "type":"IMPORT",
   "import_spec":{
      "log_level":"DEBUG",
      "source_storage_uri":"gs://STORAGE_BUCKET/",
      "entry_sync_mode":"FULL",
      "aspect_sync_mode":"INCREMENTAL",
      "scope":{
         "glossaries": "GLOSSARY_NAME"
      }
   }
}
EOF
)"

Ersetzen Sie DATAPLEX_API durch den Dataplex API-Endpunkt im Format dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Führen Sie die folgenden Aufgaben aus, um Eintragslinks im Bulk zu importieren, indem Sie JSON-Dateien in Cloud Storage hochladen.

Erstellen Sie eine JSON-Datei mit Zeilenumbrüchen, die die Eintragslinks enthält, die Sie in den Cloud Storage-Bucket hochladen möchten.

Verwenden Sie das folgende JSON-Schema, um Ihre Importdateien zu strukturieren:

Beispielformat für Links zwischen Begriffen

   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-0606e3f2-8206-4f3a-aba9-32c6196f6048","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/synonym","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-2"}]}}
   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-2f7408e3-af3d-405d-81bb-861cf9ec5146","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/related","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-2"}]}}

Beispielformat für Links zwischen Begriffen und Daten-Assets

   {"entryLink":{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entryLinks/el-import-0606e3f2-8206-4f3a-aba9-32c6196f6048","entryLinkType":"projects/dataplex-types/locations/global/entryLinkTypes/definition","entryReferences":[{"name":"projects/PROJECT_NUMBER/locations/global/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/global/glossaries/import-glossary/terms/term-1"},{"name":"projects/PROJECT_NUMBER/locations/us-central1/entryGroups/entry-group-1/entries/entry-1"}]}}

Verwenden Sie den folgenden Befehl, um einen Metadatenimportjob zu initiieren, der synonym- oder related-Verbindungen zwischen Ihren Katalogbegriffen herstellt:

gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
   {
      "type":"IMPORT",
      "import_spec":{
         "log_level":"DEBUG",
         "source_storage_uri":"gs://STORAGE_BUCKET/",
         "entry_sync_mode":"FULL",
         "aspect_sync_mode":"INCREMENTAL",
         "scope":{
            "entry_groups":[  "projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex"
            ],
            "entry_link_types":[
               "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
               "projects/dataplex-types/locations/global/entryLinkTypes/related"
            ],
            "referenced_entry_scopes":[
               "PROJECT_IDS"
            ]
         }
      }
   }
EOF
)"

Ersetzen Sie DATAPLEX_API durch dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Wenn Sie eine Verknüpfung zwischen Glossarbegriffen und Daten-Assets erstellen möchten, führen Sie den Importjob für jede Eintragsgruppe aus, zu der der Eintrag für das Daten-Asset gehört. Alle Links zu Definitionseinträgen werden in dieser Eintragsgruppe erstellt.

   gcurl https://DATAPLEX_API/metadataJobs?metadata_job_id=JOB_ID -d "$(cat<<EOF
   {
   "type":"IMPORT",
   "import_spec":{
      "log_level":"DEBUG",
      "source_storage_uri":"gs://STORAGE_BUCKET/",
      "entry_sync_mode":"FULL",
      "aspect_sync_mode":"INCREMENTAL",
      "scope":{
         "entry_groups":[  "projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/@dataplex"
         ],
         "entry_link_types":[
            "projects/dataplex-types/locations/global/entryLinkTypes/definition"
         ],
         "referenced_entry_scopes":[
            "PROJECT_IDS"
         ]
      }
   }
   }
EOF
)"

Ersetzen Sie DATAPLEX_API durch dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID.

Status des Importjobs überwachen

  1. Führen Sie den folgenden Befehl aus, um den Status des import-Vorgangs abzurufen:

    gcurl https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/operations/operation-OPERATION_ID

    Ersetzen Sie OPERATION_ID durch die ID des Vorgangs.

  2. Führen Sie den folgenden Befehl aus, um den Status des Metadatenjobs abzurufen:

    gcurl -X GET https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION_ID/metadataJobs/JOB_ID

Nächste Schritte