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

באמצעות משימות דוחות, אפשר להתחיל בקשה אסינכררונית ממושכת כדי ליצור דוח מותאם אישית של נתוני האירועים ב-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. במדריך למתחילים מפורטות דוגמאות לשימוש בספריות הלקוח.

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

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

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

אחרי שיוצרים את משימה הדיווח באמצעות השיטה 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"
  }
}