استفاده از Analytics Advisor برای پرس‌وجو و تحلیل داده‌های شما

روش chat رابط برنامه‌نویسی کاربردی داده (Data API) دسترسی برنامه‌نویسی‌شده به Analytics Advisor را فراهم می‌کند - یک دستیار تحلیلی مبتنی بر هوش مصنوعی که به شما کمک می‌کند داده‌های گوگل آنالیتیکس خود را با استفاده از زبان طبیعی جستجو، تجزیه و تحلیل و تشخیص دهید.

در حالی که Analytics Advisor به صورت تعاملی در رابط کاربری Google Analytics در دسترس است، API chat به توسعه‌دهندگان، عوامل هوش مصنوعی مستقل و ابزارهای داخلی اجازه می‌دهد تا از طریق HTTP به صورت برنامه‌نویسی شده با Analytics Advisor تعامل داشته باشند.

مهم: این محصول از هوش مصنوعی استفاده می‌کند و ممکن است اطلاعات نادرستی را نمایش دهد. فعالیت چت شما ممکن است برای بهبود محصول استفاده شود و استفاده شما تابع شرایط ، سیاست استفاده از هوش مصنوعی و سیاست حفظ حریم خصوصی گوگل است.

نمای کلی

روش chat ، هم امکان پرسش‌های داده‌ای موردی تک نوبتی و هم جلسات مکالمه‌ای چند نوبتی را فراهم می‌کند:

  1. پرسش‌های تک‌مرحله‌ای: پرسش‌های تحلیلی فوری بپرسید (مانند «کانال‌های برتر ترافیک ما در هفته گذشته کدام بودند؟») و پاسخ‌های زبان طبیعی را به همراه جداول داده‌های ساختاریافته دریافت کنید.
  2. مکالمات چند نوبتی: برای حفظ سابقه مکالمات و پرسیدن سوالات تشخیصی تکمیلی (مانند «چرا ترافیک ارگانیک در آن دوره کاهش یافته است؟»)، یک sessionId ارسال کنید.
  3. پاسخ‌های داده ساختاریافته: علاوه بر روایت‌های متنی، پاسخ‌ها حاوی بلوک‌های table ساختاریافته با سرستون‌ها و ردیف‌ها هستند.
  4. نظارت بر سهمیه چت: با تنظیم returnPropertyQuota روی true ، سهمیه‌های باقیمانده توکن چت در هر روز و در هر ساعت را بررسی کنید.

احراز هویت

فراخوانی‌های متد chat نیاز به مجوز OAuth 2.0 با دامنه زیر دارند:

قبل از اینکه شروع کنی

  1. رابط خط فرمان gcloud را نصب و راه‌اندازی کنید .

  2. برای تولید اعتبارنامه‌های پیش‌فرض برنامه و اختصاص دادن حوزه‌های لازم به حساب کاربری خود، دستور زیر را اجرا کنید:

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

  3. در رابط کاربری گوگل آنالیتیکس ، به حساب کاربری خود اجازه دسترسی به یک ویژگی گوگل آنالیتیکس را بدهید.

  4. متغیرهای محیطی خود را با وارد کردن موارد زیر پیکربندی کنید. PROJECT_ID را با شناسه پروژه خود جایگزین کنید. پروژه و PROPERTY_ID با شناسه‌ی ویژگی گوگل آنالیتیکس شما.

      export PROJECT_ID=PROJECT_ID
  export PROPERTY_ID=PROPERTY_ID

مثال ۱: پرس‌وجوی تک نوبتی با ردیابی سهمیه

برای شروع یک مکالمه جدید، یک 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 که به تازگی اختصاص داده شده و می‌توانید برای نوبت‌های بعدی از آن استفاده کنید.
  • فهرستی از blocks که شامل خلاصه‌ای به زبان طبیعی ( text ) و جدولی ساختاریافته ( table ) است. بلوک‌های متنی می‌توانند شامل قالب‌بندی Markdown مانند متن پررنگ، عنوان‌ها و پیوندها باشند.
  • جزئیات 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
    }
  }
}

مثال ۲: تشخیص مکالمه‌ای چند نوبتی

برای پرسیدن یک سوال تکمیلی ضمن حفظ متن، 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 برمی‌گرداند:

نوع بلوک میدان توضیحات
متن روایی blocks[].text توضیحات قابل فهم برای انسان و نکات تحلیلی سطح بالا.
جدول ساختاریافته blocks[].table تجزیه داده‌های جدولی شامل headers (نام‌ها و انواع داده‌ها) و rows (مقادیر سلول‌ها).

انواع داده‌های سربرگ جدول

ستون‌های موجود در blocks[].table.headers نوع داده معنایی را توصیف می‌کنند:

  • string : مقادیر متنی دسته‌بندی‌شده (مثلاً "desktop" ، "/shop/apparel" ).
  • float : اعداد اعشاری عددی.

مدیریت سهمیه چت

درخواست‌های Analytics Advisor بر اساس پیچیدگی پرس‌وجو، توکن‌های چت را مصرف می‌کنند. وضعیت سهمیه فعلی در propertyQuota برگردانده می‌شود، زمانی که returnPropertyQuota true باشد:

  • tokensPerDay : محدودیت توکن روزانه و موجودی باقی‌مانده.
  • tokensPerHour : محدودیت نرخ پنجره کشویی ساعتی و موجودی باقی مانده.

برنامه‌های پیشنهادی برای ادغام

متد properties.chat چندین معماری یکپارچه‌سازی را در بین تیم‌ها و ابزارها ارائه می‌دهد:

ربات‌های چت و همکاری سازمانی

فضای کاری چت تیمی خود را مستقیماً به گوگل آنالیتیکس متصل کنید.

  • جلسات موضوعی: sessionId در مقابل شناسه موضوع چت ذخیره کنید تا اعضای تیم بتوانند سوالات تکمیلی را به صورت مشترک بپرسند.
  • رندرینگ غنی کارت: قالب‌بندی بلوک‌های پاسخ table به ویجت‌های کارت تعاملی.

ابزارهای پروتکل زمینه مدل (MCP) و عامل‌های هوش مصنوعی خودمختار

هماهنگ‌کننده‌های LLM (مانند Gemini، LangChain یا Claude) را به یک ابزار تحلیلی GA مجهز کنید:

  • به جای اینکه یک LLM را مجبور به تولید کوئری‌های پیچیده runReport کند، عامل LLM می‌تواند متد chat را با هدف زبان طبیعی فراخوانی کند.
  • نماینده خلاصه‌های کاملاً واقعی و جداول ساختاریافته‌ای را دریافت می‌کند تا آنها را در قالب توصیه‌های بازاریابی چندکاناله ترکیب کند.

جلسات توجیهی و هشدار خودکار مدیران

سرویس‌های زمان‌بندی‌شده‌ای ایجاد کنید که به‌طور پیشگیرانه ناهنجاری‌ها را بررسی کنند:

  • یک درخواست روزانه cron job: «معیارهای کلیدی عملکرد دیروز را خلاصه کنید و هرگونه افت غیرعادی در تبدیل‌ها را شناسایی کنید.»
  • اگر ناهنجاری پیدا شود، اسکریپت به طور خودکار یک پرس و جوی پیگیری را برای تشخیص علل ریشه‌ای آغاز می‌کند و خلاصه‌ای از آن را در داشبوردهای داخلی یا سیستم‌های CRM ارسال می‌کند.