Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

구조화되지 않은 데이터에 데이터 프로필 사용

Vertex AI Gemini 2.5 Pro 모델로 구동되는 비정형 데이터 (UnstructuredDataProfileSpec)의 데이터 프로필 스캔은 기존 BigQuery 객체 테이블을 분석하여 Cloud Storage의 원시 비정형 파일 (예: PDF)을 구조화된 쿼리 가능 애셋으로 변환합니다. 이 독립형 워크플로는 이미 BigQuery 객체 테이블이 있는 사용자를 위해 설계되었으며 맞춤 프롬프트로 추출을 안내하는 기능을 지원합니다. Cloud Storage의 원시 파일로 시작하고 자동 탐색 워크플로를 원하는 경우 비구조적 데이터에 탐색 스캔 사용을 참고하세요.

이 문서에서는 필요한 권한을 설정하고, 객체 테이블을 준비하고, REST API를 사용하여 구조화되지 않은 데이터의 데이터 프로필 스캔을 만들고, 생성된 통계를 보고, 그래프 프로필을 선별하고, BigQuery로 데이터를 추출하는 방법을 설명합니다.

시작하기 전에

구조화되지 않은 데이터의 데이터 프로필 스캔을 만들기 전에 필요한 권한이 있고 API가 사용 설정되어 있는지 확인하세요.

API 사용 설정

프로젝트에 다음 API 사용 설정:

dataplex.googleapis.com
bigquery.googleapis.com
aiplatform.googleapis.com (Vertex AI)

API 사용 설정에 필요한 역할

API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

API 사용 설정

필수 역할 및 권한

비정형 데이터 시맨틱 추론은 BigQuery 객체 테이블에서 작동하는 고급 데이터 프로필 스캔 기능입니다. 구조화되지 않은 데이터 프로파일링을 구성하고 실행하려면 객체 테이블에 액세스하기 위한 기준 권한을 충족하고 여러 서비스 에이전트에서 시맨틱 추론을 위한 추가 역할을 부여해야 합니다.

기준 객체 테이블 역할

BigQuery 객체 테이블에 액세스하고 이를 쿼리하려면 본인과 Knowledge Catalog에서 사용하는 서비스 계정에 프로젝트에 대한 다음 기준 Identity and Access Management (IAM) 역할이 있어야 합니다.

BigQuery 데이터 뷰어(roles/bigquery.dataViewer)
BigQuery 연결 사용자(roles/bigquery.connectionUser)

객체 테이블 필수 요건의 전체 목록은 객체 테이블 만들기를 참고하세요.

시맨틱 추론을 위한 추가 역할

기준 테이블 액세스 권한 외에도 사용자와 서비스 계정에 다음 추가 IAM 역할이 있는지 확인합니다.

추가 ID 및 역할 요약

ID 유형	일반적인 주 구성원 형식	필요한 IAM 역할	핵심 목적
최종 사용자	내 Google Cloud 사용자 계정	Dataplex DataScan 편집자 Dataplex 카탈로그 편집자 BigQuery 데이터 편집자 BigQuery 작업 사용자	이러한 추가 역할을 사용하여 스캔을 구성하고, AI 생성 결과를 확인하고, 그래프 프로필을 선별하고, 최종 데이터 추출을 트리거합니다.
Dataplex Universal Catalog 검색 에이전트	`service-<var>PROJECT_NUMBER</var>@gcp-sa-dataplex.iam.gserviceaccount.com`	Vertex AI 사용자 BigQuery 작업 사용자 BigQuery 데이터 뷰어	이 Google 관리형 서비스 에이전트는 이러한 추가 역할을 사용하여 Vertex AI를 호출하여 추론된 스키마와 메타데이터를 생성합니다.
BigQuery 연결 서비스 계정	연결과 연결된 고유 ID입니다 (예: `bqcx-<var>PROJECT_NUMBER</var>-<var>ID</var>@gcp-sa-bigquery-condel.iam.gserviceaccount.com`).	스토리지 객체 뷰어 (소스 버킷) Vertex AI 사용자 (프로젝트)	BigQuery를 외부 스토리지에 연결하여 BigQuery가 개인 사용자 인증 정보를 노출하지 않고 원시 파일을 읽고, 객체 테이블을 만들고, AI 추론을 실행할 수 있도록 합니다.
파이프라인 실행 서비스 계정 (선택사항)	사용자 관리 서비스 계정	BigQuery 데이터 편집자 BigQuery 작업 사용자 BigQuery 사용자 Vertex AI 사용자	자동화된 파이프라인을 사용하여 데이터를 추출하는 경우 이 ID는 AI 생성 항목을 BigQuery 테이블로 구체화하는 백그라운드 작업을 실행합니다.
기본 Dataform 서비스 계정 (선택사항)	`service-<var>PROJECT_NUMBER</var>@gcp-sa-dataform.iam.gserviceaccount.com`	서비스 계정 토큰 생성자 (파이프라인 실행 서비스 계정에 부여됨)	파이프라인 추출 방법을 사용하는 경우 Dataform은 워크플로를 오케스트레이션하기 위해 파이프라인 실행 서비스 계정을 가장할 수 있는 권한이 필요합니다.

최종 사용자 역할 및 권한

사용자 계정에 스캔을 만들고, 통계를 보고, 그래프 프로필을 선별하고, 데이터를 추출하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트에 대한 다음 IAM 역할을 사용자 계정에 부여해 달라고 요청하세요.

스캔을 만들고 통계 보기:
- Dataplex DataScan 편집자 (roles/dataplex.dataScanEditor)
- Dataplex 카탈로그 편집자 (roles/dataplex.catalogEditor)
SQL 또는 파이프라인을 사용하여 데이터 추출:
- BigQuery 데이터 편집자 (roles/bigquery.dataEditor)
- BigQuery 작업 사용자 (roles/bigquery.jobUser)

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

이러한 사전 정의된 역할에는 스캔을 만들고, 통계를 보고, 그래프 프로필을 선별하고, 데이터를 추출하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

스캔을 만들고, 통계를 확인하고, 그래프 프로필을 큐레이팅하고, 데이터를 추출하려면 다음 권한이 필요합니다.

DataScans:
- dataplex.datascans.create
- dataplex.datascans.get
- dataplex.datascans.getData
- dataplex.datascans.list
- dataplex.datascans.update
데이터 추출:
- bigquery.tables.create
- bigquery.tables.update
- bigquery.tables.getData
- bigquery.jobs.create

관리자는 커스텀 역할이나 다른 사전 정의된 역할이 있는 이러한 권한을 사용자 계정에 부여할 수도 있습니다.

Dataplex 검색 서비스 에이전트 역할 및 권한

Dataplex 검색 서비스 에이전트는 Vertex AI를 사용하여 스캔을 실행하고 시맨틱 추론을 수행하는 데 액세스해야 하는 서비스 에이전트입니다.

Dataplex 탐색 서비스 에이전트 (일반적으로 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)에 스캔을 실행하고 Vertex AI를 사용하여 시맨틱 추론을 실행하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트의 Dataplex 탐색 서비스 에이전트 (일반적으로 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)에 다음 IAM 역할을 부여해 달라고 요청하세요.

중요: 이러한 역할은 사용자 계정이 아닌 Dataplex 탐색 서비스 에이전트 (일반적으로 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)에 부여해야 합니다. 올바른 주체에 역할을 부여하지 않으면 권한 오류가 발생할 수 있습니다.

전체:
- Vertex AI 사용자 (roles/aiplatform.user)
- Dataplex 검색 서비스 에이전트 (roles/dataplex.discoveryServiceAgent)
- BigQuery 작업 사용자 (roles/bigquery.jobUser)
- BigQuery 데이터 뷰어 (roles/bigquery.dataViewer)

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

이러한 사전 정의된 역할에는 Vertex AI를 사용하여 스캔을 실행하고 시맨틱 추론을 수행하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

Vertex AI를 사용하여 스캔을 실행하고 시맨틱 추론을 수행하려면 다음 권한이 필요합니다.

전체:
- aiplatform.endpoints.predict
- bigquery.datasets.create
- bigquery.datasets.get
- bigquery.tables.get
- bigquery.tables.getData
- storage.buckets.get
- storage.objects.get
- storage.objects.list

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 Dataplex 검색 서비스 에이전트 (일반적으로 service-PROJECT_NUMBER@gcp-sa-dataplex.iam.gserviceaccount.com)에 이러한 권한을 부여할 수도 있습니다.

BigQuery 연결 서비스 계정 역할 및 권한

BigQuery Cloud 리소스 연결을 사용하면 Knowledge Catalog에서 Cloud Storage에 저장된 구조화되지 않은 데이터에 액세스할 수 있습니다. 연결을 만들면 BigQuery가 자동으로 전용 서비스 계정을 만듭니다. 이 서비스 계정은 외부 데이터 소스에 연결하는 데 사용되는 ID 역할을 합니다.

기본적으로 이 서비스 계정에는 권한이 없습니다. 데이터가 포함된 Cloud Storage 버킷에 필요한 IAM 역할을 이 서비스 계정에 명시적으로 부여해야 합니다. 기존 BigQuery 연결을 사용하거나 소스 Cloud Storage 버킷과 동일한 위치에 새 연결을 만들 수 있습니다. 연결 공유에 관한 자세한 내용은 사용자와 연결 공유하기를 참고하세요.

BigQuery 연결 서비스 계정 (연결 세부정보의 연결 정보 섹션에서 ID 가져오기)에 객체 테이블을 읽고 추론을 실행하는 데 필요한 권한이 있는지 확인하려면 관리자에게 BigQuery 연결 서비스 계정 (연결 세부정보의 연결 정보 섹션에서 ID 가져오기)에 다음 IAM 역할을 부여해 달라고 요청하세요.

전체:
- 구조화되지 않은 데이터가 포함된 버킷에 대한 스토리지 객체 뷰어 (roles/storage.objectViewer)
- Vertex AI 사용자 (roles/aiplatform.user) 프로젝트

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

이러한 사전 정의된 역할에는 객체 테이블을 읽고 추론을 실행하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

객체 테이블을 읽고 추론을 실행하려면 다음 권한이 필요합니다.

전체:
- 비정형 데이터가 포함된 버킷에 대한 storage.buckets.get
- 비정형 데이터가 포함된 버킷에 대한 storage.objects.get
- 프로젝트에 대한 aiplatform.endpoints.predict 권한

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 BigQuery 연결 서비스 계정 (연결 세부정보의 연결 정보 섹션에서 ID를 가져옴)에 이러한 권한을 부여할 수도 있습니다.

파이프라인 실행 서비스 계정 역할 및 권한 (선택사항)

자동화된 파이프라인을 사용하여 추론된 데이터를 추출하려면 파이프라인을 실행할 전용 서비스 계정을 만들거나 제공해야 합니다. 이 실행 서비스 계정은 BigQuery에서 백그라운드 데이터 추출 및 분석 작업을 인증하고 실행하는 ID 역할을 합니다. 또한 기본 Dataform 서비스 계정에 이 실행 서비스 계정을 가장할 수 있는 권한을 부여해야 합니다.

파이프라인 실행 서비스 계정에 파이프라인을 사용하여 추론된 항목과 관계를 추출하는 데 필요한 권한이 있는지 확인하려면 관리자에게 프로젝트의 파이프라인 실행 서비스 계정에 다음 IAM 역할을 부여해 달라고 요청하세요.

전체:
- BigQuery 데이터 편집자 (roles/bigquery.dataEditor)
- BigQuery 작업 사용자 (roles/bigquery.jobUser)
- BigQuery 사용자 (roles/bigquery.user)
- Vertex AI 사용자 (roles/aiplatform.user)

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

이러한 사전 정의된 역할에는 파이프라인을 사용하여 추론된 항목과 관계를 추출하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

파이프라인을 사용하여 추론된 항목과 관계를 추출하려면 다음 권한이 필요합니다.

전체:
- bigquery.tables.create
- bigquery.tables.update
- bigquery.tables.get
- bigquery.tables.getData
- bigquery.jobs.create
- aiplatform.endpoints.predict

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 파이프라인 실행 서비스 계정에 이러한 권한을 부여할 수도 있습니다.

기본 Dataform 서비스 계정 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)에 파이프라인 실행 서비스 계정을 가장하는 데 필요한 권한이 있는지 확인하려면 관리자에게 파이프라인 실행 서비스 계정의 기본 Dataform 서비스 계정 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)에 다음 IAM 역할을 부여해 달라고 요청하세요.

중요: 이러한 역할은 사용자 계정이 아닌 기본 Dataform 서비스 계정 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)에 부여해야 합니다. 올바른 주체에 역할을 부여하지 않으면 권한 오류가 발생할 수 있습니다.

모두: 서비스 계정 토큰 생성자 (roles/iam.serviceAccountTokenCreator)

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

이러한 사전 정의된 역할에는 파이프라인 실행 서비스 계정을 가장하는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.

필수 권한

파이프라인 실행 서비스 계정을 가장하려면 다음 권한이 필요합니다.

전체: iam.serviceAccounts.getAccessToken

관리자는 커스텀 역할이나 다른 사전 정의된 역할을 사용하여 기본 Dataform 서비스 계정 (service-PROJECT_NUMBER@gcp-sa-dataform.iam.gserviceaccount.com)에 이러한 권한을 부여할 수도 있습니다.

객체 테이블 준비

비정형 데이터의 데이터 프로필 검사는 기존 BigQuery 객체 테이블에서 직접 작동합니다. 검사를 만들기 전에 비정형 데이터 (예: PDF)가 Cloud Storage 버킷에 저장되어 있고 Cloud 리소스 연결을 사용하여 해당 버킷에 대한 BigQuery 객체 테이블을 만들었는지 확인하세요.

나와 Knowledge Catalog 서비스 계정에 객체 테이블에서 사용하는 연결에 대한 BigQuery 연결 사용자 (roles/bigquery.connectionUser) 역할이 있는지 확인합니다.

객체 테이블을 만들고 필요한 연결을 설정하는 방법에 대한 자세한 내용은 객체 테이블 만들기를 참고하세요.

비정형 데이터의 데이터 프로필 스캔 만들기

객체 테이블에서 시맨틱 통계를 추출하려면 비정형 데이터 (UnstructuredDataProfileSpec)의 데이터 프로필 스캔을 만들어야 합니다. 이 스캔은 Vertex AI Gemini 2.5 Pro 모델을 사용하여 객체 테이블에서 참조하는 비정형 파일을 분석하고 추론된 메타데이터, 스키마, 관계를 생성합니다.

이번 초기 출시에서는 REST API를 사용해야만 스캔 생성이 지원됩니다.

REST API를 사용하여 비정형 데이터의 데이터 프로필 스캔을 만들려면 unstructuredDataProfileSpec와 함께 dataScans.create 메서드를 사용합니다.

POST https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans?dataScanId=DATASCAN
{
  "description": "Data profile scan for unstructured data",
  "data": {
    "resource": "//bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID/tables/TABLE_ID"
  },
  "executionSpec": {
    "trigger": {
      "onDemand": {}
    }
  },
  "unstructuredDataProfileSpec": {
    "customizedPrompt": "",
    "graphProfilePublishingEnabled": false
  }
}

다음을 바꿉니다.

PROJECT_ID: Google Cloud프로젝트의 ID
LOCATION: 리전 (Gemini 2.5 Pro를 지원해야 함) Google Cloud
DATASCAN: 데이터 프로필 스캔의 이름입니다.
DATASET_ID 및 TABLE_ID: BigQuery 데이터 세트 및 객체 테이블 이름입니다.

데이터 프로필 스캔 사양 매개변수

customizedPrompt: 선택사항. Gemini에게 추출할 특정 항목 또는 도메인 컨텍스트를 지시하는 자연어 프롬프트입니다 (예: Focus extraction on M&A contract terms, identifying purchasing entities, target companies, and agreed escrow amounts.). 기본적으로 빈 문자열 ("")입니다. 맞춤설정된 프롬프트의 최대 문자 길이에는 제한이 있습니다.
graphProfilePublishingEnabled: 선택사항. 스캔이 완료되면 추론된 그래프 프로필을 카탈로그에 자동으로 게시할지 여부입니다. 기본값은 false입니다.

Knowledge Catalog는 데이터 프로필 스캔을 실행하고 AI 생성 메타데이터로 카탈로그 항목을 보강합니다. 이 프로세스는 일반적으로 표준 데이터 세트의 경우 몇 분 정도 걸립니다.

예: 판매자 PDF에서 계약 조건 추출

다음 예에서는 객체 테이블 (seller_agreements_obj_table)에 저장된 판매자 계약 PDF를 분석하기 위해 데이터 프로필 스캔 (seller-contracts-scan)을 만드는 샘플 소매업체의 REST API 요청을 보여줍니다. 맞춤 프롬프트를 사용하여 Gemini에게 수수료율, 결제 조건과 같은 특정 비즈니스 용어를 추출하도록 지시합니다.

POST https://dataplex.googleapis.com/v1/projects/example-retail-project/locations/us-central1/dataScans?dataScanId=seller-contracts-scan
{
  "description": "Data profile scan for seller PDF agreements",
  "data": {
    "resource": "//bigquery.googleapis.com/projects/example-retail-project/datasets/marketplace_operations/tables/seller_agreements_obj_table"
  },
  "executionSpec": {
    "trigger": {
      "onDemand": {}
    }
  },
  "unstructuredDataProfileSpec": {
    "customizedPrompt": "Focus extraction on seller agreement terms, identifying seller business entities, commission rates, payment terms, and termination clauses in the PDFs.",
    "graphProfilePublishingEnabled": true
  }
}

데이터 프로필 스캔 실행

주문형으로 실행되도록 데이터 프로필 스캔을 구성한 경우 구조화되지 않은 데이터를 분석하려면 스캔을 수동으로 트리거해야 합니다.

REST API를 사용하여 주문형 데이터 프로필 스캔을 실행하려면 dataScans.run 메서드를 사용합니다.

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN:run"

다음을 바꿉니다.

PROJECT_ID: Google Cloud프로젝트의 ID
LOCATION: 데이터 프로필 스캔이 있는 Google Cloud 리전입니다.
DATASCAN: 데이터 프로필 스캔의 이름입니다.

데이터 프로필 스캔 결과 살펴보기

데이터 프로필 스캔이 완료되면 Knowledge Catalog에서 항목과 관계의 추론된 스키마가 포함된 그래프 프로필을 생성합니다. Google Cloud 콘솔 또는 REST API를 사용하여 이러한 결과를 살펴볼 수 있습니다.

콘솔

카탈로그(graphProfilePublishingEnabled: true)에 그래프 프로필 게시를 사용 설정한 경우 Knowledge Catalog에서 객체 테이블과 추론된 시맨틱 그래프를 볼 수 있습니다.

Google Cloud 콘솔에서 Knowledge Catalog 검색 페이지로 이동합니다.

검색 페이지로 이동
스캔에서 구성한 ID의 객체 테이블을 붙여넣고 검색합니다.
검색 결과에서 테이블을 클릭하여 항목 페이지를 엽니다.
세부정보 탭의 관점에서 그래프 프로필 관점 (dataplex-types.global.graph-profile)이 있는지 확인합니다. 이 관점에는 항목 및 관계에 대해 추론된 스키마가 포함되어 있습니다.
통계 탭을 클릭합니다. 통계 탭에서 다음 정보를 확인할 수 있습니다.
- 의미 추출: 추출 가능한 항목과 관계가 감지되었음을 나타내는 배너가 표시됩니다. SQL 또는 파이프라인 배포를 사용하여 데이터를 구체화하는 추출 버튼이 포함되어 있습니다.
- 설명. AI 생성, 사람이 읽을 수 있는 요약은 비구조적 데이터 콘텐츠를 설명합니다. 발견된 기본 노드(엔티티)와 노드가 가장자리(관계)를 통해 서로 매핑되는 방식을 설명합니다.
- 파이프라인: 이 리소스와 연결된 이전에 배포된 데이터 추출 파이프라인의 목록입니다. 표시 이름, 리전, 생성 시간, 파이프라인을 만든 사용자를 볼 수 있습니다.
- 추론된 항목 및 관계 시각적인 대화형 그래프에 구조화되지 않은 데이터의 검색된 시맨틱 구조가 표시됩니다. 그래프에는 Recipe, Ingredient과 같은 개별 항목을 나타내는 노드와 HasAllergenStatus와 같은 노드 간 연결을 나타내는 에지가 포함됩니다. 범례를 사용하여 특정 노드와 가장자리를 필터링하고 탐색할 수 있습니다.
- 항목 발견된 기본 항목의 자세한 목록입니다. 각 항목을 펼쳐 AI 생성 설명과 추론된 스키마를 볼 수 있습니다. 스키마에는 필드 이름, 데이터 유형, 필드 설명이 포함됩니다.
- 관계 엔티티 간에 발견된 연결의 자세한 목록입니다. 각 관계를 펼쳐 설명과 항목이 서로 매핑되는 방식을 정의하는 스키마를 볼 수 있습니다.

REST

REST API를 사용하여 스캔 작업 실행에서 직접 그래프 프로필 결과를 가져오려면 view=full와 함께 dataScans.jobs.get 메서드를 사용합니다.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/dataScans/DATASCAN/jobs/JOB_ID?view=full"

다음을 바꿉니다.

PROJECT_ID: Google Cloud프로젝트의 ID
LOCATION: 데이터 프로필 스캔이 있는 Google Cloud 리전입니다.
DATASCAN: 데이터 프로필 스캔의 이름입니다.
JOB_ID: 데이터 프로필 스캔 작업 실행의 고유 ID입니다.

다음 예시는 unstructuredDataProfileResult 및 graphProfile를 포함한 seller-contracts-scan 작업의 응답을 보여줍니다.

{
  "name": "projects/example-retail-project/locations/us-central1/dataScans/seller-contracts-scan/jobs/123e4567-e89b-12d3-a456-426614174000",
  "uid": "123e4567-e89b-12d3-a456-426614174000",
  "startTime": "2026-06-08T19:12:03.102Z",
  "endTime": "2026-06-08T19:15:28.415Z",
  "state": "SUCCEEDED",
  "type": "DATA_SCAN_TYPE_UNSTRUCTURED_DATA_PROFILE",
  "unstructuredDataProfileSpec": {
    "customizedPrompt": "Focus extraction on seller agreement terms, identifying seller business entities, commission rates, payment terms, and termination clauses in the PDFs.",
    "graphProfilePublishingEnabled": true
  },
  "unstructuredDataProfileResult": {
    "description": "The unstructured data contains seller agreement PDFs. The primary entities discovered are Seller Entity, Commission Rate, Payment Terms, and Termination Clause, mapped to each other through business agreement relationships.",
    "graphProfile": {
      "nodeTypes": [
        {
          "name": "Seller Entity",
          "description": "Discovered business entity representing the seller.",
          "fields": [
            {
              "name": "seller_name",
              "dataType": "STRING",
              "description": "The legal name of the seller.",
              "mode": "NULLABLE"
            },
            {
              "name": "address",
              "dataType": "STRING",
              "description": "The physical or mailing address of the seller.",
              "mode": "NULLABLE"
            }
          ]
        },
        {
          "name": "Commission Rate",
          "description": "Discovered agreed commission rate terms.",
          "fields": [
            {
              "name": "rate_percentage",
              "dataType": "NUMBER",
              "description": "The agreed commission percentage.",
              "mode": "NULLABLE"
            }
          ]
        },
        {
          "name": "Payment Terms",
          "description": "Discovered payment schedule and terms.",
          "fields": [
            {
              "name": "billing_cycle",
              "dataType": "STRING",
              "description": "The agreed billing frequency or payment schedule.",
              "mode": "NULLABLE"
            }
          ]
        }
      ],
      "edgeTypes": [
        {
          "name": "AgreedCommission",
          "description": "Defines the commission rate agreed by the seller entity.",
          "sourceNodeType": "Seller Entity",
          "targetNodeType": "Commission Rate"
        },
        {
          "name": "HasPaymentTerms",
          "description": "Defines the payment terms applicable to the seller entity.",
          "sourceNodeType": "Seller Entity",
          "targetNodeType": "Payment Terms"
        }
      ]
    }
  }
}

추론된 인사이트 업데이트

추론된 통계는 객체 테이블에 연결된 측면으로 Knowledge Catalog 카탈로그에 저장됩니다. REST API를 사용하여 이러한 통계를 수동으로 업데이트할 수 있습니다.

REST

REST API를 사용하여 추론된 통계를 업데이트하려면 다음 단계를 따르세요.

payload.json이라는 파일을 만들고 업데이트하려는 측면의 JSON 콘텐츠를 추가합니다. 예를 들면 다음과 같습니다.

{
  "aspects": {
    "dataplex-types.global.graph-profile": {
      "data": {
        "nodeTypes": [],
        "edgeTypes": []
      }
    }
  }
}

터미널에서 다음 명령어를 실행합니다.
```
curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-d @payload.json \
"https://dataplex.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/entryGroups/ENTRY_GROUP_ID/entries/ENTRY_ID?updateMask=aspects"
```
다음을 바꿉니다.
- PROJECT_ID: 프로젝트 ID(예: example-project)
- LOCATION: 항목의 위치입니다(예: us-central1).
- ENTRY_GROUP_ID: 항목 그룹의 ID입니다 (예: example-entry-group). BigQuery 객체 테이블의 경우 @bigquery를 사용하세요.
- ENTRY_ID: 항목의 ID입니다 (예: example-entry). Google Cloud 콘솔의 항목 세부정보 페이지에 있는 개요 탭에서 이 ID를 가져옵니다.

자세한 내용과 다른 언어의 코드 샘플은 항목 측면 업데이트를 참고하세요.

BigQuery로 데이터 추출

SQL 또는 자동화된 파이프라인을 사용하여 추론된 항목과 관계를 BigQuery의 구조화된 테이블 또는 뷰로 구체화할 수 있습니다.

Google Cloud 콘솔에서 Knowledge Catalog 검색 페이지로 이동합니다.

검색 페이지로 이동
스캔으로 생성된 객체 테이블을 검색합니다.
검색 결과에서 테이블을 클릭하여 항목 페이지를 엽니다.
통계 탭을 클릭합니다.
인사이트 탭에서 추출을 클릭합니다.
분석 요구사항과 구조화되지 않은 데이터의 규모에 따라 다음 방법 중 하나를 선택하세요.
- SQL로 추출: 신속한 임시 분석, 중소 규모 데이터 세트 또는 BigQuery 원격 모델을 사용하는 인프라 제로 접근 방식을 원하는 경우 이 옵션을 선택합니다.
  
  SQL을 사용하여 추출하려면 다음 단계를 따르세요.
  1. SQL로 추출을 선택합니다.
  2. SQL로 추출 창에서 대상 데이터 세트를 선택합니다. 데이터 세트는 소스와 동일한 위치에 있어야 합니다.
  3. 추출을 클릭합니다.
  4. BigQuery 편집기에서 ML.PROCESS_DOCUMENT 함수를 사용하는 사전 입력된 쿼리가 열립니다. 쿼리를 실행하여 표준 테이블과 뷰를 만듭니다.
  SQL을 사용하여 문서 통계를 추출하는 방법에 대한 자세한 내용은 ML.PROCESS_DOCUMENT 함수로 문서 처리하기를 참고하세요.
- 파이프라인으로 추출: 대규모 데이터 처리를 위해 또는 대량의 문서를 처리하기 위해 강력한 재시도 로직, 오류 처리, 자동 오케스트레이션이 필요한 경우 이 옵션을 선택합니다.
  
  파이프라인을 사용하여 추출하려면 다음 단계를 따르세요.
  1. 파이프라인으로 추출을 선택합니다.
  2. 파이프라인으로 추출 창에 파이프라인의 표시 이름을 입력합니다.
  3. 리전을 선택하세요.
  4. 대상 데이터 세트를 선택합니다. 데이터 세트는 소스와 동일한 위치에 있어야 합니다.
  5. 추출을 클릭합니다. 이렇게 하면 Dataform을 사용하여 데이터 구체화를 오케스트레이션하는 BigQuery 파이프라인이 생성됩니다.
  6. 파이프라인의 모든 작업을 실행하여 구조화된 노드 및 가장자리 뷰를 생성합니다.
  데이터 워크플로 실행에 대한 자세한 내용은 Dataform 소개를 참고하세요.

의미론적 통계를 추출하여 BigQuery에 구체화한 후 다음 작업을 수행할 수 있습니다.

구조화된 데이터 쿼리 새로 생성된 테이블에 대해 표준 SQL 쿼리를 실행하여 추출된 항목과 관계를 분석합니다.
기존 데이터와 조인 비정형 파일에서 추출한 정성적 통계를 기존의 정형 BigQuery 데이터 세트 (예: 파싱된 인보이스 데이터를 회계 테이블과 조인)와 결합합니다.
데이터 통계 탐색: BigQuery Studio의 데이터 통계 기능을 사용하여 새 구조화된 애셋에 대한 자연어 질문과 SQL 쿼리를 자동으로 생성합니다.
Gemini로 분석 BigQuery의 Gemini를 사용하여 대화형 분석을 실행하고, 추세를 요약하고, 추출된 데이터를 기반으로 데이터 스튜디오에서 대시보드를 만듭니다.

다음 단계

구조화되지 않은 데이터에 탐색 스캔을 사용하는 방법을 알아보세요.
데이터 탐색에 대해 자세히 알아보세요.
데이터 프로파일링 정보를 읽습니다.

구조화되지 않은 데이터에 데이터 프로필 사용 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

API 사용 설정

필수 역할 및 권한

기준 객체 테이블 역할

시맨틱 추론을 위한 추가 역할

추가 ID 및 역할 요약

최종 사용자 역할 및 권한

필수 권한

Dataplex 검색 서비스 에이전트 역할 및 권한

필수 권한

BigQuery 연결 서비스 계정 역할 및 권한

필수 권한

파이프라인 실행 서비스 계정 역할 및 권한 (선택사항)

필수 권한

필수 권한

객체 테이블 준비

비정형 데이터의 데이터 프로필 스캔 만들기

데이터 프로필 스캔 사양 매개변수

예: 판매자 PDF에서 계약 조건 추출

데이터 프로필 스캔 실행

데이터 프로필 스캔 결과 살펴보기

콘솔

REST

추론된 인사이트 업데이트

REST

BigQuery로 데이터 추출

다음 단계

구조화되지 않은 데이터에 데이터 프로필 사용