在 Dataplex Universal Catalog 中轉換至商務詞彙表

本文提供操作說明，協助您將支援 Data Catalog 中繼資料的商務詞彙表搶先版，單一步驟遷移至 Dataplex Universal Catalog 中正式發布的商務詞彙表。遷移至正式發布版本後，您就能使用強化功能，並與 Dataplex Universal Catalog 中繼資料進行更深入的整合，享有更穩定的服務、新功能和完整的正式版支援。這個程序會自動更新詞彙表，支援 Dataplex Universal Catalog 中繼資料。

注意： 如果您已開始使用手動程序遷移詞彙表，並想查看相關操作說明，請參閱「手動遷移至 Dataplex Universal Catalog 的商務詞彙表」。

事前準備

1. 安裝 gcloud 或 Python 套件。驗證使用者帳戶和 Python 程式庫使用的應用程式預設憑證 (ADC)。執行下列指令，並按照瀏覽器中的提示操作：

   gcloud init
   gcloud auth login
   gcloud auth application-default login
   

2. 啟用下列 API：

   • Dataplex API
   • Data Catalog API
   • Cloud Resource Manager API
   • Cloud Storage API

3. 在任一專案中建立一或多個 Cloud Storage bucket。這些 bucket 會做為匯入檔案的暫存位置。提供的 bucket 越多，匯入速度就越快。將 Storage 管理員身分與存取權管理角色授予執行遷移作業的服務帳戶：

   [e-mail]

   將 MIGRATION_PROJECT_ID 替換為要遷移字彙表的專案。

4. 設定存放區：

   1. 複製存放區：

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

   2. 安裝必要套件：

      pip3 install -r requirements.txt
      cd migration
      

      注意： 如果安裝套件時發生任何問題，請按照步驟建立新的 Python 虛擬環境。

必要的角色

如要取得將詞彙從 Data Catalog 遷移至 Dataplex Universal Catalog 的權限，請要求管理員授予下列 IAM 角色：

• Data Catalog 詞彙表擁有者 (roles/datacatalog.glossaryOwner) 專案
• Dataplex 管理員 (roles/dataplex.admin) 專案

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備將詞彙從 Data Catalog 遷移至 Dataplex Universal Catalog 的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要將詞彙表從 Data Catalog 遷移至 Dataplex Universal Catalog，您必須具備下列權限：

• datacatalog.glossaries.get 要遷移字彙表的專案
• datacatalog.glossaries.list 要遷移字彙表的專案
• dataplex.glossaries.create 在 Dataplex Universal Catalog 中建立術語表的專案
• dataplex.glossaries.update 在專案上，詞彙表將在 Dataplex Universal Catalog 中更新

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

如要進一步瞭解 Dataplex Universal Catalog Identity and Access Management (IAM)，請參閱「使用 IAM 控管存取權」。

執行遷移指令碼

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2

更改下列內容：

• USER_PROJECT_ID：要遷移的專案 ID。

  MIGRATION_PROJECT_ID 是指包含要匯出 Data Catalog 字彙表的來源專案。USER_PROJECT_ID 是用於帳單和配額歸因的專案，適用於指令碼產生的 API 呼叫。

• BUCKET1 和 BUCKET2：用於匯入作業的 Cloud Storage bucket ID。

  您可以提供一或多個值區。如要提供 bucket 引數，請以逗號分隔列出 bucket 名稱，且不得包含空格 (例如 --buckets=bucket-one,bucket-two)。bucket 和字彙表之間不一定要一對一對應；指令碼會平行執行匯入工作，加快遷移速度。

如果權限問題導致指令碼無法自動探索機構 ID，請使用 --orgIds 旗標指定指令碼可使用的機構，以便搜尋與術語相關聯的資料資產。

注意： 請勿編輯匯出的 JSON 檔案。這個指令碼會以 Dataplex Universal Catalog 匯入 API 要求的格式產生檔案；修改格式可能會導致匯入作業失敗。

遷移範圍詞彙表

如要只遷移特定字彙表，請提供相應網址來定義範圍。

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

將 GLOSSARY_URL1 (和 GLOSSARY_URL2) 替換為要遷移的字彙表網址。您可以提供一或多個詞彙表網址。

遷移作業執行時，匯入工作數量可能會少於匯出字彙表數量。如果直接建立不需要背景匯入工作的空白字彙表，就會發生這種情況。

繼續執行匯入工作失敗的遷移作業

如果遷移後仍有檔案，表示部分匯入工作失敗。如要繼續遷移作業，請執行下列指令：

python3 run.py --project=MIGRATION_PROJECT_ID --user-project=USER_PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

如果失敗，請再次執行 resume 指令。這個指令碼只會處理未成功匯入及刪除的檔案。

這個指令碼會強制執行項目連結和詞彙間連結的依附元件檢查。 只有在成功匯入父項字彙表的情況下，系統才會匯入項目連結檔案。同樣地，只有在成功匯入所有參照字詞後，系統才會匯入字詞之間的連結。

注意： 系統可能會在記錄或產生的檔案中，為字彙表、項目連結和工作名稱附加隨機 ID。這些 ID 僅供內部後端使用，不會影響最終遷移字彙表的名稱或結構。

疑難排解

本節提供常見錯誤的解決方法。

• 權限遭拒 / 403 錯誤：請確認使用者或服務帳戶在目的地專案中具有 Dataplex Universal Catalog 編輯者角色，且在來源專案中具有 Data Catalog 檢視者角色。

• ModuleNotFoundError：請確認您已啟用 Python 虛擬環境，並使用 pip3 install -r requirements.txt 安裝必要套件。

• TimeoutError / ssl.SSLError：這類網路層級的錯誤可能是防火牆、Proxy 或連線速度緩慢所致。指令碼的逾時時間為 5 分鐘，如果問題持續發生，可能需要檢查本機網路設定。

• 找不到方法 (無法擷取項目)：這項錯誤通常表示使用者專案未列入允許呼叫 API 的清單，因此無法擷取必要項目。