이 페이지에서는 대화형 분석 API에 인증하는 방법을 설명합니다. 또한 직접 HTTP 요청 또는 SDK를 사용하여 Looker, BigQuery, 데이터 스튜디오, 데이터베이스(AlloyDB, Spanner용 GoogleSQL, MySQL용 Cloud SQL, PostgreSQL용 Cloud SQL)에서 데이터에 대한 연결을 구성하는 방법도 설명합니다. 대화형 분석 API는 표준 Google Cloud 인증 방법을 사용합니다.
시작하기 전에
대화형 분석 API에 인증하고 데이터에 대한 연결을 구성하려면 대화형 분석 API 사용 설정에 설명된 대로 기본 요건을 완료하고 Google Cloud 프로젝트에 필요한 API를 사용 설정해야 합니다.
고객 관리 암호화 키(CMEK)를 사용하여 대화형 분석 API 리소스를 보호하려면 API의 서비스 계정에 Cloud Key Management Service 키를 사용할 수 있는 권한을 부여해야 합니다. 자세한 내용은 CMEK 문서의 시작하기 전에를 참조하세요.
대화형 분석 API 인증
이 섹션에서는 HTTP 및 Python 메서드를 사용하여 필요한 승인 토큰을 가져와 대화형 분석 API에 인증하는 방법을 설명합니다. 다음 샘플에서는 리소스 위치를 기반으로 리전 엔드포인트 로직을 사용합니다. 리전 엔드포인트에 대한 자세한 내용은 데이터 레지던시를 참조하세요.
HTTP curl
다음 샘플 curl 명령어는 API 엔드포인트 메서드를 타겟팅하여 Google Cloud CLI에서 생성된 ID 토큰을 사용하여 인증된 요청을 전송하는 방법을 보여줍니다.
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://ENDPOINT_URL/v1/projects/PROJECT_ID/locations/LOCATION/METHOD
샘플 값을 다음과 같이 바꿉니다.
- ENDPOINT_URL: 위치에 해당하는 서비스 엔드포인트 URL입니다(예:
global기본 위치의 경우geminidataanalytics.googleapis.com,us멀티 리전의 경우geminidataanalytics.us.rep.googleapis.com). - PROJECT_ID: 필수 API를 사용 설정한 Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 저장되는 위치입니다(예:
global또는us-east4).METHOD: 대상 엔드포인트 메서드 또는 리소스 경로입니다(예: 에이전트를 만드는
dataAgents또는 특정 에이전트를 가져오는dataAgents/AGENT_ID).
Python을 사용하는 HTTP
다음 샘플 Python 코드는 API 엔드포인트 메서드를 타겟팅하여 액세스 토큰을 가져오고 인증된 HTTP 요청을 전송하는 방법을 보여줍니다. 코드는 지정된 위치 유형에 따라 엔드포인트 URL을 동적으로 빌드합니다.
billing_project = 'PROJECT_ID'
location = 'LOCATION'
access_token = !gcloud auth application-default print-access-token
# Set the base URL based on location.
if not location or location == "global":
base_url = "https://geminidataanalytics.googleapis.com"
elif "-" in location:
# Regional endpoints
base_url = f"https://geminidataanalytics-{location}.googleapis.com"
else:
# Multi-regional endpoints
base_url = f"https://geminidataanalytics.{location}.rep.googleapis.com"
url = f"{base_url}/v1/projects/{billing_project}/locations/{location}/METHOD"
headers = {"Authorization": f'Bearer {access_token[0]}'}
샘플 값을 다음과 같이 바꿉니다.
- PROJECT_ID: 필수 API를 사용 설정한 Google Cloud 프로젝트의 ID입니다.
LOCATION: 리소스가 저장되는 위치입니다(예:
global또는us-east4).METHOD: 대상 엔드포인트 메서드 또는 리소스 경로입니다. 예를 들면 다음과 같습니다.
- 데이터 에이전트를 만들려면
POST메서드를 사용하고dataAgents를 지정합니다. - 기존 데이터 에이전트를 나열하려면
GET메서드를 사용하고dataAgents를 지정합니다.
- 데이터 에이전트를 만들려면
Python SDK
다음 Python 샘플 코드는 Colaboratory 내에서 Conversational Analytics API에 액세스하도록 Google 계정을 인증하는 방법을 보여줍니다.
from google.colab import auth
auth.authenticate_user()
Conversational Analytics API를 사용하여 Looker에 연결
Looker Explore에 연결하는 데 필요한 역할 및 권한, 승인 옵션, 샘플 코드는 Looker에 연결을 참조하세요. 비공개 연결만 사용하는 인스턴스의 경우 비공개 연결을 사용하는 Looker(Google Cloud 핵심 서비스) 인스턴스에 연결을 참조하세요.
Conversational Analytics API를 사용하여 BigQuery에 연결
이 섹션에서는 직접 HTTP 요청 또는 SDK를 사용하여 BigQuery에 연결하도록 Conversational Analytics API를 구성하는 방법을 설명합니다. 대화형 분석 API는 BigQuery 테이블 및 BigQuery Graph를 사용한 그래프에 대한 연결을 지원합니다.
대화형 분석 API를 사용하면 연결할 수 있는 BigQuery 테이블 수에 대한 엄격한 제한이 없습니다. 하지만 많은 수의 테이블에 연결하면 정확성이 떨어지거나 Gemini의 입력 토큰 한도를 초과할 수 있습니다. 여러 테이블에 걸쳐 복잡한 조인을 수행해야 하는 쿼리는 정확도가 낮은 응답을 반환할 수 있습니다.
테이블에 연결
하나 이상의 BigQuery 테이블에 연결하려면 각 테이블의 프로젝트 ID, 데이터 세트 ID, 테이블 ID를 제공합니다.
다음 예시에서는 HTTP 요청 또는 Python SDK를 사용하여 하나 이상의 BigQuery 테이블에 연결하는 방법을 보여줍니다.
Python을 사용하는 HTTP
다음 샘플 코드는 여러 BigQuery 테이블에 대한 연결을 정의합니다.
bigquery_data_sources = {
"bq": {
"tableReferences": [
{
"projectId": "PROJECT_ID",
"datasetId": "DATASET_ID",
"tableId": "TABLE_ID"
},
{
"projectId": "PROJECT_ID_2",
"datasetId": "DATASET_ID_2",
"tableId": "TABLE_ID_2"
},
{
"projectId": "PROJECT_ID_3",
"datasetId": "DATASET_ID_3",
"tableId": "TABLE_ID_3"
},
]
}
}
샘플 값을 다음과 같이 바꿉니다.
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: 연결하려는 BigQuery 데이터 세트 및 테이블이 포함된 Google Cloud 프로젝트의 ID입니다. 공개 데이터 세트에 연결하려면
bigquery-public-data를 지정합니다. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: BigQuery 데이터 세트의 ID(또는 Lakehouse 런타임 카탈로그 테이블의 경우
catalog.namespace)입니다. - TABLE_ID, TABLE_ID_2, TABLE_ID_3: BigQuery 테이블의 ID(또는 Lakehouse 런타임 카탈로그 테이블의 테이블 이름)입니다.
Python SDK
Colaboratory의 auth SDK를 사용하여 Google 계정 사용자 인증 정보로 인증하고 Colab 클라이언트가 사용자 인증 정보를 사용하여 BigQuery에 액세스하도록 승인할 수 있습니다.
다음 샘플 Python 코드는 여러 BigQuery 테이블에 대한 연결을 정의하고 Colaboratory 내에서 Google 계정 사용자 인증 정보를 사용하여 요청을 승인하는 방법을 보여줍니다.
from google.colab import auth
auth.authenticate_user()
# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "PROJECT_ID"
bigquery_table_reference.dataset_id = "DATASET_ID"
bigquery_table_reference.table_id = "TABLE_ID"
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "PROJECT_ID_2"
bigquery_table_reference_2.dataset_id = "DATASET_ID_2"
bigquery_table_reference_2.table_id = "TABLE_ID_2"
bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "PROJECT_ID_3"
bigquery_table_reference_3.dataset_id = "DATASET_ID_3"
bigquery_table_reference_3.table_id = "TABLE_ID_3"
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.table_references = [bigquery_table_reference, bigquery_table_reference_2, bigquery_table_reference_3]
샘플 값을 다음과 같이 바꿉니다.
- PROJECT_ID, PROJECT_ID_2, PROJECT_ID_3: 연결하려는 BigQuery 데이터 세트 및 테이블이 포함된 Google Cloud 프로젝트의 ID입니다. 공개 데이터 세트에 연결하려면
bigquery-public-data를 지정합니다. - DATASET_ID, DATASET_ID_2, DATASET_ID_3: BigQuery 데이터 세트의 ID(또는 Lakehouse 런타임 카탈로그 테이블의 경우
catalog.namespace)입니다. 예를 들면san_francisco입니다. - TABLE_ID, TABLE_ID_2, TABLE_ID_3: BigQuery 테이블의 ID(또는 Lakehouse 런타임 카탈로그 테이블의 테이블 이름)입니다. 예를 들면
street_trees입니다.
BigQuery Graph에 연결
다음 예시에서는 HTTP 요청 또는 Python SDK를 사용하여 BigQuery Graph로 하나 이상의 그래프에 연결하는 방법을 보여줍니다.
BigQuery 버전 요구사항 및 그래프 쿼리 제한사항에 대한 자세한 내용은 BigQuery Graph에 연결을 참조하세요.
Python을 사용하는 HTTP
다음 샘플 코드는 BigQuery 그래프에 대한 연결을 정의합니다.
bigquery_data_sources = {
"bq": {
"propertyGraphReferences": [
{
"projectId": "GRAPH_PROJECT_ID",
"datasetId": "GRAPH_DATASET_ID",
"propertyGraphId": "GRAPH_ID"
}
]
}
}
샘플 값을 다음과 같이 바꿉니다.
- GRAPH_PROJECT_ID: BigQuery 그래프가 포함된 Google Cloud 프로젝트의 ID입니다.
- GRAPH_DATASET_ID: 그래프가 포함된 BigQuery 데이터 세트의 ID입니다.
- GRAPH_ID: BigQuery 그래프의 ID입니다.
Python SDK
Colaboratory의 auth SDK를 사용하여 Colaboratory에 인증된 사용자의 사용자 인증 정보를 사용해 BigQuery에 인증할 수 있습니다.
다음 샘플 Python 코드는 BigQuery 그래프에 대한 연결을 정의합니다.
from google.colab import auth
auth.authenticate_user()
# BigQuery graph reference
graph_reference = geminidataanalytics.BigQueryPropertyGraphReference()
graph_reference.project_id = "GRAPH_PROJECT_ID"
graph_reference.dataset_id = "GRAPH_DATASET_ID"
graph_reference.property_graph_id = "GRAPH_ID"
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.bq.property_graph_references = [graph_reference]
샘플 값을 다음과 같이 바꿉니다.
- GRAPH_PROJECT_ID: BigQuery 그래프가 포함된 Google Cloud 프로젝트의 ID입니다.
- GRAPH_DATASET_ID: 그래프가 포함된 BigQuery 데이터 세트의 ID입니다.
- GRAPH_ID: BigQuery 그래프의 ID입니다.
Conversational Analytics API를 사용하여 데이터 스튜디오에 연결
Conversational Analytics API를 사용하여 데이터 스튜디오에 연결하려면 먼저 데이터 스튜디오 API를 사용 설정해야 합니다. 이 섹션에서는 직접 HTTP 요청 또는 SDK를 사용하여 데이터 스튜디오에 연결하도록 대화형 분석 API를 구성하는 방법을 설명합니다.
데이터 스튜디오 Pro에서 대화형 분석 API를 사용하려면 Pro 구독이 VPC-SC 경계 외부에 있어야 합니다.
Data Studio API 사용 설정
Data Studio API를 사용 설정하려면 API 사용 설정 안내를 따르세요.
데이터 스튜디오에 인증
대화형 분석 API를 사용하여 데이터 스튜디오에 연결하려면 인증된 사용자 또는 서비스 계정이 데이터 스튜디오 데이터 소스에 액세스할 수 있는 권한이 있는지 확인한 후 데이터 소스 ID를 제공해야 합니다.
Python을 사용하는 HTTP
Data Studio API를 사용 설정한 후 Python으로 HTTP curl 요청을 실행하여 데이터 스튜디오에 연결할 수 있습니다. 다음 샘플 코드는 HTTP 요청 본문 내에 데이터 스튜디오 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.
직접 HTTP 요청을 통해 데이터 스튜디오에 연결할 수 있습니다. 다음 코드 블록에는 샘플 HTTP 호출이 나와 있습니다.
looker_studio_data_source = {
"studio":{
"studio_references":
[
{
"datasource_id": "DATASOURCE_ID"
}
]
}
}
your_studio_datasource_id를 사용하려는 데이터 스튜디오 데이터 소스의 실제 데이터 소스 ID로 바꿉니다.
Python SDK
Data Studio API를 사용 설정한 후 SDK를 사용하여 데이터 스튜디오에 연결할 수 있습니다. 다음 샘플 Python 코드는 데이터 스튜디오 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.
datasource_id = "DATASOURCE_ID"
# Looker Studio
studio_references = geminidataanalytics.StudioDatasourceReference()
studio_references.datasource_id = studio_datasource_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.studio.studio_references = [studio_references]
STUDIO-DATASOURCE-ID를 사용하려는 데이터 스튜디오 데이터 소스의 실제 데이터 소스 ID로 바꿉니다.
대화형 분석 API를 사용하여 데이터베이스에 연결
대화형 분석 API를 사용하여 데이터베이스에 연결하려면 데이터베이스 인스턴스에 필요한 IAM 권한이 있어야 합니다. 필요한 경우 데이터베이스 데이터 소스와 함께 컨텍스트 세트(프리뷰)를 사용하는 경우 컨텍스트 세트를 만들거나 업로드하거나 관리하려면 Knowledge Catalog API를 사용 설정하고 프로젝트에 Dataplex 카탈로그 편집자(roles/dataplex.catalogEditor) 또는 Dataplex 카탈로그 관리자(roles/dataplex.catalogAdmin) 역할을 부여해야 합니다. 자세한 내용은 컨텍스트 세트 권한을 참고하세요.
PostgreSQL용 AlloyDB에 연결
사용자 또는 서비스 계정에 alloydb.databaseUser 역할이 있어야 합니다. 자세한 내용은 AlloyDB, IAM 데이터베이스 인증을 참조하세요.
Python을 사용하는 HTTP
다음 샘플 코드는 HTTP 요청 본문에 AlloyDB 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.
alloydb_data_sources = {
"alloydb": {
"database_reference": {
"project_id": alloydb_project_id,
"region": location,
"cluster_id": alloydb_cluster_id,
"instance_id": alloydb_instance_id,
"database_id": alloydb_database_id,
"table_ids":["table1", "table2", "table3"]
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/alloydb_project_id/locations/{location}/contextSets/your_context_set_id"
# }
}
}
샘플 값을 다음과 같이 바꿉니다.
- your_table_id: 쉼표로 구분된 테이블 ID 목록입니다. 설정하지 않으면 데이터베이스의 모든 테이블이 고려됩니다.
- your_context_set_id: (선택사항) 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 관한 자세한 내용은 AlloyDB 문서를 참조하세요.
Python SDK
다음 샘플 Python 코드는 Python SDK를 사용하여 AlloyDB 데이터 소스 세부정보를 정의하는 방법을 보여줍니다.
# AlloyDB data source
alloydb_table_ids = ["your_table_id_1", "your_table_id_2"]
alloydb_context_set_id = "your_context_set_id"
alloydb_reference = geminidataanalytics.AlloyDbReference()
alloydb_reference.database_reference.table_id = alloydb_table_ids
alloydb_reference_database_reference.project_id = billing_project
alloydb_reference_database_reference.region = "us-central1" # Example region
alloydb_reference_database_reference.cluster_id = alloydb_cluster_id
alloydb_reference_database_reference.instance_id = alloydb_instance_id
alloydb_reference_database_reference.database_id = alloydb_database_id
# optional set agent context reference
# alloydb_ref_1.agent_context_reference.context_set_id = f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
alloydb_reference.agent_context_reference.context_set_id = alloydb_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.alloydb.alloydb_reference = alloydb_reference
샘플 값을 다음과 같이 바꿉니다.
- your_table_id_1: AlloyDB 인스턴스의 첫 번째 테이블 ID입니다.
- your_table_id_2: AlloyDB 인스턴스의 두 번째 테이블 ID입니다.
- your_context_set_id: 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 관한 자세한 내용은 AlloyDB 문서를 참고하세요.
Spanner용 GoogleSQL에 연결
사용자 또는 서비스 계정에 spanner.databaseReader 역할이 있어야 합니다. 자세한 내용은 IAM 역할 적용을 참조하세요.
Python을 사용하는 HTTP
다음 샘플 코드는 HTTP 요청 본문 내에 Spanner용 GoogleSQL 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.
spanner_data_sources = {
"spanner_reference": {
"database_reference": {
"project_id": spanner_project_id,
"region": location,
"engine": engine,
"instance_id": spanner_instance_id,
"database_id": spanner_database_id,
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/{billing_project}/locations/{location}/contextSets/your_context_set_id"
# }
}
}
샘플 값을 다음과 같이 바꿉니다.
- your_table_id_1: Spanner용 GoogleSQL 인스턴스의 첫 번째 테이블 ID입니다.
- your_table_id_2: Spanner용 GoogleSQL 인스턴스의 두 번째 테이블 ID입니다.
- your_context_set_id: 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 대한 자세한 내용은 Spanner 문서를 참조하세요.
Python SDK
다음 샘플 Python 코드는 Python SDK를 사용하여 Spanner용 GoogleSQL 데이터 소스 세부정보를 정의하는 방법을 보여줍니다.
# Spanner data source
spanner_table_ids = ["your_table_id_1", "your_table_id_2"]
spanner_context_set_id = "your_context_set_id"
spanner_reference = geminidataanalytics.SpannerReference()
spanner_reference.database_reference.table_id = spanner_table_ids
spanner_reference.agent_context_reference.context_set_id = spanner_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.spanner.spanner_reference = spanner_reference
샘플 값을 다음과 같이 바꿉니다.
- your_table_id_1: Spanner용 GoogleSQL 인스턴스의 첫 번째 테이블 ID입니다.
- your_table_id_2: Spanner용 GoogleSQL 인스턴스의 두 번째 테이블 ID입니다.
- your_context_set_id: 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 대한 자세한 내용은 Spanner 문서를 참조하세요.
MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL에 연결
다음 섹션에서는 MySQL용 Cloud SQL과 PostgreSQL용 Cloud SQL에 연결하는 방법을 설명합니다. 사용자 또는 서비스 계정에 cloudsql.studioUser 및 cloudsql.instanceUser 역할이 있어야 합니다. 자세한 내용은 MySQL용 Cloud SQL의 IAM 데이터베이스 인증으로 사용자 관리 및 PostgreSQL용 Cloud SQL의 IAM 데이터베이스 인증으로 사용자 관리를 참조하세요.
Python을 사용하는 HTTP
다음 샘플 코드는 HTTP 요청 본문 내에 MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.
cloudsql_data_source = {
"cloudSqlReference": {
"databaseReference": {
"engine": MYSQL,
"project_id": cloud-db-nl2sql,
"region": us-central1,
"instance_id": nl2sql-birdsql-mysql,
"database_id": financial
},
# Optional: Include this if you have pre-authored context for the agent
# "agent_context_reference": {
# "context_set_id": f"projects/cloud-db-nl2sql/locations/us-central1/contextSets/bdf_pg_all_templates\"
# }
}
}
샘플 값을 다음과 같이 바꿉니다.
- your_table_id_1: MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 인스턴스의 첫 번째 테이블 ID입니다.
- your_table_id_2: MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 인스턴스의 두 번째 테이블 ID입니다.
- your_context_set_id: 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 대한 자세한 내용은 MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 문서를 참조하세요.
Python SDK
다음 샘플 Python 코드는 Python SDK를 사용하여 MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 데이터 소스 세부정보를 정의하는 방법을 보여줍니다.
# Cloud SQL data source
cloudsql_table_ids = ["your_table_id_1", "your_table_id_2"]
cloudsql_context_set_id = "your_context_set_id"
cloudsql_reference = geminidataanalytics.CloudSqlReference()
cloudsql_reference.database_reference.table_id = cloudsql_table_ids
cloudsql_reference.agent_context_reference.context_set_id = cloudsql_context_set_id
# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.cloudsql.cloudsql_reference = cloudsql_reference
샘플 값을 다음과 같이 바꿉니다.
- your_table_id_1: MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 인스턴스의 첫 번째 테이블 ID입니다.
- your_table_id_2: MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 인스턴스의 두 번째 테이블 ID입니다.
- your_context_set_id: 검색할 컨텍스트 세트의 전체 ID입니다. 컨텍스트 세트 ID를 찾는 방법에 대한 자세한 내용은 MySQL용 Cloud SQL 및 PostgreSQL용 Cloud SQL 문서를 참조하세요.