Menggunakan Ask Advisor di Google Analytics secara terprogram untuk membuat kueri dan menganalisis data Anda

Metode chat Data API menyediakan akses terprogram ke Ask Advisor di Google Analytics — asisten analisis didukung AI yang membantu Anda membuat kueri, menganalisis, dan mendiagnosis data Google Analytics menggunakan bahasa alami.

Meskipun Tanya Penasihat tersedia secara interaktif dalam antarmuka pengguna Google Analytics, chat API memungkinkan developer, agen AI otonom, dan alat internal berinteraksi dengan Tanya Penasihat secara terprogram melalui HTTP.

Penting: Produk ini menggunakan AI dan mungkin menampilkan info yang tidak akurat. Aktivitas percakapan Anda dapat digunakan untuk meningkatkan kualitas produk, dan penggunaan Anda tunduk pada Persyaratan, Kebijakan Penggunaan AI, dan Kebijakan Privasi Google.

Ringkasan

Metode chat memungkinkan baik pertanyaan data ad hoc satu giliran dan sesi percakapan multi-giliran:

  1. Kueri satu giliran: Ajukan pertanyaan analisis langsung (seperti, "Apa saluran traffic teratas kita minggu lalu?") dan terima jawaban bahasa alami beserta tabel data terstruktur.
  2. Percakapan multi-giliran: Teruskan sessionId untuk mempertahankan histori percakapan dan ajukan pertanyaan lanjutan diagnostik (seperti, "Mengapa traffic organik menurun pada periode tersebut?").
  3. Respons data terstruktur: Selain narasi teks, respons berisi blok table terstruktur dengan header dan baris kolom.
  4. Pemantauan kuota chat: Periksa kuota token chat per hari dan per jam yang tersisa dengan menetapkan returnPropertyQuota ke true.

Autentikasi

Panggilan ke metode chat memerlukan otorisasi OAuth 2.0 dengan cakupan berikut:

Sebelum memulai

  1. Instal dan lakukan inisialisasi gcloud CLI.

  2. Untuk membuat Kredensial Default Aplikasi dan memberikan cakupan yang diperlukan ke akun Anda, jalankan perintah berikut:

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

  3. Di UI Google Analytics, berikan akses akun pengguna Anda ke properti Google Analytics.

  4. Konfigurasi variabel lingkungan Anda dengan memasukkan hal berikut. Ganti PROJECT_ID dengan ID project Anda dan PROPERTY_ID dengan ID properti Google Analytics Anda. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

Contoh 1: Kueri satu giliran dengan pelacakan kuota

Untuk memulai percakapan baru, buat ChatRequest yang berisi userQuery Anda. Tetapkan returnPropertyQuota ke true untuk memeriksa saldo token Anda yang tersisa.

Skenario: Pendapatan dan Rasio Konversi menurut Perangkat

Anda ingin membandingkan pendapatan dan rasio konversi sesi di seluruh perangkat selama 30 hari terakhir.

Permintaan 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
  }'

Respons HTTP

Respons berisi:

  • sessionId yang baru ditetapkan yang dapat Anda gunakan untuk giliran lanjutan.
  • Daftar blocks yang berisi ringkasan bahasa alami (text) dan tabel terstruktur (table). Blok teks dapat berisi pemformatan Markdown seperti teks tebal, judul, dan link.
  • Detail propertyQuota properti.
{
  "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
    }
  }
}

Contoh 2: Diagnostik percakapan multi-giliran

Untuk mengajukan pertanyaan lanjutan sambil mempertahankan konteks, sertakan sessionId yang ditampilkan oleh respons sebelumnya dalam permintaan Anda.

Skenario: Bandingkan dengan periode sebelumnya

Setelah perbandingan perangkat sebelumnya, Anda meminta Penasihat untuk membandingkan hasilnya dengan periode sebelumnya.

Permintaan 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."
  }'

Respons HTTP

Ask Advisor menggunakan memori sesi untuk mengorelasikan hasil dengan periode sebelumnya.

{
  "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%"
              }
            ]
          }
      }
    }
  ]
}

Struktur Respons &Blok Data

Objek ChatResponse menampilkan komponen terstruktur dalam array blocks:

Jenis Blok Kolom Deskripsi
Teks Naratif blocks[].text Penjelasan yang dapat dibaca manusia dan poin analisis tingkat tinggi.
Tabel Terstruktur blocks[].table Perincian data tabel yang berisi headers (nama dan jenis data) serta rows (nilai sel).

Jenis Data Header Tabel

Kolom di blocks[].table.headers menjelaskan jenis data semantik:

  • string: Nilai teks kategoris (misalnya, "desktop", "/shop/apparel").
  • float: Angka floating-point numerik.

Pengelolaan Kuota Chat

Permintaan Ask Advisor menggunakan token chat berdasarkan kompleksitas kueri. Status kuota saat ini ditampilkan di propertyQuota saat returnPropertyQuota adalah true:

  • tokensPerDay: Batas token harian dan saldo yang tersisa.
  • tokensPerHour: Pembatasan kapasitas jendela geser per jam dan saldo yang tersisa.

Aplikasi Integrasi yang Disarankan

Metode properties.chat memungkinkan beberapa arsitektur integrasi di seluruh tim dan alat:

Bot Chat &Kolaborasi Perusahaan

Hubungkan ruang kerja chat tim Anda langsung ke Google Analytics.

  • Sesi Berulir: Simpan sessionId terhadap ID thread chat untuk memungkinkan anggota tim mengajukan pertanyaan lanjutan secara kolaboratif.
  • Rendering Kartu Informasi: Format table blok respons menjadi widget kartu interaktif.

Agen AI Otonom &Alat Model Context Protocol (MCP)

Lengkapi orkestrator LLM (seperti Gemini, LangChain, atau Claude) dengan alat analisis GA:

  • Daripada memaksa LLM untuk membuat kueri runReport yang kompleks, agen LLM dapat memanggil metode chat dengan maksud bahasa alami.
  • Agen menerima ringkasan dengan tingkat faktualitas tinggi dan tabel terstruktur untuk disintesis menjadi rekomendasi pemasaran multi-saluran.

Ringkasan &Pemberitahuan Eksekutif Otomatis

Buat layanan terjadwal yang secara proaktif menyelidiki anomali:

  • Kueri tugas cron harian: "Ringkas metrik performa utama kemarin dan identifikasi penurunan konversi yang anomali."
  • Jika anomali ditemukan, skrip akan otomatis memicu kueri lanjutan untuk mendiagnosis penyebab utama dan memposting ringkasan ke dasbor internal atau sistem CRM.

Langkah berikutnya