روش chat
Data API
دسترسی برنامهای به
Ask Advisor در Google Analytics را فراهم میکند
— دستیار تحلیلی با بهرهگیری از هوش مصنوعی که به شما کمک میکند
دادههای Google Analytics خود را بااستفاده از زبان طبیعی پُرسمان، تحلیل، و عیبیابی کنید.
درحالیکه «از مشاور بپرسید» بهصورت تعاملی در میانای کاربر Google Analytics دردسترس است، chat API
به توسعهدهندگان، عاملهای هوش مصنوعی خودکار، و ابزارهای داخلی اجازه میدهد ازطریق HTTP با
«از مشاور بپرسید» بهصورت برنامهریزیشده تعامل کنند.
مهم: این محصول از هوش مصنوعی استفاده میکند و ممکن است اطلاعات نادرست نشان دهد. ممکن است از فعالیت گپ شما برای بهبود دادن محصول استفاده شود و استفاده شما تابع شرایط، خطمشی استفاده از هوش مصنوعی، و خطمشی رازداری Google است.
نمای کلی
روش chat هم سؤالات دادهای موردی تکنوبتی و هم جلسات مکالمهای چندنوبتی را فعال میکند:
- پُرسمانهای تکنوبتی: سؤالات تحلیلی فوری بپرسید (مثلاً «کانالهای ترافیک برتر ما در هفته گذشته چه بود؟») و پاسخهایی به زبان طبیعی همراه با جدولهای داده ساختاریافته دریافت کنید.
- مکالمههای چندنوبتی:
sessionIdرا ارسال کنید تا سابقه مکالمه حفظ شود و سؤالات تعقیبی تشخیصی بپرسید (مثلاً «چرا ترافیک طبیعی در آن دوره کاهش یافت؟»). - پاسخهای دادههای ساختاریافته: علاوهبر روایتهای نوشتاری، پاسخها
حاوی بلوکهای ساختاریافته
tableبا سرصفحههای ستون و ردیف هستند. - پایش سهمیه گپ: با تنظیم کردن
returnPropertyQuotaرویtrue، سهمیه باقیمانده گپ روزانه و ساعتی را بررسی کنید.
اصالتسنجی
تماس با روش chat
به مجوز OAuth 2.0 با حوزه زیر نیاز دارد:
قبلاز شروع
gcloud CLI را نصب و مقداردهی اولیه کنید.
برای تولید اعتبارنامههای پیشفرض برنامه و دادن دامنههای لازم به حسابتان، دستور زیر را اجرا کنید:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"در رابط کاربری Google Analytics، به حساب کاربریتان دسترسی به دارایی Google Analytics اعطا کنید.
متغیرهای محیطیتان را با وارد کردن موارد زیر پیکربندی کنید.
PROJECT_IDرا با شناسه پروژه وPROPERTY_IDرا با شناسه دارایی Google Analytics خودتان جایگزین کنید.export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
مثال ۱: پُرسمان تکنوبتی با ردیابی سهمیه
برای شروع مکالمه جدید، ChatRequest بسازید
که حاوی userQuery شما باشد.
برای بررسی تراز باقیمانده رمز خود، returnPropertyQuota
را روی true تنظیم کنید.
سناریو: درآمد و نرخ تبدیل براساس دستگاه
میخواهید درآمد و نرخ تبدیلبهمشتری جلسه را در دستگاههای مختلف در ۳۰ روز گذشته مقایسه کنید.
درخواست اچتیتیپی
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
برگرداندهشده توسط پاسخ قبلی را در درخواستتان بگنجانید.
سناریو: مقایسه با دوره قبلی
در ادامه مقایسه دستگاه قبلی، از «مشاور» میخواهید نتایج را با دوره قبلی مقایسه کند.
درخواست اچتیتیپی
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: اعداد ممیز شناور عددی.
مدیریت سهمیه گپ
درخواستهای Ask Advisor براساس پیچیدگی پُرسمان، از نشانهای گپ استفاده میکنند.
وضعیت سهمیه فعلی در
propertyQuota
وقتی returnPropertyQuota
برگردانده میشود که true:
tokensPerDay: حد روزانه کد و مانده باقیمانده.tokensPerHour: حد نرخ پنجره لغزنده ساعتی و مانده باقیمانده.
برنامههای یکپارچهسازی پیشنهادی
روش properties.chat
چندین معماری ادغام را در تیمها و ابزارها باز میکند:
روباتهای گپ و مشارکت سازمانی
فضای کاری گپ گروهیتان را مستقیماً به Google Analytics متصل کنید.
- جلسههای رشتهای:
sessionIdرا دربرابر شناسه رشته گپ ذخیره کنید تا به اعضای تیم اجازه دهید بهصورت مشارکتی سؤالات پیگیری بپرسند. - پرداز کارت غنی: قالب
tableبلوکهای پاسخ را به ابزارکهای کارت تعاملی تبدیل میکند.
عاملهای هوش مصنوعی خودکار و ابزارهای «پروتکل زمینهای مدل» (MCP)
هماهنگکنندههای مدل زبانی بزرگ (مثل Gemini، LangChain، یا Claude) را با ابزار تحلیلی GA مجهز کنید:
- بهجای اینکه مدل زبانی بزرگ را مجبور به تولید پُرسمانهای پیچیده
runReportکنیم، عامل مدل زبانی بزرگ میتواند روشchatرا با قصد زبان طبیعی فراخوانی کند. - این عامل خلاصههایی با واقعیتسنجی بالا و جدولهای ساختاریافته دریافت میکند تا آنها را در توصیههای بازاریابی چندکاناله ترکیب کند.
خلاصه اجرایی و هشدار خودکار
سرویسهای زمانبندیشدهای ایجاد کنید که بهطور پیشگیرانه ناهنجاریها را بررسی میکنند:
- یک کار cron روزانه این پُرسمان را اجرا میکند: «سنجههای عملکرد کلیدی دیروز را خلاصه کن و هرگونه کاهش غیرعادی در تبدیلها را شناسایی کن.»
- اگر ناهنجاریای پیدا شود، دستورگان بهطور خودکار پُرسمان پیگیری را برای تشخیص علتهای ریشهای راهاندازی میکند و خلاصه گزیدهای را در داشبوردهای داخلی یا سیستمهای CRM پست میکند.
مراحل بعدی
- برای اجرای پُرسمانهای تکنوبتی و چندنوبتی بااستفاده از کتابخانه مشتری Python، دفترچه Ask Advisor Colab تعاملی را امتحان کنید.
properties.chatمرجع REST API را مرور کنید.- درباره سهمیهها و محدودیتهای «میانای برنامهسازی کاربردی داده» بیشتر بدانید.