2026년 4월 10일부터 Dataplex Universal Catalog가 Knowledge Catalog로 변경되었습니다. API, 클라이언트 라이브러리, CLI, IAM 이름은 변경되지 않습니다. 자세한 내용은 Google Cloud Knowledge Catalog 소개를 참조하세요.

Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Knowledge Catalog의 비즈니스 용어집으로 전환

이 문서에서는 Data Catalog 메타데이터를 지원하는 비즈니스 용어집 프리뷰 버전에서 Knowledge Catalog (이전의 Dataplex Universal Catalog)의 비즈니스 용어집 정식 버전으로 한 번에 마이그레이션하는 방법을 설명합니다. 정식 버전으로 마이그레이션하면 Knowledge Catalog 메타데이터와의 향상된 기능과 심층적인 통합을 사용하여 안정성, 새로운 기능, 전체 프로덕션 지원을 개선할 수 있습니다. 이 프로세스는 Knowledge Catalog 메타데이터를 지원하도록 용어집을 자동으로 업데이트합니다.

시작하기 전에

gcloud 또는 Python 패키지를 설치합니다. 사용자 계정 및 Python 라이브러리에서 사용하는 애플리케이션 기본 사용자 인증 정보(ADC)를 인증합니다. 다음 명령어를 실행하고 브라우저 기반 안내를 따릅니다.
```
gcloud init
gcloud auth login
gcloud auth application-default login
```
다음 API를 사용 설정합니다.
프로젝트에 하나 이상의 Cloud Storage 버킷을 만듭니다. 버킷은 가져오기 파일의 임시 위치로 사용됩니다. 버킷을 많이 제공할수록 가져오기가 빨라집니다. 마이그레이션을 실행하는 서비스 계정에 스토리지 관리자 IAM 역할을 부여합니다.
```
service-MIGRATION_PROJECT_ID@gcp-sa-dataplex.
```
MIGRATION_PROJECT_ID를 용어집을 이전하는 프로젝트로 바꿉니다.

저장소를 설정합니다.

저장소를 복제합니다.

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

필요한 패키지를 설치합니다.
```
pip3 install -r requirements.txt
cd migration
```
참고: 패키지 설치에 문제가 있는 경우 새 Python 가상 환경을 만드는 단계를 따르세요.

필요한 역할

Data Catalog에서 Knowledge Catalog로 용어집을 이전하는 데 필요한 권한을 얻으려면 관리자에게 다음 IAM 역할을 부여해 달라고 요청하세요.

Data Catalog 용어집 소유자 (roles/datacatalog.glossaryOwner) 프로젝트의
프로젝트의 Dataplex 관리자 (roles/dataplex.admin)

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

이러한 사전 정의된 역할에는 Data Catalog에서 Knowledge Catalog로 용어집을 이전하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

Data Catalog에서 Knowledge Catalog로 용어집을 이전하려면 다음 권한이 필요합니다.

datacatalog.glossaries.get 용어집을 이전하는 프로젝트의
datacatalog.glossaries.list 용어집을 이전하는 프로젝트의
dataplex.glossaries.create Knowledge Catalog에서 용어집이 생성되는 프로젝트의
dataplex.glossaries.updateKnowledge Catalog에서 용어집이 업데이트되는 프로젝트의

커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한 을 부여받을 수도 있습니다.

Knowledge Catalog Identity and Access Management (IAM)에 대한 자세한 내용은 IAM으로 액세스 관리를 참고하세요.

마이그레이션 스크립트 실행

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2

다음을 바꿉니다.

PROJECT_ID: 이전할 프로젝트의 프로젝트 ID 이 프로젝트는 스크립트에서 생성된 API 호출의 청구 및 할당량 기여에도 사용됩니다.
BUCKET1 및 BUCKET2: 가져오기에 사용될 Cloud Storage 버킷 ID

하나 이상의 버킷을 제공할 수 있습니다. 버킷 인수의 경우 공백 없이 쉼표로 구분된 버킷 이름 목록을 제공합니다 (예: --buckets=bucket-one,bucket-two). 버킷과 용어집 간의 일대일 매핑은 필요하지 않습니다. 스크립트는 가져오기 작업을 병렬로 실행하여 마이그레이션 속도를 높입니다.

권한 문제로 인해 스크립트에서 조직 ID를 자동으로 검색할 수 없는 경우 --orgIds 플래그를 사용하여 스크립트에서 용어집 용어에 연결된 데이터 애셋을 검색하는 데 사용할 수 있는 조직을 지정합니다.

마이그레이션의 범위 용어집

특정 용어집만 이전하려면 각 URL을 제공하여 범위를 정의합니다.

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2 --glossaries="GLOSSARY_URL1","GLOSSARY_URL2"

GLOSSARY_URL1 (및 GLOSSARY_URL2) 을 콘솔에 표시되는 대로 이전할 용어집의 전체 URL로 바꿉니다. Google Cloud 이 플래그를 사용하여 용어집을 지정하면 소스 프로젝트가 URL에서 결정되고 --project 플래그는 청구에만 사용됩니다.

예: https://console.cloud.google.com/datacatalog/glossaries/projects/my-project/locations/us-central1/entryGroups/my-entry-group/glossaries/my-glossary

마이그레이션을 실행할 때 가져오기 작업 수는 내보낸 용어집 수보다 적을 수 있습니다. 백그라운드 가져오기 작업이 필요하지 않은 빈 용어집이 직접 생성되는 경우 발생합니다.

가져오기 작업 실패 시 마이그레이션 재개

마이그레이션 후 파일이 있으면 일부 가져오기 작업이 실패한 것입니다. 마이그레이션을 재개하려면 다음 명령어를 실행합니다.

python3 run.py --project=PROJECT_ID --buckets=BUCKET1,BUCKET2 --resume-import

실패가 발생하면 resume 명령어를 다시 실행합니다. 스크립트는 가져오기 및 삭제가 완료되지 않은 파일만 처리합니다.

스크립트는 항목 링크 및 용어집 간 링크에 대한 종속성 검사를 적용합니다. 상위 용어집을 가져온 경우에만 항목 링크 파일을 가져옵니다. 마찬가지로 참조된 모든 용어를 가져온 경우에만 용어 간의 링크를 가져옵니다.

문제 해결

이 섹션에서는 일반적인 오류 해결 방법을 설명합니다.

권한 거부 / 403 오류: 사용자 또는 서비스 계정에 대상 프로젝트의 Dataplex 편집자 역할과 소스 프로젝트의 Dataplex 뷰어 역할이 있는지 확인합니다.
ModuleNotFoundError: Python 가상 환경을 활성화하고 필요한 패키지를 설치했는지 확인합니다. pip3 install -r requirements.txt.
TimeoutError / ssl.SSLError: 이러한 네트워크 수준 오류는 방화벽, 프록시 또는 연결 속도가 느려서 발생할 수 있습니다. 스크립트에는 5분의 제한 시간이 있습니다. 지속적인 문제가 발생하면 로컬 네트워크 구성을 확인해야 할 수 있습니다.
메서드를 찾을 수 없음 (항목을 가져올 수 없음): 이 오류는 사용자 프로젝트에 API를 호출할 권한이 없어 필요한 항목을 가져올 수 없음을 나타내는 경우가 많습니다.