מדריך למפתחים בנושא דוחות ללא דגימה

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

מבוא

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

בעזרת ה-API הזה אפשר:

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

אחזור נתונים מדוחות ללא דגימה

כשיוצרים דוח ללא דגימה, יכול להיות שיחלוף זמן מה עד שהדוח יהיה זמין להורדה. השדה status בדוח ללא דגימה מציין אם העיבוד של הדוח הושלם. אחרי שמסמנים את הסטטוס COMPLETED, אפשר להשתמש ב-downloadType ובשדה המתאים של פרטי ההורדה כדי לאחזר את הקובץ שמכיל את נתוני הדוח. למשל:

אם הערך של downloadType הוא GOOGLE_DRIVE, משתמשים בשדה driveDownloadDetails.
אם הערך של downloadType הוא GOOGLE_CLOUD_STORAGE, משתמשים בשדה cloudStorageDownloadDetails.

לא מומלץ להשתמש בתשאול רציף וקצב גבוה כדי לבדוק את הסטטוס של הדוחות, כי יש סיכוי גבוה שתמצה את המכסה היומית שלך תוך זמן קצר. דרוש עיכוב זמן בין הבקשות בעת בדיקת הסטטוס של דוחות ללא דגימה.

שימוש ב-Google Drive / Google Cloud Storage API

בהתאם ליעד שאליו הקבצים מועברים (Google Drive או Google Cloud Storage), תקבלו קישור מתאים לקובץ הזה. ניתן להשתמש ב-Drive API או ב-Cloud Storage API כדי להוריד את הקובץ באמצעות הקישור הזה. פרטים נוספים על אופן אחזור הקובץ זמינים במסמכי התיעוד של Google Drive API או Google Cloud Storage API.

לדוגמה, אם הדוח ללא דגימה שמור ב-Google Drive, אפשר לשלוח בקשת HTTP GET מורשית לכתובת ה-URL של המשאב של הקובץ ולכלול את פרמטר השאילתה alt=media.

GET /drive/v2/files/XXXXXX?alt=media
Host: www.googleapis.com
Content-length: 0
Authorization: Bearer ya29.AHESVbXTUv5mHMo3RYfmS1YJonjzzdTOFZwvyOAUVhrs

כאשר XXXXXX הוא הדוח ללא דגימה driveDownloadDetails.documentId

אימות

אם בכוונתך להשתמש בדוח ללא דגימה בשילוב עם Drive או ממשקי API של Cloud Storage להורדת קבצים, עליך לכלול את היקף ההרשאה המתאים של אותו API (בנוסף להיקף ההרשאות של ממשק ה-API של Analytics) בעת בקשת אסימון OAuth 2.0. כך אפשר להשתמש באותו אסימון אימות בשני ממשקי ה-API.

מחיקת דוחות שמבוססים על כל הנתונים

תוכל למחוק דוחות מתוזמנים או שהושלמו ללא דגימה, אך קריאה ל-delete במהלך התקופה הקצרה בזמן הפקת הדוח תוביל לשגיאה. מחיקת דוחות ללא דגימה מסירה את המשאב רק מתצוגת Google Analytics (פרופיל), הנתונים שיוצאו ב-Google Drive או ב-Google Cloud Storage יישארו.

הגבלות

המגבלות הבאות חלות על יצירת דוחות ללא דגימה:

ניתן לציין רק עד 4 מאפיינים.
חלק מסוגי נתוני הדיווח, כמו נתוני Google Ads, לא נתמכים.
אין תמיכה בשאילתות שנקבעות כיקרות מדי.
אם יצרתם יותר מדי דוחות ללא דגימה ואתם מגיעים למגבלה, תוכלו למחוק בבטחה את משאבי הדוח של הנתונים ללא דגימה ולהשאיר את נתוני הדוח שנוצרו ללא דגימה ב-Google Drive או ב-Google Cloud.

אם ייקבע שהבקשה שלכם יקרה מדי, פעולת היצירה תחזיר שגיאה עם הודעה מתאימה. במקרה כזה, תוכלו:

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

תרחישים לדוגמה

דוחות ללא דגימה וממשק ה-API הראשי לדיווח

אם אתם משתמשים ב-Core Reporting API כדי לאחזר נתוני דוח והוא מכיל נתונים שנדגמו, תוכלו ליצור דוח ללא דגימה לאותה השאילתה באופן הבא:

שולחים בקשה ל-Core Reporting API.
בתשובה, בודקים את המאפיין containsSampledData כדי לראות אם הנתונים נדגמים.
אם מאפיין זה מוגדר כ-True, תוכלו להשתמש בשדות 'שאילתה' ו'פרופיל' מאותה תגובה כדי ליצור בקשה לדוח ללא דגימה.

שדה שאילתה לדוגמה מתגובה של Core Reporting API:

"query": {
  "start-date": "2011-01-01",
  "end-date": "2011-01-31",
  "ids": "ga:1234",
  "dimensions": "ga:browser",
  "metrics": [
  "ga:visits"
  ],
  "filters": "ga:country==US",
  "start-index": 1,
  "max-results": 1000
}

שדה profileInfo לדוגמה מתגובה של Core Reporting API:

"profileInfo": {
  "profileId": "1234",
  "accountId": "12345",
  "webPropertyId": "UA-12345-1",
  "internalWebPropertyId": "11254",
  "profileName": "Name of the profile",
  "tableId": "ga:1234"
}

הדוגמה הבאה מראה איך ליצור דוח ללא דגימה מתגובה של Core Reporting API:

Java

// Make a Core Reporting API call.
GaData reportingApiData = v3.data().ga().get(...).execute();

// Check if the response is sampled.
if (reportingApiData.getContainsSampledData()) {

  // Use the “query” object to construct an unsampled report object.
  Query query = reportingApiData.getQuery();
  UnsampledReport report = new UnsampledReport()
      .setDimensions(query.getDimensions())
      .setMetrics(Joiner.on(',').join(query.getMetrics()))
      .setStartDate(startDate)
      .setEndDate(endDate)
      .setSegment(query.getSegment())
      .setFilters(query.getFilters())
      .setTitle(“My unsampled report”);

  // Use “profileInfo” to create an InsertRequest for creating an
  // unsampled report.
  ProfileInfo profileInfo = reportingApiData.getProfileInfo();
  Insert insertRequest = analytics.management().unsampledReports()
  .insert(profileInfo.getAccountId(),
          profileInfo.getWebPropertyId(),
          profileInfo.getProfileId(),
          report);
  UnsampledReport createdReport = insertRequest.execute();
}

חיבור נתונים ללא דגימה למשך ימים מרובים

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

מדיניות בנושא מכסות

לרשימה המלאה של המגבלות והמכסות שחלות בזמן יצירת דוחות ללא דגימה, אפשר לעיין במאמר מגבלות ומכסות בממשק ה-API של ההגדרה והדיווח.