استخدام "مستشار إحصاءات Google" لطلب البحث عن بياناتك وتحليلها

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

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

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

نظرة عامة

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

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

المصادقة

تتطلّب الطلبات التي يتم إجراؤها على الطريقة chat تفويض OAuth 2.0 بالنطاق التالي:

قبل البدء

  1. ثبِّت gcloud CLI وافتحه.

  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

تستخدِم "ميزة المستشار في إحصاءات Google" ذاكرة الجلسة لربط النتائج بالفترة السابقة.

{
  "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

تستهلك طلبات "مستشار إحصاءات Google" رموز المحادثة المميزة استنادًا إلى درجة تعقيد طلب البحث. يتم عرض حالة الحصة الحالية في propertyQuota عندما تكون قيمة returnPropertyQuota هي true:

  • tokensPerDay: الحدّ الأقصى اليومي للرموز المميزة والرصيد المتبقي
  • ‫tokensPerHour: الحدّ الأقصى لمعدّل الاستخدام في فترة زمنية متغيرة مدتها ساعة واحدة والرصيد المتبقي

تطبيقات الدمج المقترَحة

تتيح طريقة properties.chat العديد من بُنى التكامل بين الفِرق والأدوات:

روبوتات الدردشة والتعاون في المؤسسات

ربط مساحة عمل دردشة الفريق مباشرةً بخدمة "إحصاءات Google"

  • الجلسات المتسلسلة: يتم تخزين sessionId مقابل معرّف سلسلة المحادثات للسماح لأعضاء الفريق بطرح أسئلة متابعة بشكل تعاوني.
  • عرض البطاقات التفاعلية: تنسيق table لتقسيم الردود إلى أدوات بطاقات تفاعلية

أدوات "بروتوكول سياق النموذج" (MCP) ووكلاء الذكاء الاصطناعي المستقلون

تزويد أدوات تنسيق النماذج اللغوية الكبيرة (مثل Gemini أو LangChain أو Claude) بأداة تحليل من "إحصاءات Google":

  • بدلاً من إجبار نموذج لغوي كبير على إنشاء طلبات بحث معقّدة runReport ، يمكن لوكيل النموذج اللغوي الكبير استدعاء طريقة chat باستخدام اللغة الطبيعية.
  • يتلقّى الوكيل ملخّصات عالية الدقة وجداول منظَّمة لتجميعها في اقتراحات تسويقية متعدّدة القنوات.

الإشعارات والملخّصات التنفيذية المبرمَجة

إنشاء خدمات مجدوَلة تبحث بشكل استباقي عن القيم الشاذة:

  • يتم تنفيذ مهمة cron يومية لتنفيذ طلب البحث التالي: "لخِّص مقاييس الأداء الرئيسية ليوم أمس وحدِّد أي انخفاض غير طبيعي في عدد الإحالات الناجحة".
  • في حال رصد أي شذوذ، ينفّذ النص البرمجي تلقائيًا طلب بحث للمتابعة بهدف تشخيص الأسباب الجذرية، وينشر ملخّصًا في لوحات البيانات الداخلية أو أنظمة إدارة علاقات العملاء.