Verilerinizi sorgulamak ve analiz etmek için Google Analytics'teki Ask Advisor'ı programatik olarak kullanma

chat yöntemi, Veri API'si'nin bir parçasıdır ve Google Analytics'teki Ask Advisor'a programatik erişim sağlar. Bu özellik, Google Analytics verilerinizi doğal dili kullanarak sorgulamanıza, analiz etmenize ve teşhis etmenize yardımcı olan yapay zeka destekli bir analiz asistanıdır.

Ask Advisor, Google Analytics kullanıcı arayüzünde etkileşimli olarak kullanılabilirken chat API, geliştiricilerin, bağımsız yapay zeka aracıların ve dahili araçların HTTP üzerinden Ask Advisor ile programatik olarak etkileşim kurmasına olanak tanır.

Önemli: Bu ürün yapay zeka kullanıyor ve yanlış bilgiler gösterebilir. Sohbet etkinliğiniz, ürünü iyileştirmek için kullanılabilir. Bu ürünü kullanımınız Google'ın Şartları, Yapay Zeka Kullanım Politikası ve Gizlilik Politikası'na tabidir.

Genel Bakış

chat yöntemi hem tek dönüşlü geçici veri sorularına hem de çok dönüşlü etkileşimli oturumlara olanak tanır:

  1. Tek dönüşlü sorgular: Anında analitik sorular sorun (ör. "Geçen hafta en çok trafik aldığımız kanallar hangileriydi?") ve yapılandırılmış veri tablolarıyla birlikte doğal dil yanıtları alın.
  2. Çok adımlı görüşmeler: Görüşme geçmişini korumak ve teşhis amaçlı ek sorular sormak için sessionId iletin (ör. "Bu dönemde organik trafik neden düştü?").
  3. Yapılandırılmış veri yanıtları: Yanıtlarda metin anlatımlara ek olarak sütun başlıkları ve satırları içeren yapılandırılmış table blokları da yer alır.
  4. Sohbet kotası izleme: returnPropertyQuota değerini true olarak ayarlayarak günlük ve saatlik kalan sohbet jetonu kotalarını inceleyin.

Kimlik doğrulama

chat yöntemine yapılan çağrılar için aşağıdaki kapsamda OAuth 2.0 yetkilendirmesi gerekir:

Başlamadan önce

  1. gcloud CLI'yı yükleyin ve ilk kullanıma hazırlayın.

  2. Application Default Credentials (Uygulama Varsayılan Kimlik Bilgileri) oluşturmak ve hesabınıza gerekli kapsamları vermek için aşağıdakileri çalıştırın:

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

  3. Google Analytics kullanıcı arayüzünde, kullanıcı hesabınıza Google Analytics mülküne erişim izni verin.

  4. Aşağıdakileri girerek ortam değişkenlerinizi yapılandırın. PROJECT_ID yerine projenizin kimliğini, PROPERTY_ID yerine ise Google Analytics mülkünüzün kimliğini yazın. 

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

1. örnek: Kota takibi içeren tek dönüşlü sorgu

Yeni bir görüşme başlatmak için ChatRequest oluşturun.userQuery Kalan jeton bakiyenizi incelemek için returnPropertyQuota'ı true olarak ayarlayın.

Senaryo: Cihaza Göre Gelir ve Dönüşüm Oranı

Son 30 gün içinde cihazlar genelinde gelir ve oturum dönüşüm oranını karşılaştırmak istiyorsunuz.

HTTP İsteği

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 Yanıtı

Yanıtta şunlar yer alıyor:

  • Takip eden dönüşlerde kullanabileceğiniz yeni atanmış bir sessionId.
  • Hem doğal dil özeti (text) hem de yapılandırılmış tablo (table) içeren blocks listesi. Metin blokları, kalın metin, başlıklar ve bağlantılar gibi Markdown biçimlendirmesi içerebilir.
  • Tesisin propertyQuota bilgileri.
{
  "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. örnek: Çok adımlı etkileşimli teşhis

Bağlamı koruyarak ek soru sormak için isteğinize önceki yanıtta döndürülen sessionId değerini ekleyin.

Senaryo: Önceki dönemle karşılaştırma

Önceki cihaz karşılaştırmasıyla ilgili olarak danışmana sonuçları önceki dönemle karşılaştırmasını söylüyorsunuz.

HTTP İsteği

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 Yanıtı

Ask Advisor, sonuçları önceki dönemle ilişkilendirmek için oturum belleğini kullanır.

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

Yanıt Yapısı ve Veri Blokları

ChatResponse nesnesi, blocks dizisinde yapılandırılmış bileşenler döndürür:

Blok Türü Alan Açıklama
Narrative Text blocks[].text Kullanıcılar tarafından okunabilir açıklama ve üst düzey analiz çıkarımları.
Yapılandırılmış Tablo blocks[].table headers (adlar ve veri türleri) ve rows (hücre değerleri) içeren tablo şeklinde veriler dökümü.

Tablo Başlığı Veri Türleri

blocks[].table.headers sütunları, anlamsal veri türünü açıklar:

  • string: Kategorik metin değerleri (ör. "desktop", "/shop/apparel").
  • float: Sayısal kayan nokta sayıları.

Sohbet kotası yönetimi

Ask Advisor istekleri, sorgu karmaşıklığına göre sohbet jetonları kullanır. Geçerli kota durumu, returnPropertyQuota true olduğunda propertyQuota içinde döndürülür:

  • tokensPerDay: Günlük jeton sınırı ve kalan bakiye.
  • tokensPerHour: Saatlik kayan pencere sıklık sınırlaması ve kalan bakiye.

Önerilen entegrasyon uygulamaları

properties.chat yöntemi, ekipler ve araçlar arasında çeşitli entegrasyon mimarilerinin kilidini açar:

Kurumsal Sohbet ve İşbirliği Botları

Ekip sohbeti çalışma alanınızı doğrudan Google Analytics'e bağlayın.

  • İş parçacıklı oturumlar: Ekip üyelerinin ortaklaşa takip soruları sormasına olanak tanımak için sessionId, sohbet iş parçacığı kimliğine göre saklanır.
  • Zengin Kart Oluşturma: table yanıt bloklarını etkileşimli kart widget'larına dönüştürün.

Özerk Yapay Zeka Ajanları ve Model Context Protocol (MCP) Araçları

LLM düzenleyicileri (ör. Gemini, LangChain veya Claude) bir GA analiz aracıyla donatın:

  • LLM'yi karmaşık runReport sorgular oluşturmaya zorlamak yerine, LLM ajanı chat yöntemini doğal dil niyetiyle çağırabilir.
  • Ajan, çok kanallı pazarlama önerileri oluşturmak için yüksek doğrulukta özetler ve yapılandırılmış tablolar alır.

Otomatik Yönetici Özetleri ve Uyarılar

Anormallikleri proaktif olarak inceleyen planlanmış hizmetler oluşturun:

  • Günlük bir cron işi şu sorguyu gönderir: "Dünkü temel performans metriklerini özetle ve dönüşümlerdeki anormal düşüşleri belirle."
  • Bir anormallik bulunursa komut dosyası, temel nedenleri teşhis etmek için otomatik olarak bir takip sorgusu tetikler ve dahili kontrol panellerine veya CRM sistemlerine bir özet gönderir.