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

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

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

Penting: Produk ini menggunakan AI dan mungkin menampilkan info yang tidak akurat. Aktivitas chat Anda mungkin digunakan untuk meningkatkan kualitas produk ini dan penggunaannya oleh Anda tunduk kepada Persyaratan, Kebijakan Penggunaan AI, dan Kebijakan Privasi Google.

Ringkasan

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

  1. Kueri satu giliran: Ajukan pertanyaan analisis langsung (seperti, "Apa saluran traffic teratas kami minggu lalu?") dan terima jawaban dalam bahasa alami bersama dengan tabel data terstruktur.
  2. Percakapan multi-giliran: Teruskan sessionId untuk mempertahankan histori percakapan dan mengajukan 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 sisa kuota token chat per hari dan per jam 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 memberi akun Anda cakupan yang diperlukan, 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, beri akun pengguna Anda akses ke properti Google Analytics.

  4. Konfigurasikan variabel lingkungan Anda dengan memasukkan perintah 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 sisa saldo token Anda.

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

Responsnya 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-turn

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

Skenario: Membandingkan dengan periode sebelumnya

Sebagai tindak lanjut dari perbandingan perangkat sebelumnya, Anda meminta Advisor 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 menghubungkan 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 Pemblokiran Kolom Deskripsi
Teks Naratif blocks[].text Penjelasan yang dapat dibaca manusia dan poin-poin analisis tingkat tinggi.
Tabel Terstruktur blocks[].table Perincian data tabulasi 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 jika returnPropertyQuota adalah true:

  • tokensPerDay: Batas token harian dan sisa saldo.
  • tokensPerHour: Pembatasan kapasitas periode pengamatan per jam dan sisa saldo.

Aplikasi Integrasi yang Disarankan

Metode properties.chat membuka beberapa arsitektur integrasi di berbagai tim dan alat:

Bot Chat & Kolaborasi Perusahaan

Hubungkan ruang kerja chat tim Anda langsung ke Google Analytics.

  • Sesi Berangkai: Simpan sessionId dengan ID rangkaian pesan chat untuk memungkinkan anggota tim mengajukan pertanyaan lanjutan secara kolaboratif.
  • Rendering Kartu Informasi: Memformat blok respons table menjadi widget kartu interaktif.

Alat Agen AI Otonom & Model Context Protocol (MCP)

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

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

Pemberitahuan & Ringkasan Eksekutif Otomatis

Buat layanan terjadwal yang secara proaktif menyelidiki anomali:

  • Cron job harian membuat kueri: "Ringkas metrik performa utama kemarin dan identifikasi penurunan konversi yang tidak normal."
  • Jika ditemukan anomali, skrip akan otomatis memicu kueri lanjutan untuk mendiagnosis akar masalah dan memposting ringkasan ke dasbor internal atau sistem CRM.

Langkah berikutnya