애널리틱스 어드바이저를 사용하여 데이터 쿼리 및 분석

Data API의 chat 메서드는 자연어를 사용하여 Google 애널리틱스 데이터를 쿼리, 분석, 진단할 수 있는 AI 기반 분석 어시스턴트인 애널리틱스 어드바이저에 대한 프로그래매틱 액세스를 제공합니다.

애널리틱스 어드바이저는 Google 애널리틱스 사용자 인터페이스 내에서 대화형으로 사용할 수 있지만 chat API를 사용하면 개발자, 자율 AI 에이전트, 내부 도구가 HTTP를 통해 프로그래매틱 방식으로 애널리틱스 어드바이저와 상호작용할 수 있습니다.

참고: chat 메서드는 Data API의 v1alpha 버전에서 사용할 수 있습니다.

중요: 이 제품은 AI를 사용하며 부정확한 정보를 표시할 수 있습니다. 채팅 활동은 제품 개선에 사용될 수 있으며, 사용 시 Google 약관, AI 사용 정책, 개인정보처리방침이 적용됩니다.

개요

chat 메서드를 사용하면 단일 턴 임시 데이터 질문과 멀티 턴 대화형 세션을 모두 사용할 수 있습니다.

1. 단일 턴 질문: '지난주에 가장 많은 트래픽을 유도한 채널은 무엇이었어?'와 같은 즉각적인 분석 질문을 하고 구조화된 데이터 표와 함께 자연어 답변을 받습니다.
2. 멀티턴 대화: sessionId를 전달하여 대화 기록을 유지하고 진단 후속 질문('해당 기간에 자연 트래픽이 감소한 이유는 무엇인가요?' 등)을 합니다.
3. 구조화된 데이터 응답: 텍스트 설명 외에도 응답에는 열 헤더와 행이 있는 구조화된 table 블록이 포함됩니다.
4. 채팅 할당량 모니터링: returnPropertyQuota을 true로 설정하여 일별 및 시간별 채팅 토큰 할당량을 검사합니다.

인증

chat 메서드 호출에는 다음 범위의 OAuth 2.0 승인이 필요합니다.

• https://www.googleapis.com/auth/analytics.chatbot.read

참고: 이 범위는 표준 보고 방법 (예: runReport)에 필요한 범위와 다릅니다.

시작하기 전에

1. gcloud CLI를 설치하고 초기화합니다.

2. 애플리케이션 기본 사용자 인증 정보를 생성하고 계정에 필요한 범위를 부여하려면 다음을 실행합니다.

   gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"
   

3. Google 애널리틱스 UI에서 사용자 계정에 Google 애널리틱스 속성에 대한 액세스 권한을 부여합니다.

4. 다음을 입력하여 환경 변수를 구성합니다. PROJECT_ID를 프로젝트의 ID로 바꾸고 PROPERTY_ID를 Google 애널리틱스 속성의 ID로 바꿉니다.

     export PROJECT_ID=PROJECT_ID
     export PROPERTY_ID=PROPERTY_ID

예 1: 할당량 추적이 포함된 싱글턴 질문

새 대화를 시작하려면 userQuery이 포함된 ChatRequest을 구성합니다. 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을 포함하세요.

시나리오: 이전 기간과 비교

이전 기기 비교에 이어 상담사에게 결과를 이전 기간과 비교해 달라고 요청합니다.

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 응답

애널리틱스 어드바이저는 세션 메모리를 사용하여 결과를 이전 기간과 연관시킵니다.

{
  "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 배열에 구조화된 구성요소를 반환합니다.

차단 유형	필드	설명
Narrative Text(내러티브 텍스트)	blocks[].text	인간이 읽을 수 있는 설명과 개괄적인 분석 결과입니다.
구조화된 표	blocks[].table	headers (이름 및 데이터 유형) 및 rows (셀 값)이 포함된 표 형식 데이터 분석

표 헤더 데이터 유형

blocks[].table.headers의 열은 시맨틱 데이터 유형을 설명합니다.

• string: 범주형 텍스트 값 (예: "desktop", "/shop/apparel")
• float: 숫자 부동 소수점 숫자입니다.

채팅 할당량 관리

분석 어드바이저 요청은 쿼리 복잡성에 따라 채팅 토큰을 사용합니다. returnPropertyQuota이 true인 경우 현재 할당량 상태는 propertyQuota에 반환됩니다.

• tokensPerDay: 일일 토큰 한도 및 잔액입니다.
• tokensPerHour: 시간별 슬라이딩 윈도우 비율 제한 및 잔액입니다.

추천 통합 애플리케이션

properties.chat 메서드는 팀과 도구 전반에서 여러 통합 아키텍처를 잠금 해제합니다.

엔터프라이즈 채팅 및 공동작업 봇

팀 채팅 워크스페이스를 Google 애널리틱스에 직접 연결하세요.

• 스레드 세션: 팀원이 공동으로 후속 질문을 할 수 있도록 채팅 스레드 ID에 대해 sessionId를 저장합니다.
• 리치 카드 렌더링: table 응답 블록을 대화형 카드 위젯으로 포맷합니다.

자율 AI 에이전트 및 모델 컨텍스트 프로토콜 (MCP) 도구

LLM 오케스트레이터 (예: Gemini, LangChain, Claude)에 GA 분석 도구를 장착합니다.

• LLM이 복잡한 runReport 쿼리를 생성하도록 강제하는 대신 LLM 에이전트가 자연어 의도로 chat 메서드를 호출할 수 있습니다.
• 에이전트는 사실성이 높은 요약과 구조화된 표를 받아 다중 채널 마케팅 추천으로 종합합니다.

자동화된 경영진 브리핑 및 알림

이상 현상을 사전 대응 방식으로 조사하는 예약된 서비스를 만듭니다.

• 일일 크론 작업은 '어제의 주요 실적 측정항목을 요약하고 전환의 비정상적인 감소를 식별해 줘'라고 묻습니다.
• 이상치가 발견되면 스크립트가 자동으로 후속 질문을 트리거하여 근본 원인을 진단하고 요약 다이제스트를 내부 대시보드 또는 CRM 시스템에 게시합니다.