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

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

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

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

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

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