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

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

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

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

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

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