手動轉移至 Dataplex Universal Catalog 的商務詞彙表

本文提供操作說明，協助您從支援 Data Catalog 中繼資料的商務詞彙表搶先版，遷移至支援 Dataplex Universal Catalog 中繼資料的商務詞彙表正式版。轉移程序包括從 Data Catalog 匯出詞彙表、類別、字詞和連結，然後匯入 Dataplex Universal Catalog。

如要手動轉移至 Dataplex Universal Catalog 的商務詞彙表，請按照下列步驟操作：

  1. 從 Data Catalog 匯出術語表和詞條連結。
  2. 將詞彙表、類別和字詞匯入 Dataplex Universal Catalog。
  3. 將字詞之間的連結匯入 Dataplex Universal Catalog。
  4. 將字詞和資料欄之間的連結匯入 Dataplex Universal Catalog。

事前準備

如要啟用從 Data Catalog 術語表匯出資料的功能，請填寫這份表單。

安裝 gcloud 或 Python 套件。

必要的角色

如要從 Data Catalog 匯出詞彙表，您必須在詞彙表所在的專案中具備 roles/datacatalog.glossaryOwner 角色。請參閱這個角色需要的權限。

如要取得將商務詞彙表匯入 Dataplex Universal Catalog 所需的權限，請要求管理員在專案中授予您 Dataplex 管理員 (roles/dataplex.admin) IAM 角色。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備將商務詞彙表匯入 Dataplex Universal Catalog 所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要將商務詞彙表匯入 Dataplex Universal Catalog，必須具備下列權限：

  • dataplex.glossaries.import 詞彙表資源
  • dataplex.entryGroups.import 在 entry_groups 欄位中提供的 Dataplex Universal Catalog 項目群組，以及存在與詞彙表字詞連結的 Data Catalog 項目群組
  • dataplex.entryGroups.useSynonymEntryLink 在 entry_groups 欄位中提供的 Dataplex Universal Catalog 項目群組，以及存在與詞彙表字詞連結的 Data Catalog 項目群組
  • dataplex.entryGroups.useRelatedEntryLink 在entry_groups欄位中提供的 Dataplex Universal Catalog 項目群組，以及含有與詞彙表字詞連結的 Data Catalog 項目之項目群組上
  • dataplex.entryLinks.reference 在「referenced_entry_scopes」欄位中提供的所有專案上

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

從資料目錄匯出術語表、類別和字詞

一次只能匯出一個字彙表。

  1. 複製 dataplex-labs 存放區，然後將目錄變更為 business-glossary-import 子目錄：

    git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs
cd dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import

  2. 取得存取權杖：

    export GCLOUD_ACCESS_TOKEN=$(gcloud auth print-access-token)

  3. 執行匯出指令碼：

    python3 bg_import/business_glossary_export_v2.py \
--user-project="PROJECT_ID" \
--url="DATA_CATALOG_GLOSSARY_URL"

    更改下列內容：

    • PROJECT_ID：包含字彙表的專案 ID。
    • DATA_CATALOG_GLOSSARY_URL： Google Cloud 控制台中的 Data Catalog 企業詞彙網址。

    這個指令碼會建立 JSON 檔案，格式與用於中繼資料匯入作業的中繼資料匯入檔案相同。詞彙表、類別和字詞的名稱採用下列格式：

    • 詞彙表：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/{PROJECT_ID{"</var>"}}/locations/LOCATION_ID/glossaries/GLOSSARY_ID
    • 期限：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
    • 類別：projects/PROJECT_ID/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_ID/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID

    GLOSSARY_ID、CATEGORY_ID、TERM_ID、PROJECT_ID 和 LOCATION_ID 與 Data Catalog 詞彙表中的值相同。

結果

以下列出結果的注意事項：

  • 字彙表及其類別和字詞會匯出至全域位置，因此字詞可連結至任何區域的項目。

  • 匯出的檔案位於 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 的 Exported_Files 資料夾中。檔案名稱為 glossary_GLOSSARY_ID.json。

  • 匯出指令會在全域位置自動建立 Dataplex Universal Catalog 術語表，並使用相同的 GLOSSARY_ID 和 PROJECT_ID。

  • 這項指令碼會建立 JSON 檔案，其中包含同義字和字詞間的相關連結。匯出的檔案會儲存在 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 的 Exported_Files 資料夾中。 檔案名稱為 entrylinks_related_synonym_GLOSSARY_ID.json。

  • 匯出的連結會儲存在 dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import 的 Exported_Files 資料夾中。

  • 詞彙表中的字詞可能會連結至多個項目群組中的多個項目。 匯出字詞和資料欄之間的連結時，系統會為每個 entryGroup 建立檔案。 檔案名稱格式為：entrylinks_definition_export_GLOSSARY_ID_ENTRY_PROJECT_ID_ENTRY_LOCATION_ID_ENTRY_GROUP_ID.json。

  • 匯出指令碼執行後，系統會顯示匯入詞彙表、類別和字詞時所需的詞彙表 ID。

匯入字彙表、類別和字詞

您需要匯入上一個步驟匯出的 Dataplex Universal Catalog 詞彙表、類別和字詞。本節說明如何使用中繼資料工作 API 匯入資料。

  1. 建立 Cloud Storage bucket，然後將檔案上傳至 bucket。

  2. 授予 Dataplex Universal Catalog 服務帳戶 Cloud Storage bucket 的讀取權限。

  3. 執行中繼資料匯入工作，匯入術語表。

    # Set GCURL alias
alias gcurl='curl -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json"'
     
    # Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs\?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -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": ["projects/PROJECT_ID/locations/global/glossaries/GLOSSARY_ID"]
    }
}
}
EOF
)"

    更改下列內容：

    • JOB_ID：(選用) 中繼資料匯入作業 ID，可用於追蹤作業狀態。如果您未提供 ID，gcurl 指令會產生專屬 ID。
    • STORAGE_BUCKET：包含匯出字彙表檔案的 Cloud Storage bucket 或資料夾 URI。
    • PROJECT_ID：包含字彙表的專案編號。

  4. 選用：如要追蹤中繼資料匯入作業的狀態，請使用 metadataJobs.get 方法：

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

    如果中繼資料匯入工作發生任何錯誤，系統會將錯誤記錄在記錄檔中。

將字詞之間的連結匯入 Dataplex Universal Catalog

您需要匯入上一個步驟中匯出的字詞之間的連結。本節說明如何使用中繼資料工作 API 匯入資料。

  1. 建立新的 Cloud Storage bucket，然後將上一個步驟匯出的項目連結檔案上傳到該 bucket。

  2. 授予 Dataplex Universal Catalog 服務帳戶 Cloud Storage bucket 的讀取權限。

  3. 執行中繼資料匯入工作，匯入項目連結：

    # Import CURL Command
gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -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/GLOSSARY_PROJECT_ID/locations/global/entryGroups/@dataplex"],
    "entry_link_types": [
      "projects/dataplex-types/locations/global/entryLinkTypes/synonym",
      "projects/dataplex-types/locations/global/entryLinkTypes/related"
    ],
    "referenced_entry_scopes": ["projects/GLOSSARY_PROJECT_ID","projects/LINKED_GLOSSARY_PROJECT_ID_1","projects/LINKED_GLOSSARY_PROJECT_ID_2"]
  }
}
}
EOF
)"

    更改下列內容：

    • GLOSSARY_PROJECT_ID：包含詞彙表的專案 ID
    • 選用：LINKED_GLOSSARY_PROJECT_ID_1：如果不同專案中的術語已連結至字彙表，請提供專案 ID
    • 選用：LINKED_GLOSSARY_PROJECT_ID_2：如果不同專案中的術語已連結至字彙表，請提供專案 ID

    注意事項：

    • entry_groups 物件包含建立項目連結的項目群組。這是與字彙表位於相同專案和位置的 @dataplex 系統項目群組。

    • entry_link_types 物件可讓您匯入同義字、相關字詞或兩者：

      • 同義詞：projects/dataplex-types/locations/global/entryLinkTypes/synonym
      • 相關字詞：projects/dataplex-types/locations/global/entryLinkTypes/related

    • referenced_entry_scopes 物件包含項目連結的專案 ID，這些連結會連結不同詞彙表的字詞。

匯入字詞和欄之間的連結

您需要匯入上一個步驟匯出的字詞和資料欄之間的連結。本節說明如何使用中繼資料工作 API 匯入資料。

  1. 將上一個步驟匯出的每個檔案上傳至 Cloud Storage bucket。

  2. 針對 Cloud Storage bucket 中上傳的每個檔案，分別執行匯入指令。每個檔案都會對應到一個不重複的項目群組，其中包含項目群組的字詞和資料欄之間的連結。

gcurl "https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/metadataJobs?metadata_job_id=JOB_ID" -X POST -H "Content-Type: application/json" -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/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID/entryGroups/ENTRY_GROUP_ID"],
        "entry_link_types": ["projects/dataplex-types/locations/global/entryLinkTypes/definition"],
        "referenced_entry_scopes": ["projects/ENTRY_GROUP_PROJECT_ID", "projects/GLOSSARY_PROJECT_ID"]
    }
}
}
EOF
)"

後續步驟