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

تتيح لك واجهة برمجة التطبيقات 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));

جافا

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 ليكون مؤهلاً للتنزيل.

التنزيل المباشر

لتنفيذ عملية تنزيل مباشرة، عليك إرسال طلب GET HTTP معتمد إلى خدمة "الملفات" وتضمين مَعلمة طلب البحث 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);
  }
}

جافا

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

جافا

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