تنزيل ملفات التقارير

تسمح لك واجهة برمجة تطبيقات "مدير الحملة 360" بتنزيل ملفات التقارير التي تكون نتيجة تشغيل تقرير "أداة إنشاء التقارير". كما تدعم تزويد المستخدمين بإمكانية الوصول المباشر إلى ملف عبر رابط.

وتبعًا لنوع التنزيل الذي ترغب في إجرائه، ستستخدم أحد الأساليب التالية:

• التنزيل المباشر: Files.get مع المَعلمة alt=media.
• يمكنك تنزيل الملفات في متصفّح: browserUrl من مورد Files.

يوفِّر باقي هذا الدليل تعليمات تفصيلية لتنفيذ هذه الأنواع من عمليات التنزيل عبر مورد الملفات.

المتطلبات الأساسية

لتنزيل ملف، ستحتاج إلى بعض المعلومات:

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

توفِّر العديد من مكتبات البرامج وظيفة التنزيل الجزئي عبر خدمة تنزيل الوسائط. يُرجى الرجوع إلى مستندات مكتبة البرامج للاطّلاع على التفاصيل.

تنزيل الملفات في متصفّح

إذا أردت منح المستخدمين طريقة لتنزيل ملف مباشرةً من متصفح الويب، يمكنك استخدام عنوان URL المقدَّم في الحقل browserUrl ضمن مورد "الملف". ويمكنك إعادة توجيه أحد المستخدمين إلى عنوان URL هذا، أو عرضه كرابط قابل للنقر. في كلتا الحالتين، سيكون على المستخدِم تسجيل الدخول إلى حساب Google لديه إذن الوصول إلى تقارير "مدير الحملة 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