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

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

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

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

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

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

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

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

שדה	תיאור
שדות חובה
name	שם הדוח.
סוג	את סוג הדוח.
שדות אופציונליים
משלוח	ההגדרות של שליחת האימיילים בדוח.
שם קובץ	שם הקובץ המשמש ליצירת קובצי דוח לדוח הזה.
פורמט	פורמט הפלט של הדוח, בפורמט 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	reach criteria
Path_TO_CONVERSION	pathToConversion בקריטריונים
פנס	קריטריונים לשיטפונות
CROSS_DIMENSION_REACH	קריטריונים להגדלת פוטנציאל החשיפה

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

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

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

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

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

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

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

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

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

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

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

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);

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