تنزيل الملفات وتصديرها

تتيح واجهة برمجة تطبيقات Google Drive API عدة أنواع من إجراءات التنزيل والتصدير، كما هو موضح في الجدول التالي:

عمليات التنزيل	محتوى Blob باستخدام الإجراء files.get مع معلَمة عنوان URL alt=media. محتوى ملف Blob في إصدار سابق باستخدام الإجراء revisions.get مع معلَمة عنوان URL alt=media. محتوى ملف Blob في متصفّح باستخدام الحقل webContentLink
عمليات التصدير	محتوى مستندات Google Workspace بتنسيق يمكن لتطبيقك التعامل معه باستخدام files.export. محتوى مستند Google Workspace في متصفِّح يستخدم الحقل exportLinks محتوى مستند Google Workspace في إصدار سابق في متصفّح يستخدم الحقل exportLinks.

قبل تنزيل محتوى الملف أو تصديره، تأكَّد من أنّه يمكن للمستخدمين تنزيل الملف باستخدام حقل capabilities.canDownload في مورد files.

يقدم الجزء المتبقي من هذا الدليل إرشادات مفصلة عن تنفيذ هذه الأنواع من إجراءات التنزيل والتصدير.

تنزيل محتوى ملف blob

لتنزيل ملف ثنائي كبير مخزّن على Drive، استخدِم الإجراء files.get مع معرّف الملف المطلوب تنزيله ومَعلمة عنوان URL للسمة alt=media. تُعلم معلَمة عنوان URL alt=media الخادم أنه يتم طلب تنزيل المحتوى كتنسيق استجابة بديل.

معلمة عنوان URL alt=media هي مَعلمة نظام متاحة في جميع واجهات برمجة تطبيقات Google REST. إذا كنت تستخدم مكتبة برامج لواجهة برمجة تطبيقات Drive، لن تحتاج إلى ضبط هذه المعلَمة بشكلٍ صريح.

يعرض نموذج الرمز البرمجي التالي كيفية استخدام طريقة files.get لتنزيل ملف باستخدام مكتبات عملاء واجهة برمجة تطبيقات Drive.

ملاحظة: إذا كنت تستخدم الإصدار الثاني من Drive API القديم، يمكنك العثور على عيّنات التعليمات البرمجية في GitHub. تعرَّف على كيفية نقل البيانات إلى الإصدار 3 من Drive API.

Java

drive/snippets/drive_v3/src/main/java/DownloadFile.java

العرض على GitHub

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Arrays;

/* Class to demonstrate use-case of drive's download file. */
public class DownloadFile {

  /**
   * Download a Document file in PDF format.
   *
   * @param realFileId file ID of any workspace document format file.
   * @return byte array stream if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static ByteArrayOutputStream downloadFile(String realFileId) throws IOException {
        /* Load pre-authorized user credentials from the environment.
           TODO(developer) - See https://developers.google.com/identity for
          guides on implementing OAuth2 for your application.*/
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    try {
      OutputStream outputStream = new ByteArrayOutputStream();

      service.files().get(realFileId)
          .executeMediaAndDownloadTo(outputStream);

      return (ByteArrayOutputStream) outputStream;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to move file: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/download_file.py

العرض على GitHub

import io

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaIoBaseDownload


def download_file(real_file_id):
  """Downloads a file
  Args:
      real_file_id: ID of the file to download
  Returns : IO object with location.

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)

    file_id = real_file_id

    # pylint: disable=maybe-no-member
    request = service.files().get_media(fileId=file_id)
    file = io.BytesIO()
    downloader = MediaIoBaseDownload(file, request)
    done = False
    while done is False:
      status, done = downloader.next_chunk()
      print(f"Download {int(status.progress() * 100)}.")

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.getvalue()


if __name__ == "__main__":
  download_file(real_file_id="1KuPmvGq8yoYgbfW74OENMCB5H0n_2Jm9")

Node.js

drive/snippets/drive_v3/file_snippets/download_file.js

العرض على GitHub

/**
 * Downloads a file
 * @param{string} realFileId file ID
 * @return{obj} file status
 * */
async function downloadFile(realFileId) {
  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app

  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});

  fileId = realFileId;
  try {
    const file = await service.files.get({
      fileId: fileId,
      alt: 'media',
    });
    console.log(file.status);
    return file.status;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveDownloadFile.php

العرض على GitHub

use Google\Client;
use Google\Service\Drive;
function downloadFile()
 {
    try {

      $client = new Client();
      $client->useApplicationDefaultCredentials();
      $client->addScope(Drive::DRIVE);
      $driveService = new Drive($client);
      $realFileId = readline("Enter File Id: ");
      $fileId = '0BwwA4oUTeiV1UVNwOHItT0xfa2M';
      $fileId = $realFileId;
      $response = $driveService->files->get($fileId, array(
          'alt' => 'media'));
      $content = $response->getBody()->getContents();
      return $content;

    } catch(Exception $e) {
      echo "Error Message: ".$e;
    }

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/DownloadFile.cs

العرض على GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Download;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use-case of drive's download file.
    public class DownloadFile
    {
        /// <summary>
        /// Download a Document file in PDF format.
        /// </summary>
        /// <param name="fileId">file ID of any workspace document format file.</param>
        /// <returns>byte array stream if successful, null otherwise.</returns>
        public static MemoryStream DriveDownloadFile(string fileId)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential
                    .GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var request = service.Files.Get(fileId);
                var stream = new MemoryStream();

                // Add a handler which will be notified on progress changes.
                // It will notify on each chunk download and when the
                // download is completed or failed.
                request.MediaDownloader.ProgressChanged +=
                    progress =>
                    {
                        switch (progress.Status)
                        {
                            case DownloadStatus.Downloading:
                            {
                                Console.WriteLine(progress.BytesDownloaded);
                                break;
                            }
                            case DownloadStatus.Completed:
                            {
                                Console.WriteLine("Download complete.");
                                break;
                            }
                            case DownloadStatus.Failed:
                            {
                                Console.WriteLine("Download failed.");
                                break;
                            }
                        }
                    };
                request.Download(stream);

                return stream;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

يستخدم نموذج الرمز هذا طريقة مكتبة تضيف معلَمة عنوان URL alt=media إلى طلب HTTP الأساسي.

يجب أن يتم السماح بعمليات تنزيل الملفات التي تبدأ من تطبيقك من خلال نطاق يسمح بالوصول للقراءة إلى محتوى الملف. على سبيل المثال، لا يُسمَح لتطبيق يستخدم نطاق drive.readonly.metadata بتنزيل محتوى الملف. يستخدم نموذج الرمز هذا نطاق ملف "drive" المقيّد الذي يسمح للمستخدمين بعرض جميع ملفات Drive وإدارتها. لمزيد من المعلومات عن نطاقات Drive، يمكنك الاطّلاع على اختيار نطاقات Google Drive API.

يمكن للمستخدمين الذين لديهم أذونات تعديل حظر التنزيل من قِبل مستخدمين لديهم إذن بالقراءة فقط من خلال ضبط الحقل copyRequiresWriterPermission على false.

لا يمكن تنزيل الملفات إلا من قِبل مالك الملف إذا تم تصنيفها بأنّها مسيئة (مثل البرامج الضارة). بالإضافة إلى ذلك، يجب تضمين معلَمة طلب البحث get acknowledgeAbuse=true للإشارة إلى أنّ المستخدم قد أقرّ بخطر تنزيل برامج غير مرغوب فيها أو ملفات أخرى مسيئة. يجب أن يحذر التطبيق المستخدم بشكل تفاعلي قبل استخدام معلمة طلب البحث هذه.

تنزيل جزئي

يتضمن التنزيل الجزئي تنزيل جزء محدد فقط من الملف. يمكنك تحديد جزء الملف الذي تريد تنزيله باستخدام نطاق بايت مع العنوان Range. مثال:

Range: bytes=500-999

ملاحظة: لا تتوفّر إمكانية التنزيل الجزئي أثناء تصدير مستندات Google Workspace.

تنزيل محتوى ملف blob عن إصدار سابق

لتنزيل محتوى ملفات blob في إصدار سابق، استخدِم الإجراء revisions.get مع رقم تعريف الملف الذي تم تنزيله ورقم تعريف النسخة ومَعلمة عنوان URL alt=media. تُعلم معلَمة عنوان URL alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كتنسيق استجابة بديل. على غرار files.get، تقبل الطريقة revisions.get أيضًا مَعلمة طلب البحث الاختيارية acknowledgeAbuse وعنوان Range. للحصول على مزيد من المعلومات حول تنزيل النُسخ السابقة، يُرجى الاطّلاع على تنزيل النُسخ السابقة للملفات ونشرها.

تنزيل محتوى ملف blob في متصفِّح

لتنزيل محتوى ملفات blob التي تم تخزينها على Drive في متصفح، بدلاً من استخدام واجهة برمجة التطبيقات، استخدم الحقل webContentLink في مورد files. إذا كان لدى المستخدم حق الوصول للتنزيل إلى الملف، فسيتم عرض رابط لتنزيل الملف ومحتواه. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL هذا أو عرضه كرابط قابل للنقر.

تصدير محتوى مستند Google Workspace

لتصدير محتوى بايت لمستند Google Workspace، استخدِم الإجراء files.export مع رقم تعريف الملف المطلوب تصديره ونوع MIME الصحيح. يقتصر حجم المحتوى الذي يتم تصديره على 10 ميغابايت.

يوضّح نموذج الرمز التالي كيفية استخدام طريقة files.export لتصدير مستند Google Workspace بتنسيق PDF باستخدام مكتبات برامج Drive API:

ملاحظة: إذا كنت تستخدم الإصدار الثاني من Drive API القديم، يمكنك العثور على عيّنات التعليمات البرمجية في GitHub. تعرَّف على كيفية نقل البيانات إلى الإصدار 3 من Drive API.

Java

drive/snippets/drive_v3/src/main/java/ExportPdf.java

العرض على GitHub

import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.ByteArrayOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.util.Arrays;

/* Class to demonstrate use-case of drive's export pdf. */
public class ExportPdf {

  /**
   * Download a Document file in PDF format.
   *
   * @param realFileId file ID of any workspace document format file.
   * @return byte array stream if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static ByteArrayOutputStream exportPdf(String realFileId) throws IOException {
    // Load pre-authorized user credentials from the environment.
    // TODO(developer) - See https://developers.google.com/identity for
    // guides on implementing OAuth2 for your application.
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    OutputStream outputStream = new ByteArrayOutputStream();
    try {
      service.files().export(realFileId, "application/pdf")
          .executeMediaAndDownloadTo(outputStream);

      return (ByteArrayOutputStream) outputStream;
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to export file: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/export_pdf.py

العرض على GitHub

import io

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaIoBaseDownload


def export_pdf(real_file_id):
  """Download a Document file in PDF format.
  Args:
      real_file_id : file ID of any workspace document format file
  Returns : IO object with location

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)

    file_id = real_file_id

    # pylint: disable=maybe-no-member
    request = service.files().export_media(
        fileId=file_id, mimeType="application/pdf"
    )
    file = io.BytesIO()
    downloader = MediaIoBaseDownload(file, request)
    done = False
    while done is False:
      status, done = downloader.next_chunk()
      print(f"Download {int(status.progress() * 100)}.")

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.getvalue()


if __name__ == "__main__":
  export_pdf(real_file_id="1zbp8wAyuImX91Jt9mI-CAX_1TqkBLDEDcr2WeXBbKUY")

Node.js

drive/snippets/drive_v3/file_snippets/export_pdf.js

العرض على GitHub

/**
 * Download a Document file in PDF format
 * @param{string} fileId file ID
 * @return{obj} file status
 * */
async function exportPdf(fileId) {
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');

  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});

  try {
    const result = await service.files.export({
      fileId: fileId,
      mimeType: 'application/pdf',
    });
    console.log(result.status);
    return result;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveExportPdf.php

العرض على GitHub

use Google\Client;
use Google\Service\Drive;
function exportPdf()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $realFileId = readline("Enter File Id: ");
        $fileId = '1ZdR3L3qP4Bkq8noWLJHSr_iBau0DNT4Kli4SxNc2YEo';
        $fileId = $realFileId;
        $response = $driveService->files->export($fileId, 'application/pdf', array(
            'alt' => 'media'));
        $content = $response->getBody()->getContents();
        return $content;

    }  catch(Exception $e) {
         echo "Error Message: ".$e;
    }

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/ExportPdf.cs

العرض على GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Download;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use of Drive export pdf
    public class ExportPdf
    {
        /// <summary>
        /// Download a Document file in PDF format.
        /// </summary>
        /// <param name="fileId">Id of the file.</param>
        /// <returns>Byte array stream if successful, null otherwise</returns>
        public static MemoryStream DriveExportPdf(string fileId)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for 
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                var request = service.Files.Export(fileId, "application/pdf");
                var stream = new MemoryStream();
                // Add a handler which will be notified on progress changes.
                // It will notify on each chunk download and when the
                // download is completed or failed.
                request.MediaDownloader.ProgressChanged +=
                    progress =>
                    {
                        switch (progress.Status)
                        {
                            case DownloadStatus.Downloading:
                            {
                                Console.WriteLine(progress.BytesDownloaded);
                                break;
                            }
                            case DownloadStatus.Completed:
                            {
                                Console.WriteLine("Download complete.");
                                break;
                            }
                            case DownloadStatus.Failed:
                            {
                                Console.WriteLine("Download failed.");
                                break;
                            }
                        }
                    };
                request.Download(stream);
                return stream;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

يستخدم نموذج الرمز هذا نطاق drive المشروط الذي يسمح للمستخدمين بعرض جميع ملفات Drive وإدارتها. لمزيد من المعلومات عن نطاقات Drive، يمكنك الاطّلاع على اختيار نطاقات Google Drive API.

يذكر نموذج الرمز أيضًا نوع التصدير MIME على أنّه application/pdf. للاطّلاع على قائمة كاملة بجميع أنواع MIME التي يتم تصديرها والمتاحة لكل مستند من مستندات Google Workspace، يُرجى الاطّلاع على المقالة تصدير أنواع MIME لمستندات Google Workspace.

تصدير محتوى مستند Google Workspace في متصفِّح

لتصدير محتوى مستند Google Workspace داخل متصفّح، استخدِم الحقل exportLinks في المرجع files. بناءً على نوع المستند، يتم عرض رابط لتنزيل الملف ومحتواه لكل نوع MIME متاح. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL أو تقديمه كرابط قابل للنقر.

تصدير محتوى مستندات Google Workspace من إصدار سابق في متصفّح

لتصدير محتوى مستند Google Workspace في نسخة سابقة داخل متصفّح، استخدِم طريقة revisions.get مع رقم تعريف الملف لتنزيله ورقم تعريف النسخة. إذا كان المستخدم لديه حق تنزيل الملف، سيتم عرض رابط لتنزيل الملف ومحتواه. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL هذا أو عرضه كرابط قابل للنقر.

مواضيع ذات صلة

• حماية محتوى الملف

• تنزيل النُسخ السابقة من الملفات ونشرها

• تصدير أنواع MIME لمستندات Google Workspace