استخدام ميزة "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 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 الذي تم عرضه في الردّ السابق في طلبك.

السيناريو: المقارنة بالفترة السابقة

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

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