יצירה ועדכון של דוחות

שירות הדוחות ב-Campaign Manager 360 API מאפשר ליצור ולעדכן דוחות ב'יוצר הדוחות' באמצעות אובייקטים של מקורות מידע. משאב הדוח מתאר מידע בסיסי על הדוח להרצה, וכן את המבנה של פלט הדוח.

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

הגדרה של משאב דוח

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

  1. מועדף: ביצוע עדכון חלקי. בשיטה הזו מקבלים משאב ריק ומגדירים את השדות שרוצים לשנות. עדכון חלקי שומר רק שינויים בשדות שציינתם.
  2. מתבצע עדכון מלא. באמצעות גישה זו, תטען משאב קיים של דוח ותשנה את השדות שלו ישירות. עדכון מלא שומר תמיד את כל השדות בדוח.

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

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

השדות המשותפים האלו מרכיבים את השלד של הדוח. הדוגמה הבאה ממחישה איך יוצרים משאב חדש של דוח רגיל:

C#‎

Report report = new Report();

// Set the required fields "name" and "type".
report.Name = "Example standard report";
report.Type = "STANDARD";

// Set optional fields.
report.FileName = "example_report";
report.Format = "CSV";

Java

Report report = new Report();

// Set the required fields "name" and "type".
report.setName("Example standard report");
report.setType("STANDARD");

// Set optional fields
report.setFileName("example_report");
report.setFormat("CSV");

PHP

$report = new Google_Service_Dfareporting_Report();

// Set the required fields "name" and "type".
$report->setName('Example standard report');
$report->setType('STANDARD');

// Set optional fields.
$report->setFileName('example_report');
$report->setFormat('CSV');

Python

report = {
    # Set the required fields "name" and "type".
    'name': 'Example Standard Report',
    'type': 'STANDARD',
    # Set optional fields.
    'fileName': 'example_report',
    'format': 'CSV'
}

Ruby

report = DfareportingUtils::API_NAMESPACE::Report.new(
  # Set the required fields "name" and "type".
  name: 'Example Standard Report',
  type: 'STANDARD',
  # Set optional fields.
  file_name: 'example_report',
  format: 'CSV'
)

הגדרת הקריטריונים של הדוח

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

הקריטריונים לשימוש תלויים בסוג הדוח. הקשר בין סוג הדוח לקריטריונים מוסבר בטבלה הבאה:

סוג הדוח שדה קריטריונים
רגילה קריטריונים
REACH reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
זרקור floodlightCriteria
CROSS_DIMENSION_REACH crossDimensionReachCriteria

כל אחד מהקריטריונים הספציפיים האלו חושף קבוצה שונה במקצת של השדות, אבל יש קבוצה של שדות קריטריונים נפוצים שמשמשים בדרך כלל לשליטה בפלט הדוח:

שדה תיאור
dateRange התאריכים שלגביהם יש להריץ את הדוח הזה. אפשר להשתמש במאפיין הזה כדי לציין תאריכי התחלה וסיום מותאמים אישית, או טווח תאריכים יחסי.
dimensionFilters רשימת מסננים שמגבילים את התוצאות שהוחזרו. מידע נוסף על הגדרת מסננים זמין בקטע ערכי מסננים של שאילתות.
מימדים רשימה של רכיבי Campaign Manager 360 שייכללו בפלט הדוח.
metricNames יחידות מידה סטנדרטיות שצריך לכלול בפלט הדוח.

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

הדוגמה הבאה מוסיפה קריטריונים בסיסיים למשאב הדוחות הרגיל שלנו:

C#‎

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
DateRange dateRange = new DateRange();
dateRange.EndDate = DateTime.Now.ToString("yyyy-MM-dd");
dateRange.StartDate = DateTime.Now.AddDays(-30).ToString("yyyy-MM-dd");

// Create a report criteria.
SortedDimension dimension = new SortedDimension();
dimension.Name = "advertiser";

Report.CriteriaData criteria = new Report.CriteriaData();
criteria.DateRange = dateRange;
criteria.Dimensions = new List<SortedDimension>() { dimension };
criteria.MetricNames = new List<string>() {
  "clicks",
  "impressions"
};

// Add the criteria to the report resource.
report.Criteria = criteria;

Java

// Define a date range to report on. This example uses explicit start and end dates to mimic
// the "LAST_MONTH" relative date range.
DateRange dateRange = new DateRange();
dateRange.setEndDate(new DateTime(true, System.currentTimeMillis(), null));

Calendar lastMonth = Calendar.getInstance();
lastMonth.add(Calendar.MONTH, -1);
dateRange.setStartDate(new DateTime(true, lastMonth.getTimeInMillis(), null));

// Create a report criteria.
Report.Criteria criteria = new Report.Criteria();
criteria.setDateRange(dateRange);
criteria.setDimensions(Lists.newArrayList(new SortedDimension().setName("advertiser")));
criteria.setMetricNames(Lists.newArrayList("clicks", "impressions"));

// Add the criteria to the report resource.
report.setCriteria(criteria);

PHP

// Define a date range to report on. This example uses explicit start and
// end dates to mimic the "LAST_30_DAYS" relative date range.
$dateRange = new Google_Service_Dfareporting_DateRange();
$dateRange->setStartDate(
    date('Y-m-d', mktime(0, 0, 0, date('m'), date('d') - 30, date('Y')))
);
$dateRange->setEndDate(date('Y-m-d'));

// Create a report criteria.
$dimension = new Google_Service_Dfareporting_SortedDimension();
$dimension->setName('advertiser');

$criteria = new Google_Service_Dfareporting_ReportCriteria();
$criteria->setDateRange($dateRange);
$criteria->setDimensions([$dimension]);
$criteria->setMetricNames(['clicks', 'impressions']);

// Add the criteria to the report resource.
$report->setCriteria($criteria);

Python

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
end_date = date.today()
start_date = end_date - timedelta(days=30)

# Create a report criteria.
criteria = {
    'dateRange': {
        'startDate': start_date.strftime('%Y-%m-%d'),
        'endDate': end_date.strftime('%Y-%m-%d')
    },
    'dimensions': [{
        'name': 'advertiser'
    }],
    'metricNames': ['clicks', 'impressions']
}

# Add the criteria to the report resource.
report['criteria'] = criteria

Ruby

# Define a date range to report on. This example uses explicit start and end
# dates to mimic the "LAST_30_DAYS" relative date range.
start_date = DateTime.now.prev_day(30).strftime('%Y-%m-%d')
end_date = DateTime.now.strftime('%Y-%m-%d')

# Create a report criteria
criteria = DfareportingUtils::API_NAMESPACE::Report::Criteria.new(
  date_range: DfareportingUtils::API_NAMESPACE::DateRange.new(
    start_date: start_date,
    end_date: end_date
  ),
  dimensions: [
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: 'advertiser'
    )
  ],
  metric_names: ['clicks', 'impressions']
)

# Add the criteria to the report resource.
report.criteria = criteria

ערכי סינון של שאילתות

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

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

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

C#‎

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.StartDate = report.Criteria.DateRange.StartDate;
request.EndDate = report.Criteria.DateRange.EndDate;
request.DimensionName = "advertiser";

DimensionValueList values =
    service.DimensionValues.Query(request, profileId).Execute();

if (values.Items.Any()) {
  // Add a value as a filter to the report criteria.
  report.Criteria.DimensionFilters = new List<DimensionValue>() {
    values.Items[0]
  };
}

Java

// Query advertiser dimension values for report run dates.
DimensionValueRequest request = new DimensionValueRequest();
request.setStartDate(report.getCriteria().getDateRange().getStartDate());
request.setEndDate(report.getCriteria().getDateRange().getEndDate());
request.setDimensionName("advertiser");

DimensionValueList values = reporting.dimensionValues().query(profileId, request).execute();

if (!values.getItems().isEmpty()) {
  // Add a value as a filter to the report criteria.
  List<DimensionValue> filters = Lists.newArrayList(values.getItems().get(0));
  report.getCriteria().setDimensionFilters(filters);
}

PHP

// Query advertiser dimension values for report run dates.
$request = new Google_Service_Dfareporting_DimensionValueRequest();
$request->setStartDate(
    $report->getCriteria()->getDateRange()->getStartDate()
);
$request->setEndDate(
    $report->getCriteria()->getDateRange()->getEndDate()
);
$request->setDimensionName('advertiser');

$values =
    $this->service->dimensionValues->query($userProfileId, $request);

if (!empty($values->getItems())) {
    // Add a value as a filter to the report criteria.
    $report->getCriteria()->setDimensionFilters([$values->getItems()[0]]);
}

Python

# Query advertiser dimension values for report run dates.
request = {
    'dimensionName': 'advertiser',
    'endDate': report['criteria']['dateRange']['endDate'],
    'startDate': report['criteria']['dateRange']['startDate']
}

values = service.dimensionValues().query(
    profileId=profile_id, body=request).execute()

if values['items']:
  # Add a value as a filter to the report criteria.
  report['criteria']['dimensionFilters'] = [values['items'][0]]

Ruby

# Query advertiser dimension values for report run dates.
dimension = DfareportingUtils::API_NAMESPACE::DimensionValueRequest.new(
  dimension_name: 'advertiser',
  start_date: report.criteria.date_range.start_date,
  end_date: report.criteria.date_range.end_date
)

values = service.query_dimension_value(profile_id, dimension)

unless values.items.empty?
  # Add a value as a filter to the report criteria.
  report.criteria.dimension_filters = [values.items.first]
end

קביעת תאימות של שדות

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

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

הדוגמה הבאה ממחישה איך ליצור בקשה לדוגמה של שדות תואמים, ולהשתמש במשאב הדוח שלנו כקלט:

C#‎

CompatibleFields fields =
    service.Reports.CompatibleFields.Query(report, profileId).Execute();

ReportCompatibleFields reportFields = fields.ReportCompatibleFields;

if(reportFields.Dimensions.Any()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.Dimensions[0];
  SortedDimension sortedDimension = new SortedDimension();
  sortedDimension.Name = dimension.Name;
  report.Criteria.Dimensions.Add(sortedDimension);
} else if (reportFields.Metrics.Any()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.Metrics[0];
  report.Criteria.MetricNames.Add(metric.Name);
}

Java

CompatibleFields fields = reporting.reports().compatibleFields()
    .query(profileId, report).execute();

ReportCompatibleFields reportFields = fields.getReportCompatibleFields();

if (!reportFields.getDimensions().isEmpty()) {
  // Add a compatible dimension to the report.
  Dimension dimension = reportFields.getDimensions().get(0);
  SortedDimension sortedDimension = new SortedDimension().setName(dimension.getName());
  report.getCriteria().getDimensions().add(sortedDimension);
} else if (!reportFields.getMetrics().isEmpty()) {
  // Add a compatible metric to the report.
  Metric metric = reportFields.getMetrics().get(0);
  report.getCriteria().getMetricNames().add(metric.getName());
}

PHP

$fields = $this->service->reports_compatibleFields->query(
    $userProfileId,
    $report
);

$reportFields = $fields->getReportCompatibleFields();

if (!empty($reportFields->getDimensions())) {
    // Add a compatible dimension to the report.
    $dimension = $reportFields->getDimensions()[0];
    $sortedDimension = new Google_Service_Dfareporting_SortedDimension();
    $sortedDimension->setName($dimension->getName());
    $report->getCriteria()->setDimensions(
        array_merge(
            $report->getCriteria()->getDimensions(),
            [$sortedDimension]
        )
    );
} elseif (!empty($reportFields->getMetrics())) {
    // Add a compatible metric to the report.
    $metric = $reportFields->getMetrics()[0];
    $report->getCriteria()->setMetricNames(
        array_merge(
            $report->getCriteria()->getMetricNames(),
            [$metric->getName()]
        )
    );
}

Python

fields = service.reports().compatibleFields().query(
    profileId=profile_id, body=report).execute()

report_fields = fields['reportCompatibleFields']

if report_fields['dimensions']:
  # Add a compatible dimension to the report.
  report['criteria']['dimensions'].append({
      'name': report_fields['dimensions'][0]['name']
  })
elif report_fields['metrics']:
  # Add a compatible metric to the report.
  report['criteria']['metricNames'].append(
      report_fields['metrics'][0]['name'])

Ruby

fields = service.query_report_compatible_field(profile_id, report)

report_fields = fields.report_compatible_fields

if report_fields.dimensions.any?
  # Add a compatible dimension to the report.
  report.criteria.dimensions <<
    DfareportingUtils::API_NAMESPACE::SortedDimension.new(
      name: report_fields.dimensions.first.name
    )
elsif report_fields.metrics.any?
  # Add a compatible metric to the report.
  report.criteria.metric_names << report_fields.metrics.first.name
end

שמירת הדוח

השלב האחרון בתהליך הזה הוא שמירה של משאב הדוח. אם יוצרים דוח חדש, אפשר להוסיף אותו באמצעות קריאה אל Reports.insert:

C#‎

Report insertedReport =
    service.Reports.Insert(report, profileId).Execute();

Java

Report insertedReport = reporting.reports().insert(profileId, report).execute();

PHP

$insertedReport =
    $this->service->reports->insert($userProfileId, $report);

Python

inserted_report = service.reports().insert(
    profileId=profile_id, body=report).execute()

Ruby

report = service.insert_report(profile_id, report)

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

C#‎

// Patch an existing report.
Report patchedReport =
    service.Reports.Patch(report, profileId, reportId).Execute();

Java

// Patch an existing report.
Report patchedReport = reporting.reports().patch(profileId, reportId, report).execute();

PHP

# Patch an existing report.
$patchedReport =
    $this->service->reports->patch($userProfileId, $reportId, $report)

Python

# Patch an existing report.
patched_report = service.reports().patch(
    profileId=profile_id, reportId=report_id, body=report).execute();

Ruby

# Patch an existing report.
patched_report = service.patch_report(profile_id, report_id, report)

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

C#‎

// Update an existing report.
Report updatedReport =
    service.Reports.Update(report, profileId, report.Id).Execute();

Java

// Update an existing report.
Report updatedReport = reporting.reports().update(profileId, report.getId(), report).execute();

PHP

# Update an existing report.
$updatedReport =
    $this->service->reports->update($userProfileId, $report->getId(), $report)

Python

# Update an existing report.
updated_report = service.reports().update(
    profileId=profile_id, reportId=report['id'], body=report).execute();

Ruby

# Update an existing report.
updated_report = service.update_report(profile_id, report.id, report);

אם בקשת השמירה תאושר, יוחזר עותק של משאב הדוח בגוף התשובה. במשאב הזה ימולאו כמה שדות חדשים, והחשוב מביניהם הוא השדה 'מזהה'. המזהה הזה הוא המזהה שבו תשתמשו כדי להתייחס לדוח הזה בכל שאר תהליך העבודה שלכם.