נתוני דוחות של שאילתות

השיטה reportData.query מספקת דרך סינכרונית לאחזור נתוני דוחות. בניגוד לשירות Reports הרגיל, שמפיק דוחות מבוססי-קובץ (CSV או Excel), השיטה הזו מחזירה נתוני JSON מובנים ישירות בתגובה. הוא מייתר את הצורך להגדיר, ליצור ולשמור מראש משאב Report, ולכן הוא אידיאלי לאחזור ולבדיקה של נתונים בזמן אמת.

סקירה כללית

המדריך הזה יעזור לכם להכיר את נקודת הקצה הזו כדי לשלוח שאילתות לנתוני הדיווח של Campaign Manager 360.

הכנת הבקשה

יוצרים ReportDataQueryRequest ומציינים את המאפיינים, המדדים, טווח התאריכים, המסננים וקריטריוני המיון.

REST

{
  "body": {
    "dateRange": "LAST_7_DAYS",
    "dimensionNames": [
      "advertiser",
      "campaign"
    ],
    "metricNames": [
      "impressions",
      "clicks"
    ],
    "sortBys": [
      {
        "name": "clicks",
        "sortOrder": "DESCENDING"
      }
    ],
    "maxResults": 100
  }
}
dateRange
אובייקט DateRange שמציין את התקופה של השאילתה. אפשר להשתמש בטווח תאריכים מותאם אישית או בטווח תאריכים יחסי.
dimensionNames
רשימה של שמות מאפיינים רגילים לקיבוץ.
metricNames
חובה. רשימה של שמות מדדים רגילים שרוצים לכלול.
dimensionFilters
רשימה של אובייקטים מסוג DimensionValue שמשמשים לסינון נתוני הדוח. הפרמטר הזה מאפשר להגביל את תוצאות השאילתה לערכים ספציפיים של מאפיין.
sortBys
הגדרות מיון של מאפיינים או מדדים. כל הגדרה כוללת את שם השדה ואת סדר המיון.
maxResults
מספר השורות המקסימלי שיוחזר בכל דף (ברירת מחדל: 100, מקסימום: 1000).

חלוקה לדפים

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

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

שליחת הבקשה

שליחת בקשת HTTP POST לנקודת הקצה reportdata/query:

POST https://dfareporting.googleapis.com/dfareporting/v5/userprofiles/{profileId}/reportdata/query

מוודאים שהבקשה מאומתת באמצעות פרטי כניסה רגילים של OAuth 2.0 והיקפי ההרשאות הנדרשים. מידע נוסף זמין במאמר אישור בקשות.

תשובה מוצלחת

שאילתה מוצלחת מחזירה תגובת HTTP 200 OK עם מטען ייעודי (payload) של JSON שמכיל את הערכים columnHeaders, rows ו-totalRow.

{
  "columnHeaders": [
    { "name": "advertiser", "type": "DIMENSION" },
    { "name": "campaign", "type": "DIMENSION" },
    { "name": "impressions", "type": "METRIC" },
    { "name": "clicks", "type": "METRIC" }
  ],
  "rows": [
    {
      "values": [ "Test Advertiser", "Summer Campaign", "148672", "420" ]
    },
    {
      "values": [ "Test Advertiser", "Fall Campaign", "2159", "2" ]
    }
  ],
  "totalRow": {
    "values": [ "", "", "150831", "422" ]
  },
  "nextPageToken": "1234567890"
}
columnHeaders
השם והסוגים (DIMENSION או METRIC) של השדות שמוחזרים.
rows
רשימה של אובייקטים מסוג ReportDataRow שמכילים את תוצאות השאילתה. ערכי המחרוזת בכל שורה מיושרים לפי מיקום עם columnHeaders.
totalRow
שורה אחת של נתונים מצטברים שמייצגת את הסכום של כל המדדים התואמים. שדות של מאפיינים ומדדים שלא ניתן לסכום (לדוגמה, מדדי היקף חשיפה כמו uniqueReachTotalReach) ריקים ("") בשורה הזו.
nextPageToken
טוקן שמשמש בבקשה הבאה לאחזור הדף הבא אם יש שורות נוספות.

זמן אחזור ופסק זמן

מכיוון שזו נקודת קצה סינכרונית, השאילתות מופעלות באופן מיידי והנתונים מוחזרים ישירות בתגובה (עד למגבלת העמודים של maxResults). זמן הביצוע המקסימלי של שאילתות הוא 60 שניות. אם שאילתה חורגת מהמגבלה הזו, ה-API מפסיק את הפעולה ומחזיר שגיאה HTTP 503 Service Unavailable.

אם נתקלתם בשגיאה הזו, נסו לצמצם את טווח התאריכים, לצמצם את המסננים (למשל, סינון לפי מפרסמים או קמפיינים ספציפיים) או לצמצם את מספר המאפיינים והמדדים המבוקשים. לחלופין, אפשר להריץ Report באמצעות reports.run כדי ליצור קובץ דוח להורדה באופן אסינכרוני.

מגבלות על שאילתות

בנקודת הקצה reportdata.query מוגדרות כמה מגבלות כדי להבטיח שהתשובות יהיו אמינות. בקשות שמפירות את ההגבלות האלה נדחות עם תגובה HTTP 400 Bad Request.

מגבלות על טווח התאריכים

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

הגבלות על מדדים ומאפיינים

  • צריך לציין לפחות מדד אחד ב-metricNames.
  • המאפיינים והמדדים ברשימות metricNames ו-dimensionNames חייבים להיות ייחודיים.
  • אי אפשר להשתמש בשאילתות האלה במדדים ובמאפיינים שמסומנים בתווית להורדה בלבד.

מגבלות המכסה

בקשות לנקודת הקצה הזו צורכות את המכסות הבאות:

  • מגבלת קצב למשתמש: 120 בקשות בדקה לכל משתמש (2 QPS)
  • מגבלה יומית לכל פרויקט: 10,000 בקשות ביום לכל פרויקט

בקשות שחורגות מהמגבלות האלה נכשלות ומוחזרת שגיאת HTTP 429 Too Many Requests. אם עוברים בין דפים בתוצאות, כל בקשה לדף חדש (באמצעות הפרמטר pageToken) נספרת כשאילתה נפרדת וצורכת מהמכסה הזו.