Dataplex Universal Catalog のビジネス用語集に移行する

このドキュメントでは、Data Catalog メタデータをサポートするビジネス用語集のプレビュー版から、Dataplex Universal Catalog メタデータをサポートするビジネス用語集の一般提供版に移行する手順を説明します。移行プロセスでは、用語集、カテゴリ、用語、リンクを Data Catalog からエクスポートし、Dataplex Universal Catalog にインポートする必要があります。

Dataplex Universal Catalog のビジネス用語集への移行手順は次のとおりです。

  1. Data Catalog から用語集、カテゴリ、用語をエクスポートします。
  2. 用語集、カテゴリ、用語を Dataplex Universal Catalog にインポートします。
  3. Data Catalog から用語間のリンクをエクスポートします。
  4. 用語間のリンクを Dataplex Universal Catalog にインポートします。
  5. Data Catalog から用語と列間のリンクをエクスポートします。
  6. 用語と列間のリンクを Dataplex Universal Catalog にインポートします。

必要なロール

Data Catalog から用語集をエクスポートするには、用語集が存在するプロジェクトに対する roles/datacatalog.glossaryOwner ロールが必要です。このロールに必要な権限をご確認ください。

Dataplex Universal Catalog にビジネス用語集をインポートするために必要な権限を取得するには、プロジェクトに対する Dataplex 管理者（roles/dataplex.admin）IAM ロールの付与を管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

この事前定義ロールには、ビジネス用語集を Dataplex Universal Catalog にインポートするために必要な権限が含まれています。必要とされる正確な権限については、「必要な権限」セクションを開いてご確認ください。

必要な権限

ビジネス用語集を Dataplex Universal Catalog にインポートするには、次の権限が必要です。

  • 用語集リソースに対する dataplex.glossaries.import
  • entry_groups フィールドで指定された Dataplex Universal Catalog エントリ グループと、用語集の用語にリンクされている Data Catalog エントリが存在するエントリ グループに対する dataplex.entryGroups.import
  • entry_groups フィールドで指定された Dataplex Universal Catalog エントリ グループと、用語集の用語にリンクされている Data Catalog エントリが存在するエントリ グループに対する dataplex.entryGroups.useSynonymEntryLink
  • entry_groups フィールドで指定された Dataplex Universal Catalog エントリ グループと、用語集の用語にリンクされている Data Catalog エントリが存在するエントリ グループに対する dataplex.entryGroups.useRelatedEntryLink
  • referenced_entry_scopes フィールドで指定されたすべてのプロジェクトに対する dataplex.entryLinks.reference

カスタムロールや他の事前定義ロールを使用して、これらの権限を取得することもできます。

Data Catalog から用語集、カテゴリ、用語をエクスポートする

一度にエクスポートできる用語集は 1 つだけです。

  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" \
--export-mode=glossary_only

    次のように置き換えます。

    • PROJECT_ID: 用語集が含まれているプロジェクトの ID。
    • DATA_CATALOG_GLOSSARY_URL: Data Catalog ビジネス用語集のコンソール内での URL。

    このスクリプトにより、メタデータをインポートするジョブに使用されるメタデータのインポート ファイルと同じ形式で、JSON ファイルが作成されます。用語集、カテゴリ、用語の名前には、以下の形式が使用されます。

    • 用語集: projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID
    • 用語: projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/terms/TERM_ID
    • カテゴリ: projects/PROJECT_NUMBER/locations/LOCATION_ID/entryGroups/@dataplex/entries/projects/PROJECT_NUMBER/locations/LOCATION_ID/glossaries/GLOSSARY_ID/categories/CATEGORY_ID

    ここで、GLOSSARY_ID、CATEGORY_ID、TERM_ID、PROJECT_NUMBER、LOCATION_ID は、Data Catalog 用語集の値と同じです。

用語集、カテゴリ、用語をインポートする

前の手順でエクスポートした Dataplex Universal Catalog の用語集、カテゴリ、用語をインポートする必要があります。このセクションでは、メタデータ ジョブを実行する API を使用したインポートの方法を説明します。

  1. Cloud Storage バケットを作成し、ファイルをそのバケットにアップロードします。

  2. Dataplex Universal Catalog サービス アカウントに、その Cloud Storage バケットに対する読み取り権限を付与します。

  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_NUMBER/locations/global/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": ["projects/PROJECT_NUMBER/locations/global/glossaries/GLOSSARY_ID"]
    }
}
}
EOF
)"

    次のように置き換えます。

    • JOB_ID:（省略可）メタデータのインポート ジョブの ID。ジョブのステータスの追跡に使用できます。ID を指定しない場合、gcurl コマンドによって一意の ID が生成されます。
    • STORAGE_BUCKET: エクスポートされた用語集ファイルが格納されている Cloud Storage バケットまたはフォルダの URI。
    • PROJECT_NUMBER: 該当する用語集が含まれているプロジェクトの番号。

  4. 省略可: メタデータのインポート ジョブのステータスを追跡するには、metadataJobs.get メソッドを使用します。

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

    メタデータのインポート ジョブでエラーが生じた場合は、ログに表示されます。

Data Catalog から用語間のリンクをエクスポートする

  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" \
--export-mode=entry_links_only \
--entrylinktype="related,synonym"

    このスクリプトにより、類義語と用語間の関連リンクを含む JSON ファイルが作成されます。エクスポートされたファイルは、dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import の Exported_Files フォルダにあり、ファイル名は entrylinks_relatedsynonymGLOSSARY_ID.json です。

用語間のリンクを Dataplex Universal Catalog にインポートする

前の手順でエクスポートした用語間のリンクをインポートする必要があります。このセクションでは、メタデータ ジョブを実行する API を使用したインポートの方法を説明します。

  1. 新しい Cloud Storage バケットを作成し、前の手順でエクスポートしたエントリリンクのファイルを、そのバケットにアップロードします。

  2. Dataplex Universal Catalog サービス アカウントに、その Cloud Storage バケットに対する読み取り権限を付与します。

  3. メタデータのインポート ジョブを実行して、エントリリンクをインポートします。

    # Import CURL Command
gcurl https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/global/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/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": [PROJECT_IDS]
    }
}
}
EOF
)"

    次のように置き換えます。

    • GLOSSARY_PROJECT_ID: 該当する用語集が含まれているプロジェクトの ID。
    • PROJECT_IDS: 異なるプロジェクトの用語集間で用語がリンクされている場合は、該当するプロジェクトの ID を "projects/PROJECT_ID1", "projects/PROJECT_ID2" の形式で指定します。

    次の点にご注意ください。

    • entry_groups オブジェクトには、エントリリンクが作成されるエントリ グループが含まれています。これは用語集と同じプロジェクトおよび同じロケーションにある、@dataplex システム エントリ グループです。

    • entry_link_types オブジェクトを使用すると、類義語、関連する用語、またはその両方をインポートできます。

      • 類義語: projects/dataplex-types/locations/global/entryLinkTypes/synonym
      • 関連する用語: projects/dataplex-types/locations/global/entryLinkTypes/related

    • referenced_entry_scopes オブジェクトには、異なる用語集の用語をリンクするエントリリンクのプロジェクト ID が含まれます。

用語と列間のリンクをエクスポートする

用語集および用語間のリンクをエクスポートしてインポートしたら、用語と列間のリンクのインポートに進みます。次のコマンドでは、リンクの種類を definition に設定することで、用語と列間のリンクをエクスポートします。

## Clone the repository and navigate to the directory
git clone https://github.com/GoogleCloudPlatform/dataplex-labs.git
cd dataplex-labs
cd dataplex-quickstart-labs/00-resources/scripts/python/business-glossary-import

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

## Run the export code
python3 bg_import/business_glossary_export_v2.py \
 --user-project="PROJECT_ID" \
 --url="DATA_CATALOG_GLOSSARY_URL" \
 --export-mode=entry_links_only \
 --entrylinktype="definition"

用語と列間のリンクをインポートする

前の手順でエクスポートした用語と列間のリンクをインポートする必要があります。このセクションでは、メタデータ ジョブを実行する API を使用したインポートの方法を説明します。

  1. 前の手順でエクスポートされた各ファイルを、手順 2 で説明されているように Cloud Storage バケットにアップロードします。

  2. Cloud Storage バケットにアップロードしたファイルごとに、個別に import コマンドを実行します。各ファイルは一意のエントリ グループに対応しており、そのエントリ グループの用語と列間のリンクを含んでいます。

# 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/ENTRY_GROUP_PROJECT_ID/locations/ENTRY_GROUP_LOCATION_ID
{
   "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":[
            PROJECT_IDS
         ]
      }
   }
}
EOF
)"

次のステップ