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

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

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

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

نظرة عامة

تتيح طريقة chat كلاً من أسئلة البيانات المخصّصة ذات الإجابة الواحدة وجلسات المحادثات المتعدّدة:

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

تستخدم ميزة 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: أرقام النقطة العائمة.

إدارة حصة المحادثة

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

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

اقتراحات لتطبيقات التكامل

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

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

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

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

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

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

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

الإحاطات التنفيذية والإشعارات الآلية

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

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

الخطوات التالية