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

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

عمليات التنزيل
ملف تخزين البيانات الثنائية الكبيرة باستخدام الطريقة 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 API.

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

Java

drive/snippets/drive_v3/src/main/java/DownloadFile.java
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
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
/**
 * 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
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
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

تنزيل محتوى ملف الكائن الثنائي الكبير (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 المكتبات:

Java

drive/snippets/drive_v3/src/main/java/ExportPdf.java
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
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
/**
 * 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
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
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 هذا، أو عرضه كعنوان قابل للنقر. .