Google 애널리틱스의 Ask Advisor를 프로그래매틱 방식으로 사용하여 데이터 쿼리 및 분석

chat 메서드는 Data API의 프로그래매틱 액세스를 제공합니다. Google 애널리틱스의 Ask Advisor는 자연어를 사용하여 Google 애널리틱스 데이터를 쿼리, 분석, 진단하는 데 도움이 되는 AI 기반 애널리틱스 어시스턴트입니다.

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

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

개요

chat 메서드는 일회성 임시 데이터 질문과 멀티턴 대화 세션을 모두 지원합니다.

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

인증

chat 메서드를 호출하려면 다음 범위로 OAuth 2.0 승인이 필요합니다.

시작하기 전에

  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: 할당량 추적이 포함된 일회성 쿼리

새 대화를 시작하려면 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 시스템에 게시합니다.

다음 단계