דיווח על יסודות המשימות

בעזרת משימות של דוחות, תוכלו להתחיל בקשה אסינכרונית ממושכת כדי ליצור דוח בהתאמה אישית של נתוני האירועים ב-Google Analytics.

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

דוח בהתאמה אישית יהיה זמין למשך 72 שעות אחרי שהוא יהיה מוכן. אחרי התקופה הזו, משאב המשימה של הדוח והתוכן שלה יימחקו באופן אוטומטי.

יצירת משימת דיווח

ב-Google Analytics Data API v1 נעשה שימוש בגישה אסינכרונית כדי ליצור משימות דיווח. קודם כול, צריך בקשה ל-method reportTasks.create כדי ליצור משימת דוח. לאחר מכן משתמשים בשיטה reportTasks.query כדי לאחזר את הדוח בהתאמה אישית שנוצר.

בנוסף, אפשר להשתמש ב-reportTasks.get כדי לאחזר מטא-נתונים של הגדרות של משימת דוח ספציפית, וגם ב-reportTasks.list כדי להציג רשימה של כל משימות הדיווח בנכס.

צריך לבחור ישות לדיווח

בכל השיטות של Data API v1 צריך לציין את מזהה נכס Google Analytics 4 בתוך נתיב הבקשה לכתובת URL, בפורמט properties/GA4_PROPERTY_ID. לדוגמה:

  POST  https://analyticsdata.googleapis.com/v1alpha/properties/GA4_PROPERTY_ID/reportTasks

הדוח נוצר על סמך נתוני האירוע ב-Google Analytics שנאספים בנכס Google Analytics 4 שצוין.

אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות את נתיב כתובת ה-URL של הבקשה באופן ידני. רוב לקוחות ה-API מספקים פרמטר property שמצפה למחרוזת בפורמט properties/GA4_PROPERTY_ID. במדריך למתחילים מוצגות דוגמאות לשימוש בספריות הלקוח.

שליחת בקשה ליצירת משימת דיווח

כדי ליצור משימת דיווח, צריך לקרוא לשיטה reportTasks.create באמצעות האובייקט ReportTask שבבקשה. הפרמטרים הבאים נדרשים:

בקשה לדוגמה ליצירת משימת דוח:

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks
{
  "reportDefinition": {
    "dateRanges": [{ "startDate": "2024-05-01"", "endDate": "2024-05-15" }],
    "dimensions": [{ "name": "country" }],
    "metrics": [{ "name": "activeUsers" }]
  }
}

תשובה משיטת reportTasks.create מכילה את השם של משימת הדוח בשדה name (כמו properties/1234567/reportTasks/123), שבו ניתן להשתמש בשאילתות הבאות כדי לקבל את הסטטוס של משימת דוח ולאחזר את הדוח שמתקבל.

תגובת HTTP

{
  "response": {
    "@type": "type.googleapis.com/google.analytics.data.v1alpha.ReportTask",
    "name": "properties/1234567/reportTasks/123",
    "reportDefinition": {
      "dimensions": [
        {
          "name": "country"
        }
      ],
      "metrics": [
        {
          "name": "activeUsers"
        }
      ],
      "dateRanges": [
        {
          "startDate": "2024-05-01",
          "endDate": "2024-05-15"
        }
      ]
    },
    "reportMetadata": {
      "state": "CREATING",
      "beginCreatingTime": "2024-05-16T00:00:01.133612336Z"
    }
  }
}

קבלת מצב המוּכנוּת למשימות

יצירת דוח עשויה להימשך כמה דקות אחרי השיחה ל-reportTasks.create. אפשר לבדוק את מצב המוּכנוּת של משימת דיווח על ידי קריאה לשיטה reportTasks.get.

משתמשים בשם של משימת הדיווח (למשל properties/1234567/reportTasks/123) שקיבלתם מהתגובה של reportTasks.create כדי לציין את משימת הדיווח.

דוגמה:

בקשת HTTP

GET https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123

סטטוס המוּכנוּת של משימת דיווח מוחזר בשדה state של התשובה. אחרי שיצירת הדוח תושלם, המצב של משימת דוח ישתנה מ-CREATING ל-ACTIVE.

השדה reportMetadata מכיל את המידע הכללי על הדוח שנוצר, כמו מספר השורות וכמות אסימוני המכסה שחויבתם.

תגובת HTTP

{
  "reportDefinition": {
    "dimensions": [
      {
        "name": "country"
      }
    ],
    "metrics": [
      {
        "name": "activeUsers"
      }
    ],
    "dateRanges": [
      {
        "startDate": "2024-05-01",
        "endDate": "2024-05-15"
      }
    ]
  },
  "reportMetadata": {
    "state": "ACTIVE",
    "beginCreatingTime": "2024-05-16T00:00:01.133612336Z",
    "creationQuotaTokensCharged": 6,
    "taskRowCount": 167,
    "errorMessage": "",
    "totalRowCount": 167
  }
}

אפשר לבדוק את המצב של כל משימות הדיווח באמצעות קריאה ל-method reportTasks.list.

אחזור הדוח שנוצר

אחרי שיוצרים את משימת הדיווח באמצעות השיטה reportTasks.create, קוראים ל-method reportTasks.query ומציינים את השם של Report Task (למשל properties/1234567/reportTasks/123).

בקשת HTTP

POST https://analyticsdata.googleapis.com/v1alpha/properties/1234567/reportTasks/123:query

אם משימת הדיווח מוכנה, תוחזר תשובה עם הדוח שנוצר:

תגובת HTTP

{
  "dimensionHeaders": [
    {
      "name": "country"
    }
  ],
  "metricHeaders": [
    {
      "name": "activeUsers",
      "type": "TYPE_INTEGER"
    }
  ],
  "rows": [

...

  ],
  "rowCount": 167,
  "metadata": {
    "currencyCode": "USD",
    "timeZone": "America/Los_Angeles"
  }
}