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

تسمح لك "مدير الحملة 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));

‫2,999

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

‫2,999

// 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 في مورد File (الملف). يمكنك إعادة توجيه مستخدم إلى عنوان 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();

‫2,999

$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