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

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

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

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

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

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

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

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

בכל השיטות של Data API v1 יש צורך ב- מזהה הנכס ב-Google Analytics יצוין בתוך נתיב בקשה של כתובת URL, properties/GA_PROPERTY_ID, למשל:

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

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

אם אתם משתמשים באחת מספריות הלקוח של Data API, אין צורך לשנות באופן ידני את נתיב כתובת ה-URL של הבקשה. רוב לקוחות ה-API מספקים את הפרמטר property שמצפה מחרוזת בפורמט properties/GA_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
  }
}

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

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

אחרי שמשימת הדיווח נוצרה באמצעות reportTasks.create נוצרת אחת, reportTasks.query ומציינים את השם של משימת הדיווח (למשל 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"
  }
}