חיפוש והרצה של דוחות

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

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

חיפוש דוח

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

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

C#‎

Report target = null;
ReportList reports;
String nextPageToken = null;

do {
  // Create and execute the reports list request.
  ReportsResource.ListRequest request = service.Reports.List(profileId);
  request.PageToken = nextPageToken;
  reports = request.Execute();

  foreach (Report report in reports.Items) {
    if (IsTargetReport(report)) {
      target = report;
      break;
    }
  }

  // Update the next page token.
  nextPageToken = reports.NextPageToken;
} while (target == null
    && reports.Items.Any()
    && !String.IsNullOrEmpty(nextPageToken));

Java

Report target = null;
ReportList reports;
String nextPageToken = null;

do {
  // Create and execute the reports list request.
  reports = reporting.reports().list(profileId).setPageToken(nextPageToken).execute();

  for (Report report : reports.getItems()) {
    if (isTargetReport(report)) {
      target = report;
      break;
    }
  }

  // Update the next page token.
  nextPageToken = reports.getNextPageToken();
} while (target == null
    && !reports.getItems().isEmpty()
    && !Strings.isNullOrEmpty(nextPageToken));

PHP

$target = null;
$response = null;
$pageToken = null;

do {
    // Create and execute the report list request.
    $response = $this->service->reports->listReports(
        $userProfileId,
        ['pageToken' => $pageToken]
    );

    foreach ($response->getItems() as $report) {
        if ($this->isTargetReport($report)) {
            $target = $report;
            break;
        }
    }

    $pageToken = $response->getNextPageToken();
} while (empty($target) && !empty($response->getItems()) && !empty($pageToken));

Python

target = None

# Construct the request.
request = service.reports().list(profileId=profile_id)

while True:
  response = request.execute()

  for report in response['items']:
    if is_target_report(report):
      target = report
      break

  if not target and response['items'] and response['nextPageToken']:
    request = service.reports().list_next(request, response)
  else:
    break

Ruby

page_token = nil
target = nil

loop do
  result = service.list_reports(profile_id, page_token: page_token)

  result.items.each do |report|
    if target_report?(report)
      target = report
      break
    end
  end

  page_token = (result.next_page_token if target.nil? && result.items.any?)
  break if page_token.to_s.empty?
end

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

הרצת דוח

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

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

C#‎

// Run the report.
File file = service.Reports.Run(profileId, reportId).Execute();

Java

// Run the report.
File file = reporting.reports().run(profileId, reportId).execute();

PHP

// Run the report.
$file = $this->service->reports->run($userProfileId, $reportId);

Python

# Run the report.
report_file = service.reports().run(
    profileId=profile_id, reportId=report_id).execute()

Ruby

# Run the report.
report_file = service.run_report(profile_id, report_id)

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

מתי מסתיים הריצה של דוח?

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

  1. שדה id, שאפשר להשתמש בו כדי להפנות לקובץ הזה בבקשות הבאות.
  2. שדה status שמייצג את המצב הנוכחי של הרצת הדוח.

כדי לדעת מתי הדוח סיים לפעול, צריך לבדוק מעת לעת את status של הקובץ, כמו בדוגמה הבאה:

C#‎

// Wait for the report file to finish processing.
// An exponential backoff policy is used to limit retries and conserve quota.
int sleep = 0;
int startTime = GetCurrentTimeInSeconds();
do {
  File file = service.Files.Get(reportId, fileId).Execute();

  if ("REPORT_AVAILABLE".Equals(file.Status)) {
    Console.WriteLine("File status is {0}, ready to download.", file.Status);
    return;
  } else if (!"PROCESSING".Equals(file.Status)) {
    Console.WriteLine("File status is {0}, processing failed.", file.Status);
    return;
  } else if (GetCurrentTimeInSeconds() - startTime > MAX_RETRY_ELAPSED_TIME) {
    Console.WriteLine("File processing deadline exceeded.");
    return;
  }

  sleep = GetNextSleepInterval(sleep);
  Console.WriteLine("File status is {0}, sleeping for {1} seconds.", file.Status, sleep);
  Thread.Sleep(sleep * 1000);
} while (true);

Java

BackOff backOff =
    new ExponentialBackOff.Builder()
        .setInitialIntervalMillis(10 * 1000) // 10 second initial retry
        .setMaxIntervalMillis(10 * 60 * 1000) // 10 minute maximum retry
        .setMaxElapsedTimeMillis(60 * 60 * 1000) // 1 hour total retry
        .build();

do {
  File file = reporting.files().get(reportId, fileId).execute();

  if ("REPORT_AVAILABLE".equals(file.getStatus())) {
    // File has finished processing.
    System.out.printf("File status is %s, ready to download.%n", file.getStatus());
    return file;
  } else if (!"PROCESSING".equals(file.getStatus())) {
    // File failed to process.
    System.out.printf("File status is %s, processing failed.", file.getStatus());
    return null;
  }

  // The file hasn't finished processing yet, wait before checking again.
  long retryInterval = backOff.nextBackOffMillis();
  if (retryInterval == BackOff.STOP) {
    System.out.println("File processing deadline exceeded.%n");
    return null;
  }

  System.out.printf("File status is %s, sleeping for %dms.%n", file.getStatus(), retryInterval);
  Thread.sleep(retryInterval);
} while (true);

PHP

// Wait for the report file to finish processing.
// An exponential backoff policy is used to limit retries and conserve
// quota.
$sleep = 0;
$startTime = time();

do {
    $file = $this->service->files->get($reportId, $fileId);

    if ($file->getStatus() === 'REPORT_AVAILABLE') {
        printf('File status is %s, ready to download<br>', $file->getStatus());
        return $file;
    } elseif ($file->getStatus() !== 'PROCESSING') {
        printf('File status is %s, processing failed<br>', $file->getStatus());
        return null;
    } elseif (time() - $startTime > self::MAX_RETRY_ELAPSED_TIME) {
        printf('File processing deadline exceeded<br>');
        return null;
    }

    $sleep = $this->getNextSleepInterval($sleep);
    printf(
        'File status is %s, sleeping for %d seconds<br>',
        $file->getStatus(),
        $sleep
    );
    $this->sleep($sleep);
} while (true);

Python

# Wait for the report file to finish processing.
# An exponential backoff strategy is used to conserve request quota.
sleep = 0
start_time = time.time()
while True:
  report_file = service.files().get(
      reportId=report_id, fileId=file_id).execute()

  status = report_file['status']
  if status == 'REPORT_AVAILABLE':
    print 'File status is %s, ready to download.' % status
    return
  elif status != 'PROCESSING':
    print 'File status is %s, processing failed.' % status
    return
  elif time.time() - start_time > MAX_RETRY_ELAPSED_TIME:
    print 'File processing deadline exceeded.'
    return

  sleep = next_sleep_interval(sleep)
  print 'File status is %s, sleeping for %d seconds.' % (status, sleep)
  time.sleep(sleep)

Ruby

# Wait for the report file to finish processing.
# An exponential backoff strategy is used to conserve request quota.
interval = 0
start_time = Time.now
loop do
  report_file = service.get_file(report_id, file_id)

  status = report_file.status
  if status == 'REPORT_AVAILABLE'
    puts format('File status is %s, ready to download.', status)
    break
  elsif status != 'PROCESSING'
    puts format('File status is %s, processing failed.', status)
    break
  elsif Time.now - start_time > MAX_RETRY_ELAPSED_TIME
    puts 'File processing deadline exceeded.'
    break
  end

  interval = next_sleep_interval(interval)
  puts format('File status is %s, sleeping for %d seconds.', status,
    interval)
  sleep(interval)
end

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