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

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

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

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

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

ב-Google Analytics Data API v1, יצירת משימות של דוחות מתבצעת באופן אסינכרוני. קודם כול, צריך לשלוח בקשה ל-method‏ 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. במדריך למתחילים יש דוגמאות לשימוש בספריות הלקוח.

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

כדי ליצור משימת דוח, צריך להפעיל את ה-method‏ 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.

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

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

השלבים הבאים