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

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

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

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

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

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