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

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

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

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

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

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

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

שדהתיאור
שדות חובה
שםשם הדוח.
סוגסוג הדוח.
שדות אופציונליים
deliveryהגדרות משלוח האימייל של הדוח.
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'
)

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

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

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

סוג הדוח שדה קריטריונים
STANDARD criteria
REACH reachCriteria
PATH_TO_CONVERSION pathToConversionCriteria
FLOODLIGHT 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);

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