שימוש בסוכן הייעוץ ב-Analytics כדי לבצע שאילתות ולנתח את הנתונים

השיטה chat של Data API מספקת גישה פרוגרמטית לסוכן הייעוץ ב-Analytics – עוזר אנליטי מבוסס-AI שעוזר לכם לשאול שאלות, לנתח ולאבחן את הנתונים ב-Google Analytics באמצעות שפה טבעית.

התכונה 'יועץ Analytics' זמינה באופן אינטראקטיבי בממשק המשתמש של Google Analytics, אבל ה-API‏ chat מאפשר למפתחים, לסוכני AI אוטונומיים ולכלים פנימיים ליצור אינטראקציה עם 'יועץ Analytics' באופן פרוגרמטי באמצעות HTTP.

חשוב: המוצר הזה מבוסס על AI ויכול להיות שיוצג בו מידע לא מדויק. יכול להיות שנשתמש בשיחות שלכם בצ'אט כדי לשפר את המוצר, והשימוש שלכם בו כפוף לתנאים, למדיניות בנושא שימוש אסור ב-AI ולמדיניות הפרטיות של Google.

סקירה כללית

השיטה chat מאפשרת לשאול שאלות אד-הוק על נתונים, וגם לנהל שיחות רב-שלביות:

  1. שאילתות חד-שלביות: אפשר לשאול שאלות אנליטיות מיידיות (לדוגמה, 'מה היו ערוצי התנועה המובילים שלנו בשבוע שעבר?') ולקבל תשובות בשפה טבעית יחד עם טבלאות של נתונים מובְנים.
  2. שיחות רב-שלביות: אפשר להעביר sessionId כדי לשמור את היסטוריית השיחות ולשאול שאלות המשך לצורך אבחון (למשל, "למה התנועה האורגנית ירדה בתקופה הזו?").
  3. תשובות עם נתונים מובְנים: בנוסף לתיאורים מילוליים, התשובות מכילות בלוקים של נתונים מובְנים table עם כותרות של עמודות ושורות.
  4. מעקב אחר מכסת השימוש ב-Chat: כדי לבדוק את מכסת השימוש היומית והשעתית שנותרה ב-Chat, מגדירים את returnPropertyQuota ל-true.

אימות

קריאות לשיטה chat דורשות הרשאת OAuth 2.0 עם ההיקף הבא:

לפני שמתחילים

  1. מתקינים ומפעילים את gcloud CLI.

  2. כדי ליצור Application Default Credentials ולתת לחשבון את ההיקפים הנדרשים, מריצים את הפקודה הבאה:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.chatbot.read"

  3. בממשק המשתמש של Google Analytics, מעניקים לחשבון המשתמש גישה לנכס ב-Google Analytics.

  4. מגדירים את משתני הסביבה על ידי הזנת הערכים הבאים. מחליפים את PROJECT_ID במזהה הפרויקט ב- ואת PROPERTY_ID במזהה הנכס ב-Google Analytics. 

      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

היועץ של Analytics משתמש בזיכרון הסשן כדי ליצור קורלציה בין התוצאות לבין התקופה הקודמת.

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

הבקשות לסוכן הייעוץ של Analytics צורכות טוקנים של צ'אט על סמך מורכבות השאילתה. מצב המכסה הנוכחי מוחזר ב-propertyQuota כש-returnPropertyQuota הוא true:

  • ‫tokensPerDay: מכסת הטוקנים היומית והיתרה הנותרת.
  • ‫tokensPerHour: מגבלת קצב חלון נע לשעה והיתרה לתשלום.

הצעות לאפליקציות לשילוב

השיטה properties.chat מאפשרת להשתמש בכמה ארכיטקטורות שילוב בין צוותים וכלים:

בוטים לצ'אט ולשיתוף פעולה בארגונים

אפשר לקשר את סביבת העבודה של הצ'אט הצוותי ישירות ל-Google Analytics.

  • סשנים עם שרשורים: אחסון של sessionId לפי מזהה שרשור הצ'אט, כדי לאפשר לחברי הצוות לשאול שאלות המשך בשיתוף פעולה.
  • עיבוד של צ'אטים אינטראקטיביים: עיצוב של בלוקי תגובה table לווידג'טים של כרטיסים אינטראקטיביים.

סוכני AI אוטונומיים וכלים של Model Context Protocol‏ (MCP)

מציידים כלים לתזמור LLM (כמו Gemini,‏ LangChain או Claude) בכלי ניתוח של GA:

  • במקום להכריח מודל שפה גדול (LLM) ליצור שאילתות runReport מורכבות, סוכן ה-LLM יכול להפעיל את השיטה chat באמצעות כוונה בשפה טבעית.
  • הסוכן מקבל סיכומים עם רמת דיוק גבוהה וטבלאות מובנות כדי ליצור המלצות שיווקיות לכמה ערוצים.

תקצירים אוטומטיים למנהלים והתראות

יצירת שירותים מתוזמנים שבודקים אנומליות באופן יזום:

  • משימת cron יומית שולחת שאילתה: "סכם את מדדי הביצועים העיקריים מאתמול וזהה ירידה חריגה בהמרות".
  • אם נמצאה אנומליה, הסקריפט מפעיל באופן אוטומטי שאילתת מעקב כדי לאבחן את שורש הבעיה, ומפרסם סיכום בלוחות בקרה פנימיים או במערכות CRM.