دانلود فایل های گزارش

رابط برنامه‌نویسی کاربردی (API) مدیر کمپین ۳۶۰ به شما امکان می‌دهد فایل‌های گزارش را که نتیجه اجرای یک گزارش Report Builder هستند، دانلود کنید. همچنین از دسترسی مستقیم کاربران به یک فایل از طریق یک لینک پشتیبانی می‌کند.

بسته به نوع دانلودی که می‌خواهید انجام دهید، از یکی از رویکردهای زیر استفاده خواهید کرد:

• دانلود مستقیم — Files.get با پارامتر alt=media .
• دانلود فایل‌ها در مرورگر — browserUrl از منبع Files.

ادامه‌ی این راهنما، دستورالعمل‌های دقیقی برای انجام این نوع دانلودها از طریق منبع Files ارائه می‌دهد.

پیش‌نیازها

برای دانلود یک فایل، به چند اطلاعات نیاز دارید:

1. شناسه گزارشی که فایل به آن تعلق دارد. می‌توانید این شناسه را با ایجاد یک گزارش جدید یا جستجوی یک گزارش موجود پیدا کنید.
2. شناسه فایلی که باید دانلود شود. می‌توانید این شناسه را با اجرای گزارش مرحله قبل یا جستجوی لیست فایل‌های موجود مانند مثال زیر پیدا کنید:

سی شارپ

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

جاوا

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

پی اچ پی

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

پایتون

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

روبی

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 پاسخ پیدا کنید.

اکثر کتابخانه‌های رسمی کلاینت گوگل، روش‌های راحتی برای شروع دانلود مستقیم ارائه می‌دهند، همانطور که در مثال زیر نشان داده شده است. اگر ترجیح می‌دهید دانلود را به صورت دستی شروع کنید، یک URL از پیش ساخته شده در فیلد apiUrl از منبع فایل ارائه شده است.

سی شارپ

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

جاوا

// 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());
}

پی اچ پی

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

پایتون

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

روبی

# 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

دانلودهای قابل از سرگیری

هنگام دانلود فایل‌های گزارش بزرگ، ممکن است دانلود در میانه راه با شکست مواجه شود. برای آسان‌تر کردن بازیابی و از سرگیری دانلود ناموفق، سرویس فایل از قابلیت دانلود جزئی پشتیبانی می‌کند.

دانلود جزئی شامل درخواست بخش‌های خاصی از یک فایل است که به شما امکان می‌دهد دانلودهای بزرگ را به قطعات کوچک‌تر تقسیم کنید. می‌توانید با قرار دادن یک محدوده بایت در هدر Range HTTP درخواست خود، مشخص کنید که کدام بخش از فایل را می‌خواهید دانلود کنید. به عنوان مثال:

Range: bytes=500-999

قابلیت دانلود جزئی توسط بسیاری از کتابخانه‌های کلاینت از طریق سرویس دانلود رسانه ارائه می‌شود. برای جزئیات بیشتر به مستندات کتابخانه کلاینت مراجعه کنید.

دانلود فایل‌ها در مرورگر

اگر می‌خواهید به کاربران راهی برای دانلود مستقیم فایل از مرورگر وبشان ارائه دهید، می‌توانید از URL ارائه شده در فیلد browserUrl از منبع File استفاده کنید. می‌توانید کاربر را به این URL هدایت کنید یا آن را به عنوان یک لینک قابل کلیک ارائه دهید. در هر صورت، برای شروع دانلود، کاربر باید به یک حساب گوگل با دسترسی به گزارش‌گیری Campaign Manager 360 وارد شده باشد و مجوزهای صحیح برای دسترسی به فایل مشخص شده را داشته باشد.

سی شارپ

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

جاوا

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

پی اچ پی

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

پایتون

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

روبی

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