Conversational Analytics API로 데이터 소스를 인증하고 연결

개발자는 geminidataanalytics.googleapis.com을 통해 액세스할 수 있는 Conversational Analytics API를 사용하여, 자연어로 BigQuery, Looker, Looker Studio의 정형 데이터에 대한 질문에 응답하는 인공지능(AI) 기반 채팅 인터페이스 또는 데이터 에이전트를 빌드할 수 있습니다.

이 페이지에서는 직접 HTTP 요청 또는 SDK를 사용하여 Conversational Analytics API에 인증하고 Looker, BigQuery, Looker Studio에서 데이터 연결을 구성하는 방법을 설명합니다. Conversational Analytics API는 표준 Google Cloud 인증 방법을 사용합니다.

시작하기 전에

Conversational Analytics API에 인증하고 데이터에 대한 연결을 구성하려면 Conversational Analytics API 사용 설정에 설명된 대로 기본 요건을 완료하고 Google Cloud 프로젝트에 필요한 API를 사용 설정해야 합니다.

Conversational Analytics API 인증

이 섹션에서는 HTTP 및 Python 메서드를 사용하여 필요한 승인 토큰을 가져와 geminidataanalytics.googleapis.com을 통해 Conversational Analytics API에 인증하는 방법을 설명합니다.

HTTP curl

다음의 샘플 curl 명령어는 Conversational Analytics API에 요청을 전송합니다. gcloud auth print-identity-token 명령어는 승인에 사용되는 액세스 토큰을 제공합니다. 코드 샘플에서 를 적절한 API 리소스 경로로 바꿉니다.

curl  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
https://geminidataanalytics.googleapis.com/

Python을 사용한 HTTP

다음의 샘플 Python 코드는 Google Cloud CLI와 Python을 사용하여 HTTP 인증을 위한 액세스 토큰을 가져오는 방법을 보여줍니다.

  billing_project = 'YOUR_BILLING_PROJECT'
  access_token = !gcloud auth application-default print-access-token
  url = f"https://geminidataanalytics.googleapis.com/v1beta/projects/{billing_project}:method"
  headers = {"Authorization": f'Bearer {access_token[0]}'}

샘플 값을 다음과 같이 바꿉니다.

YOUR_BILLING_PROJECT: 필요한 API를 사용 설정한 결제 프로젝트의 ID입니다.
method: 대상 엔드포인트의 리소스 경로입니다. 예를 들면 다음과 같습니다.
- 데이터 에이전트를 만들려면 POST 메서드와 리소스 경로 /v1beta/projects/{billing_project}/locations/global/dataAgents를 사용합니다.
- 기존 데이터 에이전트를 나열하려면 GET 메서드와 리소스 경로 /v1beta/projects/{billing_project}/locations/global/dataAgents를 사용합니다.

Python SDK

다음 Python 샘플 코드는 Colaboratory 내에서 Conversational Analytics API에 액세스하도록 Google 계정을 인증하는 방법을 보여줍니다.

from google.colab import auth
auth.authenticate_user()

Conversational Analytics API를 사용하여 Looker에 연결

Conversational Analytics API를 사용하여 Looker에 연결하려면 다음 정보를 제공해야 합니다.

Looker 인스턴스의 URL
데이터 소스로 사용할 특정 LookML 모델 및 Looker Explore

또한 인증하는 사용자 또는 서비스 계정에 필요한 Looker 권한이 있어야 합니다.

적절한 인증 방법 선택

그런 다음 Looker API 키(클라이언트 ID 및 클라이언트 보안 비밀번호) 또는 액세스 토큰을 사용하여 인증할 수 있습니다. 비공개 연결만 있는 Looker(Google Cloud 핵심 서비스)을 사용하는 고객은 액세스 토큰으로 인증해야 합니다.

다음 표를 사용하여 적절한 인증 방법을 선택하세요.

사용자 유형	인증 방법	Looker(원본)	Looker(Google Cloud 핵심 서비스)	비공개 연결만 사용하는 Looker(Google Cloud 핵심 서비스)	설명
사용자 삽입	액세스 토큰	`login_user`	`login_user`	해당 사항 없음	대상 사용자의 `access_token`에 대한 LookML 행 및 열 수준 권한(예: `access_filters`, `access_grants`, `sql_always_where`)을 따릅니다.
일반 사용자	액세스 토큰	`login_user` 또는 OAuth 클라이언트	OAuth 클라이언트	OAuth 클라이언트	대상 사용자의 `access_token`에 대한 LookML 행 및 열 수준 권한(예: `access_filters`, `access_grants`, `sql_always_where`)을 따릅니다.
Looker API 전용 서비스 계정	API 키	클라이언트 ID 및 보안 비밀	클라이언트 ID 및 보안 비밀	해당 사항 없음	모든 사용자가 Looker에 대한 동일한 수준의 액세스 권한을 공유합니다.

API 키는 사용자의 권한 및 액세스 수준을 사용합니다. 모든 사용자가 동일한 수준의 액세스 권한을 공유하는 애플리케이션을 빌드하는 경우 API 키가 유용할 수 있습니다.

액세스 토큰을 사용하면 대상 사용자의 access_token에 대한 LookML 행 및 열 수준 권한(예: access_filters, access_grants, sql_always_where)을 사용할 수 있습니다. 액세스 토큰은 멀티 테넌트 애플리케이션에 유용합니다.

필요한 Looker 권한

인증에 사용되는 사용자 또는 서비스 계정에는 쿼리할 모델에 대한 다음 권한이 포함된 Looker 역할이 부여되어야 합니다.

Looker 인스턴스의 관리 > 역할 섹션에서 이러한 권한을 구성할 수 있습니다.

Looker API 키로 인증

이 섹션에서는 직접 HTTP 요청 또는 SDK를 사용하여 Looker에 연결하도록 API 키를 생성하고 Conversational Analytics API를 구성하는 방법을 설명합니다.

Looker 인스턴스와의 연결을 설정하려면 유효한 Looker API 키가 필요합니다. 이는 Looker에서 생성되며 클라이언트 ID와 클라이언트 보안 비밀번호로 구성됩니다. Looker는 이러한 키를 사용하여 Looker API에 대한 요청을 승인합니다.

새 Looker API 키를 생성하는 방법에 대한 자세한 내용은 관리자 설정 - 사용자를 참조하세요. 인증 방법 및 Looker API 키 관리에 대해 자세히 알아보려면 Looker API 인증을 참조하세요.

Python을 사용한 HTTP

API 키(클라이언트 ID 및 보안 비밀번호)를 생성한 후 직접 HTTP 요청을 실행하여 Looker에 연결하도록 Conversational Analytics API를 구성할 수 있습니다. 다음 샘플 코드는 HTTP 요청 본문 내에 Looker 데이터 소스 세부정보와 API 키를 지정하는 방법을 보여줍니다.


looker_credentials = {
  "oauth": {
      "secret": {
        "client_id": "your_looker_client_id",
        "client_secret": "your_looker_client_secret",
      }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

샘플 값을 다음과 같이 바꿉니다.

your_looker_client_id: 생성된 Looker API 키의 클라이언트 ID입니다.
your_looker_client_secret: 생성된 Looker API 키의 클라이언트 보안 비밀번호입니다.
https://your_company.looker.com: Looker 인스턴스의 전체 URL입니다.
your_model: 사용할 LookML 모델의 이름입니다.
your_explore: 지정된 모델 내에서 사용할 Explore의 이름입니다.

Python SDK

API 키(클라이언트 ID 및 보안 비밀번호)를 생성한 후 Python을 사용하여 Looker에 연결하도록 Conversational Analytics API를 구성할 수 있습니다. 다음의 샘플 Python 코드는 Looker 데이터 소스 세부정보와 API 키를 Conversational Analytics API에 지정하는 방법을 보여줍니다.

looker_client_id = "YOUR-LOOKER-CLIENT-ID" # @param {type:"string"}
looker_client_secret = "YOUR-LOOKER-CLIENT-SECRET" # @param {type:"string"}
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI" # @param {type:"string"}
lookml_model = "YOUR-LOOKER-MODEL" # @param {type:"string"}
explore = "YOUR-LOOKER-EXPLORE" # @param {type:"string"}

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.secret.client_id = looker_client_id
credentials.oauth.secret.client_secret = looker_client_secret

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

샘플 값을 다음과 같이 바꿉니다.

YOUR-LOOKER-CLIENT-ID: 생성된 Looker API 키의 클라이언트 ID입니다.
YOUR-LOOKER-CLIENT-SECRET: 생성된 Looker API 키의 클라이언트 보안 비밀번호입니다.
YOUR-LOOKER-INSTANCE-URI: Looker 인스턴스의 전체 URL입니다.
YOUR-LOOKER-MODEL: 사용할 Looker 모델의 이름입니다.
YOUR-LOOKER-EXPLORE: 사용할 Looker Explore의 이름입니다.

액세스 토큰으로 인증

이 섹션에서는 액세스 토큰을 사용하여 Looker에 연결하도록 Conversational Analytics API를 구성하는 방법을 설명합니다.

Looker 인스턴스와의 연결을 설정하려면 유효한 OAuth2 access_token 값이 필요합니다. 이는 login Looker API 엔드포인트에 대한 성공적인 요청을 통해 생성됩니다.

액세스 토큰 생성에 대해 자세히 알아보려면 Looker API 인증 및 클라이언트 사용자 인증 정보를 제공하여 승인 토큰을 획득하는 방법을 참조하세요.

Python을 사용한 HTTP

다음 샘플 코드는 HTTP 요청 본문 내에 Looker 데이터 소스 세부정보와 액세스 토큰을 지정하는 방법을 보여줍니다.

보안을 강화하려면 Looker 액세스 토큰(access_token)을 환경 변수로 저장하는 것이 좋습니다.

looker_credentials = {
  "oauth": {
    "token": {
      "access_token": "YOUR-TOKEN",
    }
  }
}

looker_data_source = {
  "looker": {
    "explore_references": {
        "looker_instance_uri": "https://your_company.looker.com",
        "lookml_model": "your_model",
        "explore": "your_explore",
    }
  }
}

샘플 값을 다음과 같이 바꿉니다.

YOUR-TOKEN: Looker에 인증하기 위해 생성하는 access_token 값입니다.
https://your_company.looker.com: Looker 인스턴스의 전체 URL입니다.
your_model: 사용할 LookML 모델의 이름입니다.
your_explore: 지정된 모델 내에서 사용할 Explore의 이름입니다.

Python SDK

다음 샘플 Python 코드는 Python SDK를 사용하여 인증하기 위해 Looker 데이터 소스 세부정보와 액세스 토큰을 정의하는 방법을 보여줍니다.

보안을 강화하려면 Looker 액세스 토큰(access_token)을 환경 변수로 저장하는 것이 좋습니다.

looker_access_token = "YOUR-TOKEN"
looker_instance_uri = "YOUR-LOOKER-INSTANCE-URI"
lookml_model = "YOUR-LOOKER-MODEL"
explore = "YOUR-LOOKER-EXPLORE"

# Looker data source
looker_explore_reference = geminidataanalytics.LookerExploreReference()
looker_explore_reference.looker_instance_uri = looker_instance_uri
looker_explore_reference.lookml_model = lookml_model
looker_explore_reference.explore = explore

credentials = geminidataanalytics.Credentials()
credentials.oauth.token.access_token = looker_access_token

# Connect to your data source
datasource_references = geminidataanalytics.DatasourceReferences()
datasource_references.looker.explore_references = [looker_explore_reference]

샘플 값을 다음과 같이 바꿉니다.

YOUR-TOKEN: Looker에 인증하는 데 사용하는 access_token 값입니다.
YOUR-LOOKER-INSTANCE-URI: Looker 인스턴스의 전체 URL입니다.
YOUR-LOOKER-MODEL: 사용할 Looker 모델의 이름입니다.
YOUR-LOOKER-EXPLORE: 사용할 Looker Explore의 이름입니다.

JavaScript를 사용한 HTTP

다음 샘플 코드는 HTTP 요청 본문 내에 Looker 데이터 소스 세부정보와 액세스 토큰을 지정하는 방법을 보여줍니다.

보안을 강화하려면 Looker 액세스 토큰(access_token)을 환경 변수로 저장하는 것이 좋습니다.

const requestBody = {
  project: GCP_PROJECT,
  messages: [
    {
      user_message: {
        text: inputWithPreviousMessages,
      },
    },
  ],
  context: {
    system_instruction: agentConfig.system_instructions,
    datasource_references: {
      looker: {
        explore_references: [
          {
            looker_instance_uri: YOUR-LOOKER-INSTANCE-URI,
            lookml_model: YOUR-LOOKER-MODEL,
            explore: YOUR-LOOKER-EXPLORE,
          },
        ],
        credentials: {
          oauth: {
            token: {
              access_token: YOUR-TOKEN,
            },
          },
        },
      },
    },
  },
}

샘플 값을 다음과 같이 바꿉니다.

YOUR-LOOKER-INSTANCE-URI: Looker 인스턴스의 전체 URL입니다.
YOUR-LOOKER-MODEL: 사용할 LookML 모델의 이름입니다.
YOUR-LOOKER-EXPLORE: 지정된 모델 내에서 사용할 Explore의 이름입니다.
YOUR-TOKEN: Looker에 인증하기 위해 생성하는 access_token 값입니다.

Conversational Analytics API를 사용하여 BigQuery에 연결

Conversational Analytics API를 사용하여 하나 이상의 BigQuery 테이블에 연결하려면 테이블마다 관련 BigQuery 프로젝트에 인증해야 합니다. 테이블마다 다음 정보를 제공하세요.

BigQuery 프로젝트 ID
BigQuery 데이터 세트 ID
BigQuery 테이블 ID

Conversational Analytics API를 사용하면 연결할 수 있는 BigQuery 테이블 수에 엄격한 제한이 없습니다. 하지만 많은 수의 테이블에 연결하면 정확도가 떨어지거나 Gemini의 입력 토큰 한도를 초과할 수 있습니다. 여러 테이블에 걸쳐 복잡한 조인을 수행해야 하는 쿼리도 정확도가 낮은 응답을 반환할 수 있습니다.

이 섹션에서는 직접 HTTP 요청 또는 SDK를 사용하여 BigQuery에 연결하도록 Conversational Analytics API를 구성하는 방법을 설명합니다.

Python을 사용한 HTTP

다음 샘플 코드는 여러 BigQuery 테이블에 대한 연결을 정의합니다.

bigquery_data_sources = {
    "bq": {
      "tableReferences": [
        {
          "projectId": "my_project_id",
          "datasetId": "my_dataset_id",
          "tableId": "my_table_id"
        },
        {
          "projectId": "my_project_id_2",
          "datasetId": "my_dataset_id_2",
          "tableId": "my_table_id_2"
        },
        {
          "projectId": "my_project_id_3",
          "datasetId": "my_dataset_id_3",
          "tableId": "my_table_id_3"
        },
      ]
    }
}

샘플 값을 다음과 같이 바꿉니다.

my_project_id: 연결하려는 BigQuery 데이터 세트 및 테이블이 포함된 Google Cloud 프로젝트의 ID입니다. 공개 데이터 세트에 연결하려면 bigquery-public-data를 지정합니다.
my_dataset_id: BigQuery 데이터 세트의 ID입니다.
my_table_id: BigQuery 테이블의 ID입니다.

Python SDK

Colaboratory의 auth SDK를 사용하여 Colaboratory에 인증된 사용자의 사용자 인증 정보를 사용해 BigQuery에 인증할 수 있습니다.

다음 샘플 Python 코드는 여러 BigQuery 테이블에 대한 연결을 정의하고 Colaboratory 내에서 BigQuery에 Google 계정을 인증하는 방법을 보여줍니다.

from google.colab import auth
auth.authenticate_user()

# BigQuery data source
bigquery_table_reference = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference.project_id = "my_project_id"
bigquery_table_reference.dataset_id = "my_dataset_id"
bigquery_table_reference.table_id = "my_table_id"

bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "my_project_id_2"
bigquery_table_reference_2.dataset_id = "my_dataset_id_2"
bigquery_table_reference_2.table_id = "my_table_id_2"

bigquery_table_reference_3 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_3.project_id = "my_project_id_3"
bigquery_table_reference_3.dataset_id = "my_dataset_id_3"
bigquery_table_reference_3.table_id = "my_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]

샘플 값을 다음과 같이 바꿉니다.

my_project_id: 연결하려는 BigQuery 데이터 세트 및 테이블이 포함된 Google Cloud 프로젝트의 ID입니다. 공개 데이터 세트에 연결하려면 bigquery-public-data를 지정합니다.
my_dataset_id: BigQuery 데이터 세트의 ID입니다. 예를 들면 san_francisco입니다.
my_table_id: BigQuery 테이블의 ID입니다. 예를 들면 street_trees입니다.

Conversational Analytics API를 사용하여 Looker Studio에 연결

Conversational Analytics API를 사용하여 Looker Studio에 연결하려면 먼저 Looker Studio API를 사용 설정해야 합니다. 이 섹션에서는 직접 HTTP 요청 또는 SDK를 사용하여 Looker Studio에 연결하도록 Conversational Analytics API를 구성하는 방법을 설명합니다.

Looker Studio API 사용 설정

Looker Studio API를 사용 설정하려면 API 사용 설정 안내를 따르세요.

Looker Studio에 인증

Conversational Analytics API를 사용하여 Looker Studio에 연결하려면 Looker Studio에 인증하고 Looker Studio 데이터 소스 ID를 제공해야 합니다.

Python을 사용한 HTTP

Looker Studio API를 사용 설정한 후 Python으로 HTTP curl 요청을 실행하여 Looker Studio에 인증할 수 있습니다. 다음 샘플 코드는 HTTP 요청 본문 내에 Looker 데이터 소스 세부정보를 지정하는 방법을 보여줍니다.

직접 HTTP 요청을 수행하여 Looker Studio를 인증할 수 있습니다. 샘플 HTTP 호출은 다음 코드 블록에 표시됩니다.

looker_studio_data_source = {
    "studio":{
        "studio_references":
        [
            {
              "datasource_id": "your_studio_datasource_id"
            }
        ]
    }
}

your_studio_datasource_id를 사용하려는 Looker Studio 데이터 소스의 실제 데이터 소스 ID로 바꿉니다.

Python SDK

Looker Studio API를 사용 설정한 후에는 SDK를 사용하여 Looker Studio에 인증할 수 있습니다. 다음 샘플 Python 코드는 Looker 데이터 소스 세부정보를 지정하고 Looker Studio에 인증하는 방법을 보여줍니다.


datasource_id = "STUDIO-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를 사용하려는 Looker Studio 데이터 소스의 실제 데이터 소스 ID로 바꿉니다.

Conversational Analytics API로 데이터 소스를 인증하고 연결 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

시작하기 전에

Conversational Analytics API 인증

HTTP curl

Python을 사용한 HTTP

Python SDK

Conversational Analytics API를 사용하여 Looker에 연결

적절한 인증 방법 선택

필요한 Looker 권한

Looker API 키로 인증

Python을 사용한 HTTP

Python SDK

액세스 토큰으로 인증

Python을 사용한 HTTP

Python SDK

JavaScript를 사용한 HTTP

Conversational Analytics API를 사용하여 BigQuery에 연결

Python을 사용한 HTTP

Python SDK

Conversational Analytics API를 사용하여 Looker Studio에 연결

Looker Studio API 사용 설정

Looker Studio에 인증

Python을 사용한 HTTP

Python SDK

Conversational Analytics API로 데이터 소스를 인증하고 연결