chat 메서드는 Data API의 프로그래매틱 액세스를 제공합니다. Google 애널리틱스의 Ask Advisor는 자연어를 사용하여 Google 애널리틱스 데이터를 쿼리, 분석, 진단하는 데 도움이 되는 AI 기반 애널리틱스 어시스턴트입니다.
Ask Advisor는 Google 애널리틱스
사용자 인터페이스 내에서 대화형으로 사용할 수 있지만, chat API
를 사용하면 개발자, 자율 AI 에이전트, 내부 도구가 HTTP를 통해
프로그래매틱 방식으로 Ask Advisor와 상호작용할 수 있습니다.
중요: 이 제품은 AI를 사용하며 부정확한 정보를 표시할 수 있습니다. 채팅 활동은 제품 개선에 사용될 수 있으며, 사용 시 Google 약관, AI 사용 정책, 개인정보처리방침이 적용됩니다.
개요
chat 메서드는
일회성 임시 데이터 질문과 멀티턴 대화 세션을 모두 지원합니다.
- 일회성 쿼리: '지난주에 가장 많은 트래픽을 발생시킨 채널은 무엇인가요?'와 같은 즉각적인 분석 질문을 하고 구조화된 데이터 표와 함께 자연어 답변을 받습니다.
- 멀티턴 대화: 대화 기록을 유지하고 '해당 기간에 자연 트래픽이 감소한 이유는 무엇인가요?'와 같은 진단 후속 질문을 하려면
sessionId를 전달하세요. - 구조화된 데이터 응답: 응답에는 텍스트 설명 외에도 열 헤더와 행이 포함된 구조화된
table블록이 포함됩니다. - 채팅 할당량 모니터링:
returnPropertyQuota`returnPropertyQuota` 를true`true`로 설정하여 일별 및 시간당 남은 채팅 토큰 할당량을 검사합니다.
인증
chat 메서드를 호출하려면 다음 범위로 OAuth 2.0 승인이 필요합니다.
시작하기 전에
애플리케이션 기본 사용자 인증 정보 를 생성하고 계정에 필요한 범위를 부여하려면 다음을 실행합니다.
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"Google 애널리틱스 UI에서 사용자 계정에 Google 애널리틱스 속성에 대한 액세스 권한을 부여합니다.
다음을 입력하여 환경 변수를 구성합니다.
PROJECT_ID를 프로젝트 ID로 바꾸고PROPERTY_ID를 Google 애널리틱스 속성 ID로 바꿉니다.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
예시 1: 할당량 추적이 포함된 일회성 쿼리
새 대화를 시작하려면 ChatRequest
가 포함된 userQuery를 구성합니다.
returnPropertyQuota
를 true로 설정하여 남은 토큰 잔액을 검사합니다.
시나리오: 기기별 수익 및 전환율
지난 30일 동안 기기별 수익 및 세션 전환율을 비교하려고 합니다.
HTTP 요청
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"userQuery": "Compare our revenue and conversion rate across mobile vs desktop over the last 30 days.",
"returnPropertyQuota": true
}'
HTTP 응답
응답에는 다음이 포함됩니다.
- 후속 턴에 사용할 수 있는 새로 할당된
sessionId입니다. - 자연어 요약 (
text)과 구조화된 표 (table)가 모두 포함된blocks목록입니다. 텍스트 블록에는 텍스트 굵게 표시, 제목, 링크와 같은 마크다운 형식이 포함될 수 있습니다. - 속성의
propertyQuota세부정보입니다.
{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"blocks": [
{
"text": "Your report on revenue and conversion rates for mobile vs. desktop over the last 30 days (August 15 - September 13, 2026) is ready.\n\nHere is a summary of your revenue and conversion rate by device category:\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Total Revenue",
"dataType": "string"
},
{
"header": "User Conversion Rate",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "$17,412.62"
},
{
"value": "99.9%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "$15,309.41"
},
{
"value": "99.46%"
}
]
}
}
},
{
"text": "**Revenue and Conversion Rate Trends:**\n\nRevenue from desktop devices saw a peak on August 18th, while mobile revenue peaked on August 30th. Conversion rates remained high and relatively stable for both desktop and mobile throughout the period."
},
{
"text": "This product uses AI and may display inaccurate info. Your chat activity may be used to improve the product and your use is subject to Google's [Terms](https://policies.google.com/terms), [AI Use Policy](https://policies.google.com/terms/generative-ai/use-policy), and [Privacy Policy](https://policies.google.com/privacy). [Learn more about Chat AI Privacy](https://support.google.com/helpguide/answer/14185196)."
}
],
"propertyQuota": {
"tokensPerDay": {
"consumed": 26849,
"remaining": 3723151
},
"tokensPerHour": {
"consumed": 26849,
"remaining": 473151
}
}
}
예시 2: 멀티턴 대화형 진단
컨텍스트를 유지하면서 후속 질문을 하려면 요청에 sessionId
이전 응답에서 반환된 내용을 포함합니다.
시나리오: 이전 기간과 비교
이전 기기 비교에 이어 Advisor에게 결과를 이전 기간과 비교해 달라고 요청합니다.
HTTP 요청
curl -X POST \
"https://analyticsdata.googleapis.com/v1alpha/properties/${PROPERTY_ID}:chat" \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "x-goog-user-project: ${PROJECT_ID}" \
-H "Content-Type: application/json" \
-d '{
"sessionId": "692e9ab9-b338-4426-b006-a05f21ac7cd6",
"userQuery": "Compare results with the same period in the previous mounth."
}'
HTTP 응답
Ask Advisor는 세션 메모리를 사용하여 결과를 이전 기간과 상호 연결합니다.
{
"sessionId": "eb3284b2-49ce-4aed-b6d0-fdc15cb87b5f",
"blocks": [
{
"text": "The following table provides a detailed comparison of total revenue and user conversion rate by device category for the two periods.\n"
},
{
"table": {
"headers": [
{
"header": "Device Category",
"dataType": "string"
},
{
"header": "Metric",
"dataType": "string"
},
{
"header": "Jul 16 - Aug 15, 2026",
"dataType": "string"
},
{
"header": "Aug 16 - Sep 14, 2026",
"dataType": "string"
}
],
"rows": [
{
"columns": [
{
"value": "Desktop"
},
{
"value": "Total Revenue"
},
{
"value": "$17,412.62"
},
{
"value": "$19,565.46"
}
]
},
{
"columns": [
{
"value": "Desktop"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.90%"
},
{
"value": "1.95%"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "Total Revenue"
},
{
"value": "$13,997.19"
},
{
"value": "$15,309.41"
}
]
},
{
"columns": [
{
"value": "Mobile"
},
{
"value": "User Conversion Rate"
},
{
"value": "1.95%"
},
{
"value": "1.99%"
}
]
}
}
}
]
}
응답 구조 및 데이터 블록
ChatResponse
객체는 blocks
배열에서 구조화된 구성요소를 반환합니다.
| 블록 유형 | 필드 | 설명 |
|---|---|---|
| 설명 텍스트 | blocks[].text |
인간이 읽을 수 있는 설명 및 개략적인 분석 결과입니다. |
| 구조화된 표 | blocks[].table |
headers (이름 및 데이터 유형)와 rows (셀 값)가 포함된 테이블 형식 데이터 분류입니다. |
표 헤더 데이터 유형
blocks[].table.headers
의 열은 시맨틱 데이터 유형을 설명합니다.
string: 카테고리 텍스트 값 (예:"desktop","/shop/apparel").float: 숫자 부동 소수점 수입니다.
채팅 할당량 관리
Ask Advisor 요청은 쿼리 복잡성에 따라 채팅 토큰을 사용합니다.
returnPropertyQuota
가 true이면 현재 할당량 상태가
propertyQuota
에 반환됩니다.
tokensPerDay: 일일 토큰 한도 및 남은 잔액입니다.tokensPerHour: 시간당 슬라이딩 윈도우 비율 제한 및 남은 잔액입니다.
추천 통합 애플리케이션
properties.chat 메서드
는 팀과 도구 전반에서 여러 통합 아키텍처를 지원합니다.
엔터프라이즈 채팅 및 공동작업 봇
팀 채팅 작업공간을 Google 애널리틱스에 직접 연결합니다.
- 스레드 세션:
sessionId를 채팅 스레드 ID에 저장하여 팀원이 공동으로 후속 질문을 할 수 있도록 합니다. - 리치 카드 렌더링:
table응답 블록을 대화형 카드 위젯으로 형식 지정합니다.
자율 AI 에이전트 및 모델 컨텍스트 프로토콜 (MCP) 도구
LLM 오케스트레이터 (예: Gemini, LangChain, Claude)에 GA 분석 도구를 제공합니다.
- LLM이 복잡한
runReport쿼리를 생성하도록 강제하는 대신 LLM 에이전트는 자연어 의도로chat메서드를 호출할 수 있습니다. - 에이전트는 높은 사실성을 갖춘 요약과 구조화된 표를 수신하여 다중 채널 마케팅 추천으로 합성합니다.
자동화된 임원 브리핑 및 알림
이상 징후를 사전에 조사하는 예약된 서비스를 만듭니다.
- 일일 cron 작업 쿼리: "어제 주요 실적 측정항목을 요약하고 전환의 비정상적인 감소를 파악합니다."
- 이상 징후가 발견되면 스크립트는 후속 쿼리를 자동으로 트리거하여 근본 원인을 진단하고 요약 다이제스트를 내부 대시보드 또는 CRM 시스템에 게시합니다.
다음 단계
- 대화형 Ask Advisor Colab 노트북을 사용하여 Python 클라이언트 라이브러리를 통해 일회성 및 멀티턴 쿼리를 실행해 보세요.
properties.chatREST API 참조를 검토합니다.- Data API 할당량 및 한도에 대해 자세히 알아보세요.