Reports: request

מאכלס בקשת דוח במערכת הדיווח. רוצים לנסות עכשיו?

בקשה

בקשת HTTP

POST https://www.googleapis.com/doubleclicksearch/v2/reports

אישור

הבקשה הזו מחייבת הרשאה עם ההיקף הבא:

היקף
https://www.googleapis.com/auth/doubleclicksearch

מידע נוסף זמין בדף אימות והרשאה.

גוף הבקשה

בגוף הבקשה, מספקים את הנתונים במבנה הבא:

{
  "reportScope": {
    "agencyId": long,
    "advertiserId": long,
    "engineAccountId": long,
    "campaignId": long,
    "adGroupId": long,
    "keywordId": long,
    "adId": long
  },
  "reportType": string,
  "columns": [
    {
      "columnName": string,
      "savedColumnName": string,
      "customDimensionName": string,
      "customMetricName": string,
      "headerText": string,
      "startDate": string,
      "endDate": string,
      "groupByColumn": boolean,
      "platformSource": string,
      "productReportPerspective": string
    }
  ],
  "timeRange": {
    "startDate": string,
    "endDate": string,
    "changedMetricsSinceTimestamp": datetime,
    "changedAttributesSinceTimestamp": datetime
  },
  "filters": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "operator": string,
      "values": [
        (value)
      ]
    }
  ],
  "orderBy": [
    {
      "column": {
        "columnName": string,
        "savedColumnName": string,
        "customDimensionName": string,
        "customMetricName": string,
        "headerText": string,
        "startDate": string,
        "endDate": string,
        "groupByColumn": boolean,
        "platformSource": string,
        "productReportPerspective": string
      },
      "sortOrder": string
    }
  ],
  "includeDeletedEntities": boolean,
  "includeRemovedEntities": boolean,
  "verifySingleTimeZone": boolean,
  "downloadFormat": string,
  "statisticsCurrency": string,
  "startRow": integer,
  "rowCount": integer,
  "maxRowsPerFile": integer
}
שם הנכס ערך תיאור הערות
reportScope object reportScope הוא קבוצה של מזהים שמשמשת כדי לקבוע איזו קבוצת משנה של ישויות יוחזרו בדוח. צריך לציין את השושלת המלאה של מזהים מהרמה הנמוכה ביותר הרצויה דרך הסוכנות.
reportScope.agencyId long מזהה הסוכנות ב-DS.
reportScope.advertiserId long מזהה המפרסם ב-DS.
reportScope.engineAccountId long מספר חשבון מנוע החיפוש ב-DS.
reportScope.campaignId long מזהה הקמפיין ב-DS.
reportScope.adGroupId long מזהה קבוצת מודעות ב-DS.
reportScope.keywordId long מזהה מילת מפתח ב-DS.
reportScope.adId long מזהה מודעה ב-DS.
reportType string קובע את סוג השורות שמוחזרות בדוח. לדוגמה, אם מציינים reportType: keyword, כל שורה בדוח תכיל נתונים לגבי מילת מפתח. בחומר העזר בנושא סוגי דוחות תוכלו לראות אילו עמודות זמינות לכל סוג.
columns[] list העמודות שייכללו בדוח. הנתונים האלה כוללים גם את העמודות של DoubleClick Search וגם את העמודות השמורות. בעמודות של DoubleClick Search, רק הפרמטר columnName נדרש. בעמודות שמורות רק הפרמטר savedColumnName. אי אפשר להגדיר גם את columnName וגם את savedColumnName באותו בית.

אפשר לשלוח עד 300 עמודות לכל בקשה.

columns[].columnName string השם של עמודת DoubleClick Search שתיכלל בדוח.
columns[].savedColumnName string השם של עמודה שמורה שתיכלל בדוח. היקף הדוח צריך להיות ברמת המפרסם או ברמה נמוכה יותר, ויש ליצור את העמודה השמורה הזו כבר בממשק המשתמש של DoubleClick Search.
columns[].headerText string טקסט שמשמש לזיהוי העמודה הזו בפלט הדוח. אם הפרמטר לא מוגדר, ערך ברירת המחדל הוא columnName או savedColumnName. אפשר להשתמש באפשרות הזו כדי למנוע התנגשויות בין עמודות של DoubleClick Search לבין עמודות שמורות עם אותו שם.
columns[].startDate string תאריך כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם endDate.
columns[].endDate string יום כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם startDate.
columns[].groupByColumn boolean דוח סינכרוני בלבד. צריך להגדיר את הערך true כדי לקבץ לפי העמודה הזו. ברירת המחדל היא false.
timeRange object אם יש בקשה למדדים בדוח, הארגומנט הזה ישמש להגבלת המדדים לטווח זמן ספציפי.
timeRange.startDate string תאריך כולל בפורמט YYYY-MM-DD.
timeRange.endDate string תאריך כולל בפורמט YYYY-MM-DD.
timeRange.changedMetricsSinceTimestamp datetime חותמת זמן כוללת לפי שעון UTC בפורמט RFC, לדוגמה: 2013-07-16T10:16:23.555Z. כאן תוכלו לקרוא הסבר נוסף על אופן הפעולה של דוחות המדדים שהשתנו.
timeRange.changedAttributesSinceTimestamp datetime חותמת זמן כוללת לפי שעון UTC בפורמט RFC, לדוגמה: 2013-07-16T10:16:23.555Z. כאן תוכלו לקרוא הסבר נוסף על האופן שבו פועלים דוחות המאפיינים שהשתנו.
filters[] list רשימת מסננים שיחולו על הדוח.

כל בקשה יכולה לכלול עד 300 מסננים.

filters[].column nested object עמודה שלפיה יש לבצע את המסנן. זו יכולה להיות עמודה של DoubleClick Search או עמודה שמורה.
filters[].column.columnName string השם של עמודת DoubleClick Search שתיכלל בדוח.
filters[].column.savedColumnName string השם של עמודה שמורה שתיכלל בדוח. היקף הדוח צריך להיות ברמת המפרסם או ברמה נמוכה יותר, ויש ליצור את העמודה השמורה הזו כבר בממשק המשתמש של DoubleClick Search.
filters[].operator string אופרטור לשימוש במסנן. ניתן לעיין בחומר העזר בנושא מסננים כדי לראות רשימה של האופרטורים הזמינים.
filters[].values[] list רשימת ערכים שלפיהם יתבצע סינון של ערך העמודה.

כל בקשה יכולה לכלול עד 300 ערכי סינון.

orderBy[] list דוח סינכרוני בלבד. רשימת עמודות ומסלולים המגדירות את המיון שיש לבצע על שורות הדוח.

מספר ההזמנות המקסימלי לכל בקשה הוא 300.

orderBy[].column nested object עמודה שלפיה רוצים לבצע מיון. זו יכולה להיות עמודה שהוגדרה ב-DoubleClick Search או עמודה שמורה.
orderBy[].column.columnName string השם של עמודת DoubleClick Search שתיכלל בדוח.
orderBy[].column.savedColumnName string השם של עמודה שמורה שתיכלל בדוח. היקף הדוח צריך להיות ברמת המפרסם או ברמה נמוכה יותר, ויש ליצור את העמודה השמורה הזו כבר בממשק המשתמש של DoubleClick Search.
orderBy[].sortOrder string כיוון המיון, שהוא ascending או descending.
includeDeletedEntities boolean המדיניות קובעת אם ישויות שהוסרו צריכות להיכלל בדוח. ברירת המחדל היא false. הוצא משימוש. במקומו צריך להשתמש ב-includeRemovedEntities.
verifySingleTimeZone boolean אם הערך הוא true, הדוח ייווצר רק אם כל הנתונים הסטטיסטיים המבוקשים מגיעים מאזור זמן אחד. ברירת המחדל היא false.
downloadFormat string הפורמט שבו צריך להחזיר את הדוח. כרגע יש תמיכה ב-csv או ב-tsv.
statisticsCurrency string מציינת את המטבע שבו יוחזר הסכום. הערכים האפשריים הם: usd, agency (תקף אם הדוח בהיקף של סוכנות או היקף נמוך יותר), advertiser (תקף אם הדוח כולל היקף * של המפרסם או קבוצה נמוכה יותר) או account (תקף אם הדוח נכלל ברמת חשבון מנוע חיפוש או רמה נמוכה יותר).
startRow integer דוח סינכרוני בלבד. אינדקס מבוסס אפס של השורה הראשונה שצריך להחזיר. הערכים הקבילים הם 0 עד 50000, כולל. ברירת המחדל היא 0.
rowCount integer דוח סינכרוני בלבד. מספר השורות המקסימלי שצריך להחזיר. שורות נוספות מושמטות. הערכים הקבילים הם 0 עד 10000, כולל. ברירת המחדל היא 10000.
maxRowsPerFile integer דוח אסינכרוני בלבד. מספר השורות המקסימלי לקובץ דוח. דוח גדול מחולק למספר קבצים על סמך השדה הזה. הערכים הקבילים הם 1000000 עד 100000000, כולל.
includeRemovedEntities boolean המדיניות קובעת אם ישויות שהוסרו צריכות להיכלל בדוח. ברירת המחדל היא false.
columns[].customDimensionName string הפילוח של הדוח מתבצע לפי מאפיין מותאם אישית. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, וחובה להגדיר את המאפיין המותאם אישית ב-DoubleClick Search. השם של המאפיין המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.

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

columns[].platformSource string הפלטפורמה שבה משתמשים כדי לספק את הנתונים של המאפיין המותאם אישית. הערכים הקבילים הם 'Floodlight'.
filters[].column.customDimensionName string הפילוח של הדוח מתבצע לפי מאפיין מותאם אישית. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, וחובה להגדיר את המאפיין המותאם אישית ב-DoubleClick Search. השם של המאפיין המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.

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

filters[].column.headerText string טקסט שמשמש לזיהוי העמודה הזו בפלט הדוח. אם הפרמטר לא מוגדר, ערך ברירת המחדל הוא columnName או savedColumnName. אפשר להשתמש באפשרות הזו כדי למנוע התנגשויות בין עמודות של DoubleClick Search לבין עמודות שמורות עם אותו שם.
filters[].column.startDate string תאריך כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם endDate.
filters[].column.endDate string יום כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם startDate.
filters[].column.groupByColumn boolean דוח סינכרוני בלבד. צריך להגדיר את הערך true כדי לקבץ לפי העמודה הזו. ברירת המחדל היא false.
filters[].column.platformSource string הפלטפורמה שבה משתמשים כדי לספק את הנתונים של המאפיין המותאם אישית. הערכים הקבילים הם 'Floodlight'.
orderBy[].column.customDimensionName string הפילוח של הדוח מתבצע לפי מאפיין מותאם אישית. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, וחובה להגדיר את המאפיין המותאם אישית ב-DoubleClick Search. השם של המאפיין המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.

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

orderBy[].column.headerText string טקסט שמשמש לזיהוי העמודה הזו בפלט הדוח. אם הפרמטר לא מוגדר, ערך ברירת המחדל הוא columnName או savedColumnName. אפשר להשתמש באפשרות הזו כדי למנוע התנגשויות בין עמודות של DoubleClick Search לבין עמודות שמורות עם אותו שם.
orderBy[].column.startDate string תאריך כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם endDate.
orderBy[].column.endDate string יום כולל בפורמט YYYY-MM-DD. אם השדה הזה מוגדר, ההגדרה הזאת מבטלת את טווח הזמן הכולל של הדוח בעמודה הזו בלבד. יש לספק אותו יחד עם startDate.
orderBy[].column.groupByColumn boolean דוח סינכרוני בלבד. צריך להגדיר את הערך true כדי לקבץ לפי העמודה הזו. ברירת המחדל היא false.
orderBy[].column.platformSource string הפלטפורמה שבה משתמשים כדי לספק את הנתונים של המאפיין המותאם אישית. הערכים הקבילים הם 'Floodlight'.
columns[].customMetricName string השם של מדד מותאם אישית שייכלל בדוח. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, והמדד המותאם אישית כבר מוגדר ב-DoubleClick Search. שם המדד המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.
filters[].column.customMetricName string השם של מדד מותאם אישית שייכלל בדוח. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, והמדד המותאם אישית כבר מוגדר ב-DoubleClick Search. שם המדד המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.
orderBy[].column.customMetricName string השם של מדד מותאם אישית שייכלל בדוח. היקף הדוח צריך להיות מפרסם או רמה נמוכה יותר, והמדד המותאם אישית כבר מוגדר ב-DoubleClick Search. שם המדד המותאם אישית, שמופיע ב-DoubleClick Search, הוא תלוי אותיות רישיות.
columns[].productReportPerspective string מחזירה מדדים רק לגבי סוג ספציפי של פעילות במוצר. הערכים הקבילים הם:
  • "sold": מדדים של החזרת מוצרים רק לגבי מוצרים שנמכרו
  • "advertised": החזרת מדדים לגבי מוצרים שפורסמו רק בקמפיין שופינג, וכאלה שנמכרו או לא נמכרו
filters[].column.productReportPerspective string מחזירה מדדים רק לגבי סוג ספציפי של פעילות במוצר. הערכים הקבילים הם:
  • "sold": מדדים של החזרת מוצרים רק לגבי מוצרים שנמכרו
  • "advertised": החזרת מדדים לגבי מוצרים שפורסמו רק בקמפיין שופינג, וכאלה שנמכרו או לא נמכרו
orderBy[].column.productReportPerspective string מחזירה מדדים רק לגבי סוג ספציפי של פעילות במוצר. הערכים הקבילים הם:
  • "sold": מדדים של החזרת מוצרים רק לגבי מוצרים שנמכרו
  • "advertised": החזרת מדדים לגבי מוצרים שפורסמו רק בקמפיין שופינג, וכאלה שנמכרו או לא נמכרו

תשובה

אם הפעולה בוצעה ללא שגיאות, השיטה הזו תחזיר משאב Reports בגוף התגובה.

נסה בעצמך!

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