استخدام ميزة "Ask Advisor" في "إحصاءات Google" بشكل آلي لطلب بياناتك وتحليلها

توفّر طريقة chat في Data API إمكانية الوصول آليًا إلى Ask Advisor في "إحصاءات Google"، وهو مساعد تحليلي مستند إلى الذكاء الاصطناعي يساعدك في طلب بياناتك في "إحصاءات Google" وتحليلها وتشخيصها باستخدام اللغة الطبيعية.

في حين أنّ ميزة "Ask Advisor" متاحة بشكل تفاعلي ضِمن واجهة مستخدم "إحصاءات Google"، تتيح واجهة برمجة التطبيقات chat للمطوّرين ووكلاء الذكاء الاصطناعي المستقلين والأدوات الداخلية التفاعل مع ميزة "Ask Advisor" آليًا عبر HTTP.

ملاحظة مهمة: يستخدم هذا المنتج الذكاء الاصطناعي وقد يعرض معلومات غير دقيقة. قد يتم استخدام نشاط المحادثة لديك لتحسين المنتج، ويخضع استخدامك له لبنود الخدمة وسياسة استخدام الذكاء الاصطناعي وسياسة الخصوصية المتّبعة في Google.

نظرة عامة

تتيح طريقة chat طرح أسئلة مخصّصة حول البيانات في جلسة واحدة، بالإضافة إلى جلسات حوارية متعدّدة:

  1. طلبات البحث ذات الدورة الواحدة: يمكنك طرح أسئلة تحليلية مباشرة (مثل "ما هي أهم قنواتنا لجذب الزيارات في الأسبوع الماضي؟") وتلقّي إجابات باللغة الطبيعية بالإضافة إلى جداول بيانات منظَّمة.
  2. المحادثات المتعددة الأدوار: أضِف sessionId للاحتفاظ بسجلّ المحادثات وطرح أسئلة متابعة تشخيصية (مثل "لماذا انخفضت الزيارات الواردة من نتائج البحث المجانية في تلك الفترة؟").
  3. الردود التي تتضمّن بيانات منظَّمة: بالإضافة إلى السرد النصي، تتضمّن الردود table منظَّمة تحتوي على رؤوس للأعمدة وصفوف.
  4. مراقبة حصة Chat: يمكنك الاطّلاع على حصص رموز Chat المتبقية لكل يوم ولكل ساعة من خلال ضبط 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. في واجهة مستخدم "إحصاءات Google"، امنح حساب المستخدم إذن الوصول إلى موقع على "إحصاءات Google".

  4. اضبط متغيّرات البيئة من خلال إدخال ما يلي. استبدِل PROJECT_ID برقم تعريف مشروعك وPROPERTY_ID برقم تعريف موقعك على "إحصاءات Google".

      export PROJECT_ID=PROJECT_ID
      export 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).