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

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

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

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

للحصول على أوصاف لأنواع الملفات المذكورة هنا، بما في ذلك ملفات الكائن الثنائي الكبير وملفات Google Workspace، يُرجى الاطّلاع على أنواع الملفات.

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

تنزيل محتوى ملف رمز الجلسة

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

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

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

ملاحظة: إذا كنت تستخدِم الإصدار 2 من 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;
        }
    }
}

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

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

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

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

تنزيل جزئي

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

Range: bytes=500-999

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

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

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

يظهر هنا بروتوكول الطلب.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

تنزيل محتوى ملف رمز بيانات في متصفّح

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

تنزيل محتوى ملف العنصر أثناء العمليات التي تستغرق وقتًا طويلاً

لتنزيل محتوى ملفات Blob أثناء العمليات التي تستغرق وقتًا طويلاً، استخدِم الأسلوب files.download مع رقم تعريف الملف المطلوب تنزيله. يمكنك اختياريًا ضبط معرّف النسخة. هذه هي الطريقة الوحيدة لتنزيل ملفات Google Vids. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة العمليات التي تستغرق وقتًا طويلاً.

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

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

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

ملاحظة: إذا كنت تستخدِم الإصدار 2 من 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.

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

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

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

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

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

تصدير محتوى مستندات Google Workspace أثناء العمليات التي تستغرق وقتًا طويلاً

لتصدير محتوى مستند Google Workspace أثناء العمليات التي تستغرق وقتًا طويلاً، استخدِم طريقة files.download مع معرّف الملف المطلوب تنزيله ومعرّف المراجعة. للمزيد من المعلومات، يُرجى الاطّلاع على إدارة العمليات طويلة الأمد.

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

• حماية محتوى الملف
• تصدير أنواع بروتوكول MIME لمستندات Google Workspace