تتيح طريقة 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
الذي تم عرضه في الردّ السابق في طلبك.
السيناريو: المقارنة بالفترة السابقة
لمتابعة مقارنة الأجهزة السابقة، تطلب من Advisor مقارنة النتائج بالفترة السابقة.
طلب 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 يومية طلبات البحث التالية: "تلخيص مقاييس الأداء الرئيسية ليوم أمس وتحديد أي انخفاض غير طبيعي في الإحالات الناجحة".
- في حال العثور على قيمة شاذة، يشغّل النص البرمجي تلقائيًا طلب بحث متابعة لتشخيص الأسباب الأساسية وينشر ملخّصًا موجزًا في لوحات البيانات الداخلية أو أنظمة إدارة علاقات العملاء.
الخطوات التالية
- يمكنك تجربة ورقة ملاحظات Colab التفاعلية الخاصة بـ Ask Advisor لتشغيل طلبات البحث ذات الجولة الواحدة والمتعدّدة الجولات باستخدام مكتبة برامج Python.
- راجِع مرجع REST API في
properties.chat. - مزيد من المعلومات عن الحصص والحدود في Data API