הוצאנו משימוש את Search Ads 360 Reporting API הקודם. עכשיו אפשר ליצור דוחות באמצעות Search Ads 360 Reporting API החדש.

חשוב לזכור שSearch Ads 360 Conversion API לא מושפע מהשינוי הזה, והתמיכה בו תמשיך.

דף זה תורגם על ידי Cloud Translation API.

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 שבהמשך כדי להפעיל את השיטה הזו בנתונים בזמן אמת ולראות את התגובה. לחלופין, אפשר לנסות את עצמאי חוקר.