從 Google 試算表匯入項目連結

本文說明如何使用項目連結匯入公用程式，從 Google 試算表將項目連結 (詞彙表字詞與資料資產之間的關係，包括 definition、related 和 synonym 項目連結類型) 大量匯入 Knowledge Catalog (前身為 Dataplex Universal Catalog)。

事前準備

將項目連結匯入 Knowledge Catalog 之前，請先完成下列必要條件。

設定服務帳戶

如要使用 Google 試算表執行匯入公用程式，您必須設定服務帳戶，並具備存取 Google Sheets API 和模擬使用者憑證的必要權限：

  1. 找出或建立服務帳戶。

    選取現有服務帳戶，或在執行匯入公用程式的專案中建立新的服務帳戶。詳情請參閱「建立服務帳戶」。記下服務帳戶電子郵件地址 (例如 SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com)。

  2. 設定服務帳戶模擬。

    如要在本機執行匯入公用程式指令碼，使用者帳戶必須具備模擬服務帳戶的權限。將服務帳戶的服務帳戶權杖建立者角色 (roles/iam.serviceAccountTokenCreator) 授予使用者帳戶。

    詳情請參閱「管理服務帳戶的存取權」。

  3. 授予服務帳戶 Google 試算表 Editor 存取權。

    開啟要用於匯入程序的 Google 試算表，按一下「共用」，然後將服務帳戶電子郵件地址新增為Editor。這項權限可讓服務帳戶讀取或寫入試算表中的資料。

建立 Cloud Storage bucket

建立 Cloud Storage bucket，做為匯入檔案的暫存區。

必要的角色

為確保服務帳戶具備從 Google 試算表匯入項目連結的必要權限，請要求管理員將下列 IAM 角色授予服務帳戶：

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

管理員或許也能透過自訂角色或其他預先定義的角色，授予服務帳戶必要權限。

啟用 API

如要匯入項目連結，請在專案中啟用下列 API：

啟用 API 時所需的角色

如要啟用 API，您需要服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

啟用 API

設定 Git 存放區

複製 dataplex-labs 存放區：

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

安裝依附元件

安裝必要的 Python 依附元件：

pip3 install -r requirements.txt
cd dataplex-glossary

如果安裝套件時發生任何問題，請設定新的 Python 開發環境。

驗證及設定服務帳戶模擬

初始化 Google Cloud CLI，並使用應用程式預設憑證 (ADC) 搭配服務帳戶模擬功能進行驗證：

# Set your service account email address
SA_EMAIL="SERVICE_ACCOUNT_EMAIL"

# Authenticate ADC using service account impersonation and required scopes
gcloud init
gcloud auth login
gcloud auth application-default login \
  --impersonate-service-account="${SA_EMAIL}" \
  --scopes="https://www.googleapis.com/auth/spreadsheets"

將 SERVICE_ACCOUNT_EMAIL 替換為服務帳戶電子郵件 ID。例如：

SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

跨專案匯入規定

如要匯入多個 Google Cloud 專案的項目連結，請先確認設定符合下列需求，再執行匯入公用程式：

  • 設定跨專案 IAM 權限：執行匯入指令碼的服務帳戶必須在所有目標專案中具備足夠的權限。

  • 確認項目是否存在：執行匯入作業前，目標項目必須已存在於各自的 Knowledge Catalog 專案中。

  • 授予 Knowledge Catalog 服務代理程式 Cloud Storage bucket 存取權：每個目標專案中的 Knowledge Catalog 服務帳戶都需要存取 Cloud Storage bucket。

建立並匯入 Google 試算表

如要順利執行大量匯入作業，請務必使用精確的欄位結構建立新的 Google 試算表，匯入公用程式才能順利剖析及驗證中繼資料欄位。確認您已授予服務帳戶 Editor Google 試算表的存取權。

試算表的第一列必須包含下列確切的結構定義標題 (須區分大小寫)：

欄標題 必要或選用 說明
entry_link_type 必填 這個值必須是 definition、related 或 synonym。
source_entry 必填 來源項目的完整資源路徑，格式為：
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
target_entry 必填 目標項目的完整資源路徑，格式為：
projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRYGROUP_NAME/entries/ENTRY_NAME
source_path 選用 定義連結的欄或欄位路徑 (例如 Schema.column_name)。

設定環境變數

設定下列環境變數：

# Set your Google Sheet URL
export SPREADSHEET_URL="GOOGLE_SHEET_URL"

# Set your bucket name
export BUCKETS="COMMA_SEPARATED_LIST_OF_BUCKETS"

# Set the project ID
export USER_PROJECT="USER_PROJECT"

從 Google 試算表匯入項目連結

如要將 Google 試算表中的項目連結匯入 Knowledge Catalog，請執行 entrylinks-import.py 指令碼：

cd import
python3 entrylinks-import.py \
  --spreadsheet-url="$SPREADSHEET_URL" \
  --buckets="$BUCKETS" \
  --user-project="$USER_PROJECT"

如要並行執行多個匯入作業，請在 --buckets 參數中指定多個 Cloud Storage 值區。指令碼會將中繼資料分割成較小的批次，並在各個 bucket 中同時處理，縮短總擷取時間。

您可以在本機執行路徑的 logs/ 目錄中查看執行記錄。這些記錄有助於稽核轉移程序，並找出遭略過的項目或格式警告。

後續步驟