Import business glossaries and entry links using JSON files

This page describes how to bulk import glossaries, categories, terms, and entry links into Knowledge Catalog (formerly Dataplex Universal Catalog) using the Dataplex API. You can use this process to migrate metadata from other cataloging tools or to perform bulk updates to your existing glossaries by uploading JSON files to Cloud Storage.

Before you begin

Before you start the import process, complete the following prerequisites:

Create a Cloud Storage bucket

Create a Cloud Storage bucket to serve as a staging area for import files.

Required roles

To get the permissions that you need to import glossaries and entry links using JSON files, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

You might also be able to get the required permissions through custom roles or other predefined roles.

Enable APIs

To import glossaries and entry links, enable the Dataplex API in your project.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the APIs

Import glossaries using JSON files

To import glossaries, categories, and terms, complete the following tasks.

Create a target glossary

Create a target glossary to import metadata.

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
)"

Replace the following:

  • PROJECT_ID: the project ID in which you're creating the glossary
  • LOCATION_ID: the location in which you want to create the glossary
  • GLOSSARY_ID: the glossary ID
  • DISPLAY_NAME: the display name of the glossary
  • DESCRIPTION: the description of the glossary

Prepare JSON files

Create a newline-delimited JSON file with glossary, categories, and terms that you want to upload to the Cloud Storage bucket.

Use the following JSON schema to structure your import files:

   {"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/