변환 API를 사용한 SQL 쿼리 변환
이 문서에서는 BigQuery에서 BigQuery Migration API를 사용하여 다른 SQL 언어로 작성된 스크립트를 GoogleSQL 쿼리로 변환하는 방법을 설명합니다.
이 SQL 변환기에서 지원하는 SQL 언어 목록과 지원되는 처리 위치 목록은 지원되는 SQL 언어 및 위치를 참고하세요.
시작하기 전에
변환 작업을 제출하기 전에 다음 단계를 완료하세요.
번역 모드 선택
BigQuery Migration API는 두 가지 변환 모드를 지원합니다. 두 모드는 모두 동일한 API 메서드를 사용하고 비동기 작업으로 실행됩니다. 모드는 소스 SQL을 제공하는 방법과 변환된 SQL을 수신하는 방법이 다릅니다.
- 일괄 번역: API가 Cloud Storage에서 소스 파일을 읽고 번역된 파일과 보고서를 Cloud Storage에 씁니다. 전체 코드베이스를 이전하는 경우와 같이 한 번에 여러 파일을 번역하려면 일괄 번역을 사용하세요.
- 대화형 변환: 요청 본문에 SQL을 문자열 리터럴로 전달하고 워크플로 응답에서 변환된 SQL을 읽습니다. SQL 또는 변환 출력을 Cloud Storage에 저장할 필요가 없습니다. 애플리케이션이나 개발자 도구의 쿼리를 번역하는 등 필요에 따라 대화형 번역을 사용하여 개별 쿼리를 번역합니다.
번역 사용 설정
필요한 BigQuery Migration API를 사용 설정합니다. 자세한 내용은 SQL 변환 사용 설정을 참고하세요.
필수 권한
인터랙터 변환기, 변환 API 또는 일괄 SQL 변환기로 변환 작업을 만드는 데 필요한 권한을 얻으려면 관리자에게 parent 리소스에 대한 다음 IAM 역할을 부여해 달라고 요청하세요.
-
마이그레이션 작업 보기 및 모니터링:
MigrationWorkflow 뷰어 (
roles/bigquerymigration.viewer) -
마이그레이션 작업 제출:
MigrationWorkflow 편집자 (
roles/bigquerymigration.editor) -
입력 및 파일에 대해 Cloud Storage 버킷에 액세스:
스토리지 객체 관리자 (
roles/storage.objectAdmin) - 소스 및 대상 Cloud Storage 버킷에 대한 권한
역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
이러한 사전 정의된 역할에는 인터랙터 변환기, 변환 API 또는 일괄 SQL 변환기를 사용하여 변환 작업을 만드는 데 필요한 권한이 포함되어 있습니다. 필요한 정확한 권한을 보려면 필수 권한 섹션을 펼치세요.
필수 권한
인터랙터 변환기, 변환 API 또는 일괄 SQL 변환기로 변환 작업을 만들려면 다음 권한이 필요합니다.
-
bigquerymigration.workflows.create -
bigquerymigration.workflows.get -
bigquerymigration.workflows.list -
bigquerymigration.workflows.delete -
bigquerymigration.subtasks.get -
bigquerymigration.subtasks.list -
storage.objects.get -
storage.objects.list -
storage.objects.create
커스텀 역할이나 다른 사전 정의된 역할을 사용하여 이 권한을 부여받을 수도 있습니다.
Cloud Storage에 입력 파일 업로드
일괄 변환 작업의 경우 변환하려는 쿼리와 스크립트가 포함된 소스 파일을 Cloud Storage에 업로드해야 합니다. 소스 파일이 포함된 동일한 Cloud Storage 버킷에 메타데이터 파일 또는 구성 YAML 파일을 업로드할 수도 있습니다.
버킷 생성 및 Cloud Storage에 파일 업로드에 대한 자세한 내용은 버킷 만들기 및 파일 시스템에서 객체 업로드를 참조하세요.
지원되지 않는 SQL 함수
소스 쿼리에서 GoogleSQL에 직접 상응하는 SQL 함수를 참조하는 경우 도우미 사용자 정의 함수(UDF)를 사용할 수 있습니다. 자세한 내용은 헬퍼 UDF로 지원되지 않는 SQL 함수 처리를 참고하세요.
변환 작업 제출
BigQuery Migration API를 사용하여 변환 작업을 제출하려면 projects.locations.workflows.create 메서드를 사용하고 MigrationWorkflow 리소스의 인스턴스를 지원되는 태스크 유형으로 제공합니다.
작업을 제출한 후 작업 상태를 폴링할 수 있습니다.
일괄 변환 만들기
다음 curl 명령어는 입력 및 출력 파일이 Cloud Storage에 저장되는 일괄 변환 작업을 만듭니다. source_target_mapping 필드에는 소스 디렉터리를 대상 출력에 대한 선택적 상대 경로에 매핑하는 목록이 포함됩니다.
curl -d "{
\"tasks\": {
string: {
\"type\": \"TYPE\",
\"translation_details\": {
\"target_base_uri\": \"TARGET_BASE\",
\"source_target_mapping\": {
\"source_spec\": {
\"base_uri\": \"BASE\"
}
},
\"target_types\": \"TARGET_TYPES\",
}
}
}
}" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows
다음을 바꿉니다.
TYPE: 소스 및 대상 언어를 결정하는 변환의 태스크 유형입니다.TARGET_BASE: 모든 변환 출력에 대한 기본 URI입니다.BASE: 변환 소스로 읽는 모든 파일의 기본 URI입니다.TARGET_TYPES(선택사항): 생성된 출력 유형입니다. 지정하지 않으면 SQL이 생성됩니다.sql(기본값): 변환된 SQL 쿼리 파일입니다.suggestion: AI 생성 추천입니다.
출력은 출력 디렉터리의 하위 폴더에 저장됩니다. 하위 폴더의 이름은
TARGET_TYPES의 값을 기반으로 지정됩니다.TOKEN: 인증 토큰입니다. 토큰을 생성하려면gcloud auth print-access-token명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform범위 사용)를 사용합니다.PROJECT_ID: 변환을 처리할 프로젝트입니다.LOCATION: 작업이 처리되는 위치입니다.
위 명령어는 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 형식으로 작성된 워크플로 ID가 포함된 응답을 반환합니다.
일괄 변환 예시
Cloud Storage 디렉터리 gs://my_data_bucket/teradata/input/의 Teradata SQL 스크립트를 변환하고 결과를 Cloud Storage 디렉터리 gs://my_data_bucket/teradata/output/에 저장하려면 다음 쿼리를 사용하면 됩니다.
{
"tasks": {
"task_name": {
"type": "Teradata2BigQuery_Translation",
"translation_details": {
"target_base_uri": "gs://my_data_bucket/teradata/output/",
"source_target_mapping": {
"source_spec": {
"base_uri": "gs://my_data_bucket/teradata/input/"
}
},
}
}
}
}
이 호출은 생성된 워크플로 ID가 포함된 메시지를 "name" 필드에 반환합니다.
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"task_name": { /*...*/ }
},
"state": "RUNNING"
}
워크플로의 업데이트된 상태를 가져오려면 GET 쿼리를 실행합니다.
작업이 진행되면 Cloud Storage로 출력을 전송합니다. 요청된 모든 target_types가 생성되면 작업 state가 COMPLETED로 변경됩니다.
태스크가 성공하면 gs://my_data_bucket/teradata/output에서 변환된 SQL 쿼리를 찾을 수 있습니다.
AI 추천을 사용한 일괄 변환 예시
다음 예시에서는 gs://my_data_bucket/teradata/input/ Cloud Storage 디렉터리에 있는 Teradata SQL 스크립트를 변환하고 추가 AI 추천과 함께 결과를 Cloud Storage 디렉터리 gs://my_data_bucket/teradata/output/에 저장합니다.
{
"tasks": {
"task_name": {
"type": "Teradata2BigQuery_Translation",
"translation_details": {
"target_base_uri": "gs://my_data_bucket/teradata/output/",
"source_target_mapping": {
"source_spec": {
"base_uri": "gs://my_data_bucket/teradata/input/"
}
},
"target_types": "suggestion",
}
}
}
}
태스크가 성공적으로 실행되면 gs://my_data_bucket/teradata/output/suggestion Cloud Storage 디렉터리에서 AI 추천을 확인할 수 있습니다.
대화형 번역 만들기
다음 curl 명령어는 문자열 리터럴 입력과 출력을 사용하여 대화형 변환 작업을 만듭니다. source_target_mapping 필드에는 소스 literal 항목을 대상 출력에 대한 선택적 상대 경로로 매핑하는 목록이 포함됩니다.
curl -d "{
\"tasks\": {
string: {
\"type\": \"TYPE\",
\"translation_details\": {
\"source_target_mapping\": {
\"source_spec\": {
\"literal\": {
\"relative_path\": \"PATH\",
\"literal_string\": \"STRING\"
}
}
},
\"target_return_literals\": \"TARGETS\",
}
}
}
}" \
-H "Content-Type:application/json" \
-H "Authorization: Bearer TOKEN" -X POST https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows
다음을 바꿉니다.
TYPE: 소스 및 대상 언어를 결정하는 변환의 태스크 유형입니다.PATH: 파일 이름이나 경로와 유사한 리터럴 항목의 식별자입니다.STRING: 변환할 리터럴 입력 데이터(예: SQL)의 문자열입니다.TARGETS: 사용자가literal형식의 응답으로 직접 반환되기를 원하는 예상 대상입니다. 이는 대상 URI 형식이어야 합니다(예: GENERATED_DIR +target_spec.relative_path+source_spec.literal.relative_path). 이 목록에 없는 항목은 응답으로 반환되지 않습니다. 일반 SQL 변환용으로 생성된 디렉터리 GENERATED_DIR은sql/입니다.TOKEN: 인증 토큰입니다. 토큰을 생성하려면gcloud auth print-access-token명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform범위 사용)를 사용합니다.PROJECT_ID: 변환을 처리할 프로젝트입니다.LOCATION: 작업이 처리되는 위치입니다.
위 명령어는 projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID 형식으로 작성된 워크플로 ID가 포함된 응답을 반환합니다.
워크플로가 생성되면 작업 상태를 확인하여 결과를 확인합니다.
대화형 변환 예시
Apache Hive SQL 문자열 select 1을 대화형으로 변환하려면 다음 쿼리를 사용하면 됩니다.
"tasks": {
string: {
"type": "HiveQL2BigQuery_Translation",
"translation_details": {
"source_target_mapping": {
"source_spec": {
"literal": {
"relative_path": "input_file",
"literal_string": "select 1"
}
}
},
"target_return_literals": "sql/input_file",
}
}
}
리터럴에 원하는 relative_path를 사용할 수 있지만 target_return_literals에 sql/$relative_path를 포함하는 경우에만 변환된 리터럴이 결과에 표시됩니다. 단일 쿼리에 여러 리터럴을 포함할 수도 있습니다. 이 경우 각 상대 경로가 target_return_literals에 포함되어야 합니다.
이 호출은 생성된 워크플로 ID가 포함된 메시지를 "name" 필드에 반환합니다.
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"task_name": { /*...*/ }
},
"state": "RUNNING"
}
워크플로의 업데이트된 상태를 가져오려면 작업 상태를 확인합니다.
"state"가 COMPLETED로 변경되면 작업이 완료된 것입니다. 태스크가 성공하면 응답 메시지에 변환된 SQL이 표시됩니다.
{
"name": "projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00",
"tasks": {
"string": {
"id": "0fedba98-7654-3210-1234-56789abcdef",
"type": "HiveQL2BigQuery_Translation",
/* ... */
"taskResult": {
"translationTaskResult": {
"translatedLiterals": [
{
"relativePath": "sql/input_file",
"literalString": "-- Translation time: 2023-10-05T21:50:49.885839Z\n-- Translation job ID: projects/123456789/locations/us/workflows/12345678-9abc-def1-2345-6789abcdef00\n-- Source: input_file\n-- Translated from: Hive\n-- Translated to: BigQuery\n\nSELECT\n 1\n;\n"
}
],
"reportLogMessages": [
...
]
}
},
/* ... */
}
},
"state": "COMPLETED",
"createTime": "2023-10-05T21:50:49.543221Z",
"lastUpdateTime": "2023-10-05T21:50:50.462758Z"
}
작업 상태 확인
번역 작업은 비동기식으로 실행됩니다. 워크플로를 제출한 후 워크플로 ID와 함께 GET 요청을 전송하여 상태를 가져옵니다.
curl \ -H "Content-Type:application/json" \ -H "Authorization:Bearer TOKEN" \ -X GET https://bigquerymigration.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/workflows/WORKFLOW_ID
다음을 바꿉니다.
TOKEN: 인증 토큰입니다. 토큰을 생성하려면gcloud auth print-access-token명령어 또는 OAuth 2.0 Playground(https://www.googleapis.com/auth/cloud-platform범위 사용)를 사용합니다.PROJECT_ID: 변환 작업을 실행하는 프로젝트입니다.LOCATION: 작업이 처리되는 위치입니다.WORKFLOW_ID: 변환 워크플로를 만들 때 반환된 워크플로 ID입니다.
워크플로 상태
응답에는 워크플로의 현재 상태를 나타내는 state 필드가 포함됩니다.
STATE_UNSPECIFIED: 워크플로 상태가 지정되지 않았습니다.RUNNING: 워크플로가 활성 상태로 실행 중입니다. 상태가 변경될 때까지 엔드포인트를 주기적으로 폴링합니다.PAUSED: 워크플로가 일시중지되었습니다.COMPLETED: 워크플로가 성공적으로 완료되었습니다. 이제 결과를 가져올 수 있습니다.FAILED: 워크플로에서 오류가 발생했습니다. 응답의taskResult및reportLogMessages필드를 검사하여 오류 세부정보를 확인합니다.
워크플로 state가 COMPLETED 또는 FAILED에 도달하면 폴링을 중지할 수 있습니다.
결과 검색
결과를 가져오는 방법은 일괄 번역 또는 대화형 번역을 제출했는지 여부에 따라 다릅니다.
일괄 번역: 번역된 파일, 요약 보고서, AI 추천은
target_base_uri에서 지정한 Cloud Storage 대상 디렉터리에 기록됩니다. gcloud CLI 스토리지 명령어, Cloud Storage 클라이언트 라이브러리 또는 REST API를 사용하여 Cloud Storage에서 이러한 파일을 직접 읽을 수 있습니다.gcloud storage cp --recursive TARGET_URI LOCAL_DIRECTORY
다음을 바꿉니다.
TARGET_URI: 대상 기본 URI(예:gs://my_data_bucket/teradata/output/)LOCAL_DIRECTORY: 파일을 수신하는 로컬 디렉터리
대상 버킷에 생성된 파일에 대한 자세한 내용은 변환 출력 살펴보기를 참고하세요.
대화형 번역: 문자열 리터럴 입력 및
target_return_literals로 구성된 작업의 경우 번역된 질문이translatedLiterals필드 아래의 워크플로 응답에 직접 반환됩니다."taskResult": { "translationTaskResult": { "translatedLiterals": [ { "relativePath": "sql/input_file", "literalString": "SELECT 1;\n" } ] } }translatedLiterals의 각 항목에 대해literalString필드를 추출하여 번역된 질문을 가져옵니다.