توفّر طريقة chat في Data API إمكانية الوصول آليًا إلى Ask Advisor في "إحصاءات Google"، وهو مساعد تحليلي مستند إلى الذكاء الاصطناعي يساعدك في طلب بياناتك في "إحصاءات Google" وتحليلها وتشخيصها باستخدام اللغة الطبيعية.
في حين أنّ ميزة "Ask Advisor" متاحة بشكل تفاعلي ضِمن واجهة مستخدم "إحصاءات Google"، تتيح واجهة برمجة التطبيقات chat للمطوّرين ووكلاء الذكاء الاصطناعي المستقلين والأدوات الداخلية التفاعل مع ميزة "Ask Advisor" آليًا عبر HTTP.
ملاحظة مهمة: يستخدم هذا المنتج الذكاء الاصطناعي وقد يعرض معلومات غير دقيقة. قد يتم استخدام نشاط المحادثة لديك لتحسين المنتج، ويخضع استخدامك له لبنود الخدمة وسياسة استخدام الذكاء الاصطناعي وسياسة الخصوصية المتّبعة في Google.
نظرة عامة
تتيح طريقة chat طرح أسئلة مخصّصة حول البيانات في جلسة واحدة، بالإضافة إلى جلسات حوارية متعدّدة:
- طلبات البحث ذات الدورة الواحدة: يمكنك طرح أسئلة تحليلية مباشرة (مثل "ما هي أهم قنواتنا لجذب الزيارات في الأسبوع الماضي؟") وتلقّي إجابات باللغة الطبيعية بالإضافة إلى جداول بيانات منظَّمة.
- المحادثات المتعددة الأدوار: أضِف
sessionIdللاحتفاظ بسجلّ المحادثات وطرح أسئلة متابعة تشخيصية (مثل "لماذا انخفضت الزيارات الواردة من نتائج البحث المجانية في تلك الفترة؟"). - الردود التي تتضمّن بيانات منظَّمة: بالإضافة إلى السرد النصي، تتضمّن الردود
tableمنظَّمة تحتوي على رؤوس للأعمدة وصفوف. - مراقبة حصة Chat: يمكنك الاطّلاع على حصص رموز Chat المتبقية لكل يوم ولكل ساعة من خلال ضبط
returnPropertyQuotaعلىtrue.
المصادقة
تتطلّب عمليات الاستدعاء إلى طريقة chat
تفويض OAuth 2.0 بالنطاق التالي:
قبل البدء
لإنشاء بيانات اعتماد تلقائية للتطبيق ومنح حسابك النطاقات اللازمة، نفِّذ ما يلي:
gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"في واجهة مستخدم "إحصاءات Google"، امنح حساب المستخدم إذن الوصول إلى موقع على "إحصاءات Google".
اضبط متغيّرات البيئة من خلال إدخال ما يلي. استبدِل
PROJECT_IDبرقم تعريف مشروعك وPROPERTY_IDبرقم تعريف موقعك على "إحصاءات Google".export PROJECT_ID=
PROJECT_IDexport PROPERTY_ID=PROPERTY_ID
المثال 1: طلب بحث واحد مع تتبُّع الحصة
لبدء محادثة جديدة، أنشئ 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
}
}
}
المثال 2: التشخيص الحواري المتعدّد الجولات
لطرح سؤال متابعة مع الحفاظ على السياق، أدرِج 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
يستخدم Ask Advisor ذاكرة الجلسة لربط النتائج بالفترة السابقة.
{
"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: أرقام نقطة عائمة عددية
إدارة حصة Chat
تستهلك طلبات Ask Advisor رموزًا مميّزة للمحادثة استنادًا إلى درجة تعقيد الطلب.
يتم عرض حالة الحصة الحالية في
propertyQuota
عندما تكون قيمة returnPropertyQuota
هي true:
tokensPerDay: الحدّ اليومي للرموز المميزة والرصيد المتبقي-
tokensPerHour: الحدّ الأقصى لمعدّل النوافذ المنزلقة كل ساعة والرصيد المتبقي
تطبيقات الدمج المقترَحة
تتيح طريقة properties.chat
العديد من بنى الدمج بين الفِرق والأدوات:
روبوتات الدردشة والتعاون في المؤسسات
ربط مساحة عمل دردشة الفريق مباشرةً بخدمة "إحصاءات Google"
- الجلسات المتسلسلة: يتم تخزين
sessionIdمقابل رقم تعريف سلسلة المحادثات للسماح لأعضاء الفريق بطرح أسئلة متابعة بشكل تعاوني. - عرض البطاقات التفاعلية: يتم تنسيق
tableكتل الردود على شكل أدوات بطاقات تفاعلية.
أدوات "بروتوكول سياق النموذج" (MCP) ووكلاء الذكاء الاصطناعي المستقلون
تزويد أدوات تنسيق النماذج اللغوية الكبيرة (مثل Gemini أو LangChain أو Claude) بأداة تحليلية من "إحصاءات Google":
- بدلاً من إجبار نموذج لغوي كبير على إنشاء طلبات بحث معقّدة
runReport، يمكن لوكيل النموذج اللغوي الكبير استدعاء طريقةchatباستخدام اللغة الطبيعية. - يتلقّى الوكيل ملخّصات عالية الدقة وجداول منظَّمة ليتم تجميعها في اقتراحات تسويقية متعددة القنوات.
الإشعارات والملخّصات التنفيذية المبرمَجة
إنشاء خدمات مجدوَلة تبحث بشكل استباقي عن القيم الشاذة:
- يُرسِل برنامج cron مهمة cron يومية للاستعلام عن ما يلي: "لخِّص مقاييس الأداء الرئيسية ليوم أمس وحدِّد أي انخفاض غير طبيعي في الإحالات الناجحة".
- في حال رصد أي شذوذ، ينفّذ البرنامج النصي تلقائيًا طلب بحث للمتابعة بهدف تشخيص الأسباب الجذرية، وينشر ملخّصًا في لوحات البيانات الداخلية أو أنظمة إدارة علاقات العملاء (CRM).