שימוש בתכונה Ask Advisor ב-Google Analytics באופן פרוגרמטי כדי לשלוח שאילתות ולנתח את הנתונים

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

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

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

סקירה כללית

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

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

אימות

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

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

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

  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

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 Analytics.

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

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

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

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

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

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

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

השלבים הבאים