הורדת קובצי דוח

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

בהתאם לסוג ההורדה שברצונך לבצע, תשתמש באחת מהגישות הבאות:

• הורדה ישירה — Files.get עם הפרמטר alt=media.
• הורדת קבצים בדפדפן – browserUrl מהמשאב 'קבצים'.

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

דרישות מוקדמות

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

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

C#‎

File target = null;
FileList files;
String nextPageToken = null;

do {
  // Create and execute the files list request.
  ReportsResource.FilesResource.ListRequest request =
      service.Reports.Files.List(profileId, reportId);
  request.PageToken = nextPageToken;
  files = request.Execute();

  foreach (File file in files.Items) {
    if (IsTargetFile(file)) {
      target = file;
      break;
    }
  }

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

Java

File target = null;
FileList files;
String nextPageToken = null;

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

  for (File file : files.getItems()) {
    if (isTargetFile(file)) {
      target = file;
      break;
    }
  }

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

PHP

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

do {
    // Create and execute the file list request.
    $response = $this->service->reports_files->listReportsFiles(
        $userProfileId,
        $reportId,
        ['pageToken' => $pageToken]
    );

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

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

Python

target = None

request = service.reports().files().list(
    profileId=profile_id, reportId=report_id)

while True:
  response = request.execute()

  for report_file in response['items']:
    if is_target_file(report_file):
      target = report_file
      break

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

Ruby

page_token = nil
target = nil

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

  result.items.each do |file|
    if target_file?(file)
      target = file
      break
    end
  end

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

שימו לב שהשדה status של משאב הקובץ חייב להיות מוגדר כ-REPORT_AVAILABLE כדי שתוכלו להוריד אותו.

הורדה ישירה

כדי לבצע הורדה ישירה, צריך לשלוח בקשת HTTP GET מורשית לשירות Files ולכלול את פרמטר השאילתה alt=media. בקשה לדוגמה עשויה להיראות כך:

GET https://www.googleapis.com/dfareporting/v3.4/reports/12345/files/12345?alt=media HTTP/1.1
Authorization: Bearer your_auth_token

שימו לב שהתשובה שתקבלו תכיל הפניה אוטומטית, לכן מומלץ להגדיר את האפליקציה כך שהיא תטפל בכך באופן אוטומטי. אם ברצונך לטפל בכך באופן ידני, אפשר למצוא את כתובת ה-URL להפניה אוטומטית בכותרת Location של התשובה.

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

C#‎

// Retrieve the file metadata.
File file = service.Files.Get(reportId, fileId).Execute();

if ("REPORT_AVAILABLE".Equals(file.Status)) {
  // Create a get request.
  FilesResource.GetRequest getRequest = service.Files.Get(reportId, fileId);

  // Optional: adjust the chunk size used when downloading the file.
  // getRequest.MediaDownloader.ChunkSize = MediaDownloader.MaximumChunkSize;

  // Execute the get request and download the file.
  using (System.IO.FileStream outFile = new System.IO.FileStream(GenerateFileName(file),
      System.IO.FileMode.Create, System.IO.FileAccess.Write)) {
    getRequest.Download(outFile);
    Console.WriteLine("File {0} downloaded to {1}", file.Id, outFile.Name);
  }
}

Java

// Retrieve the file metadata.
File file = reporting.files().get(reportId, fileId).execute();

if ("REPORT_AVAILABLE".equals(file.getStatus())) {
  // Prepare a local file to download the report contents to.
  java.io.File outFile = new java.io.File(Files.createTempDir(), generateFileName(file));

  // Create a get request.
  Get getRequest = reporting.files().get(reportId, fileId);

  // Optional: adjust the chunk size used when downloading the file.
  // getRequest.getMediaHttpDownloader().setChunkSize(MediaHttpDownloader.MAXIMUM_CHUNK_SIZE);

  // Execute the get request and download the file.
  try (OutputStream stream = new FileOutputStream(outFile)) {
    getRequest.executeMediaAndDownloadTo(stream);
  }

  System.out.printf("File %d downloaded to %s%n", file.getId(), outFile.getAbsolutePath());
}

PHP

// Retrieve the file metadata.
$file = $this->service->files->get($reportId, $fileId);

if ($file->getStatus() === 'REPORT_AVAILABLE') {
    try {
        // Prepare a local file to download the report contents to.
        $fileName = join(
            DIRECTORY_SEPARATOR,
            [sys_get_temp_dir(), $this->generateFileName($file)]
        );
        $fileResource = fopen($fileName, 'w+');
        $fileStream = \GuzzleHttp\Psr7\stream_for($fileResource);

        // Execute the get request and download the file.
        $httpClient = $this->service->getClient()->authorize();
        $result = $httpClient->request(
            'GET',
            $file->getUrls()->getApiUrl(),
            [\GuzzleHttp\RequestOptions::SINK => $fileStream]
        );

        printf('<h3>Report file saved to: %s</h3>', $fileName);
    } finally {
        $fileStream->close();
        fclose($fileResource);
    }
}

Python

# Retrieve the file metadata.
report_file = service.files().get(
    reportId=report_id, fileId=file_id).execute()

if report_file['status'] == 'REPORT_AVAILABLE':
  # Prepare a local file to download the report contents to.
  out_file = io.FileIO(generate_file_name(report_file), mode='wb')

  # Create a get request.
  request = service.files().get_media(reportId=report_id, fileId=file_id)

  # Create a media downloader instance.
  # Optional: adjust the chunk size used when downloading the file.
  downloader = http.MediaIoBaseDownload(
      out_file, request, chunksize=CHUNK_SIZE)

  # Execute the get request and download the file.
  download_finished = False
  while download_finished is False:
    _, download_finished = downloader.next_chunk()

  print('File %s downloaded to %s' % (report_file['id'],
                                      os.path.realpath(out_file.name)))

Ruby

# Retrieve the file metadata.
report_file = service.get_file(report_id, file_id)
return unless report_file.status == 'REPORT_AVAILABLE'

# Prepare a local file to download the report contents to.
File.open(generate_file_name(report_file), 'w') do |out_file|
  # Execute the download request. Providing a download destination
  # retrieves the file contents rather than the file metadata.
  service.get_file(report_id, file_id, download_dest: out_file)

  puts format('File %s downloaded to %s', file_id,
    File.absolute_path(out_file.path))
end

הורדות שניתן להמשיך

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

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

Range: bytes=500-999

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

הורדת קבצים בדפדפן

אם אתם רוצים לספק למשתמשים דרך להוריד קובץ ישירות מדפדפן האינטרנט שלהם, אתם יכולים להשתמש בכתובת ה-URL שצוינה בשדה browserUrl במשאב 'קובץ'. אפשר להפנות את המשתמש לכתובת ה-URL הזו או להציע אותה כקישור שניתן ללחוץ עליו. בכל מקרה, המשתמש צריך להיות מחובר לחשבון Google עם גישה לדוחות של Campaign Manager 360 וצריכה להיות לו ההרשאות המתאימות כדי לגשת לקובץ שצוין, כדי להתחיל בהורדה.

C#‎

File file = service.Files.Get(reportId, fileId).Execute();
String browserUrl = file.Urls.BrowserUrl;

Java

File file = reporting.files().get(reportId, fileId).execute();
String browserUrl = file.getUrls().getBrowserUrl();

PHP

$file = $this->service->files->get($reportId, $fileId);
$browserUrl = $file->getUrls()->getBrowserUrl();

Python

report_file = service.files().get(
    reportId=report_id, fileId=file_id).execute()
browser_url = report_file['urls']['browserUrl']

Ruby

report_file = service.get_file(report_id, file_id)
browser_url = report_file.urls.browser_url