تحميل بيانات الملف

تتيح لك Google Drive API تحميل بيانات الملفات عند إنشاء ملف File أو تعديله. للحصول على معلومات عن كيفية إنشاءملف يقتصر على البيانات الوصفية، مثل مجلد، يُرجى الاطّلاع على مقالة إنشاء ملفات تتضمّن بيانات وصفية فقط.

هناك ثلاثة أنواع من عمليات التحميل التي يمكنك إجراؤها:

  • التحميل البسيط (uploadType=media): استخدِم نوع التحميل هذا لنقل ملف وسائط صغير (5 ميغابايت أو أقل) بدون توفير البيانات الوصفية. لإجراء عمليةتحميل بسيطة، يُرجى الرجوع إلى مقالة تنفيذ عملية تحميل بسيطة.

  • التحميل المتعدّد الأجزاء (uploadType=multipart): "استخدِم هذا النوع من التحميل لتحميل ملف صغير (5 ميغابايت أو أقل) مع البيانات الوصفية التي تصف الملف في طلب واحد. لتنفيذ عملية تحميل متعدّد الأجزاء، يُرجى الرجوع إلى مقالة تنفيذ عمليةتحميل متعدّد الأجزاء.

  • التحميل القابل للاستئناف (uploadType=resumable): استخدِم نوع التحميل هذا للملفات الكبيرة (التي يزيد حجمها عن 5 ميغابايت) وعندما يكون هناك احتمال كبير بأن يحدث انقطاع في الشبكة، مثلاً عند إنشاء ملف من تطبيق للأجهزة الجوّالة. تُعدّ عمليات التحميل القابلة للاستئناف خيارًا جيدًا لمعظم التطبيقات، فهي تعمل أيضًا مع الملفات الصغيرة بأقل تكلفة لطلب HTTP إضافي واحد لكل تحميل. لإجراء عملية تحميل قابلة للاستئناف، يُرجى الاطّلاع على مقالة تنفيذ عملية تحميل قابلة للاستئناف.

تُنفِّذ مكتبات عملاء Google API نوعًا واحدًا على الأقل من هذه الأنواع من عمليات التحميل. راجِع مستندات مكتبة العميل للحصول على تفاصيل إضافية حول كيفية استخدام كل نوع.

استخدام PATCH مقابل PUT

للتذكير، يتيح فعل HTTP PATCH تعديلًا جزئيًا لمورد الملف، في حين يتيح فعل HTTP PUT استبدال المورد بالكامل. يُرجى العِلم أنّ PUT يمكن أن تؤدي إلى تغييرات جذرية عند إضافة حقل جديد إلى مورد حالي.

عند تحميل مرجع ملف، اتّبِع الإرشادات التالية:

  • استخدِم فعل HTTP المُسجَّل في مرجع واجهة برمجة التطبيقات للطلب الأوّلي لتحميل ملف قابل للاستئناف أو للطلب الوحيد لتحميل ملف بسيط أو متعدّد الأجزاء.
  • استخدِم PUT لجميع الطلبات اللاحقة لإعادة تحميل المحتوى بعد انقطاعه بعد أن بدأ الطلب. تعمل هذه الطلبات على تحميل المحتوى بغض النظر عن الطريقة التي يتمّ استدعاؤها.

إجراء عملية تحميل بسيطة

لإجراء عملية تحميل بسيطة، استخدِم الطريقة files.create مع uploadType=media.

في ما يلي كيفية إجراء عملية تحميل بسيطة:

HTTP

  1. أنشئ طلب POST لمعرّف الموارد المنتظم (URI)/لطريقة التحميل باستخدام معلَمة طلب البحث uploadType=media:

    POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media

  2. أضِف بيانات الملف إلى نص الطلب.

  3. أضِف رؤوس HTTP التالية:

    • Content-Type. اضبط نوع الوسائط MIME للكائن الذي يتم تحميله.
    • Content-Length: يجب ضبط هذا الإعداد على عدد وحدات البايت التي تحمِّلها. إذا كنت تستخدم ترميز النقل المقطّع، لن يكون هذا العنوان مطلوبًا.
  4. أرسِل الطلب. إذا نجح الطلب، يعرض الخادم رمز الحالة HTTP 200 OK مع البيانات الوصفية للملف. {HTTP}

عند إجراء عملية تحميل بسيطة، يتم إنشاء بيانات وصفية أساسية ويتم استنتاج بعض السمات من الملف، مثل نوع MIME أو modifiedTime. يمكنك استخدام عملية تحميل بسيطة في الحالات التي تتوفّر فيها ملفات صغيرة ولا تكون البيانات الوصفية للملفات مهمة.

تنفيذ عملية تحميل متعدّدة الأجزاء

يتيح لك طلب التحميل المتعدّد الأجزاء تحميل البيانات الوصفية والبيانات في الطلب نفسه. استخدِم هذا الخيار إذا كانت البيانات التي ترسلها صغيرة بما يكفي لتحميلها مرة أخرى، بأكملها، في حال تعذّر الاتصال.

لإجراء عملية تحميل متعدّد الأجزاء، استخدِم الطريقة files.create مع uploadType=multipart.

في ما يلي توضيح لكيفية إجراء تحميل متعدد الأجزاء:

Java

drive/snippets/drive_v3/src/main/java/UploadBasic.java
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.FileContent;
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.api.services.drive.model.File;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/* Class to demonstrate use of Drive insert file API */
public class UploadBasic {

  /**
   * Upload new file.
   *
   * @return Inserted file metadata if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static String uploadBasic() 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();
    // Upload file photo.jpg on drive.
    File fileMetadata = new File();
    fileMetadata.setName("photo.jpg");
    // File's content.
    java.io.File filePath = new java.io.File("files/photo.jpg");
    // Specify media type and file-path for file.
    FileContent mediaContent = new FileContent("image/jpeg", filePath);
    try {
      File file = service.files().create(fileMetadata, mediaContent)
          .setFields("id")
          .execute();
      System.out.println("File ID: " + file.getId());
      return file.getId();
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to upload file: " + e.getDetails());
      throw e;
    }
  }
}

Python

drive/snippets/drive-v3/file_snippet/upload_basic.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaFileUpload


def upload_basic():
  """Insert new file.
  Returns : Id's of the file uploaded

  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_metadata = {"name": "download.jpeg"}
    media = MediaFileUpload("download.jpeg", mimetype="image/jpeg")
    # pylint: disable=maybe-no-member
    file = (
        service.files()
        .create(body=file_metadata, media_body=media, fields="id")
        .execute()
    )
    print(f'File ID: {file.get("id")}')

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

  return file.get("id")


if __name__ == "__main__":
  upload_basic()

Node.js

drive/snippets/drive_v3/file_snippets/upload_basic.js
/**
 * Insert new file.
 * @return{obj} file Id
 * */
async function uploadBasic() {
  const fs = require('fs');
  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});
  const requestBody = {
    name: 'photo.jpg',
    fields: 'id',
  };
  const media = {
    mimeType: 'image/jpeg',
    body: fs.createReadStream('files/photo.jpg'),
  };
  try {
    const file = await service.files.create({
      requestBody,
      media: media,
    });
    console.log('File Id:', file.data.id);
    return file.data.id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveUploadBasic.php
use Google\Client;
use Google\Service\Drive;
# TODO - PHP client currently chokes on fetching start page token
function uploadBasic()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $fileMetadata = new Drive\DriveFile(array(
        'name' => 'photo.jpg'));
        $content = file_get_contents('../files/photo.jpg');
        $file = $driveService->files->create($fileMetadata, array(
            'data' => $content,
            'mimeType' => 'image/jpeg',
            'uploadType' => 'multipart',
            'fields' => 'id'));
        printf("File ID: %s\n", $file->id);
        return $file->id;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    } 

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/UploadBasic.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use of Drive insert file API
    public class UploadBasic
    {
        /// <summary>
        /// Upload new file.
        /// </summary>
        /// <param name="filePath">Image path to upload.</param>
        /// <returns>Inserted file metadata if successful, null otherwise.</returns>
        public static string DriveUploadBasic(string filePath)
        {
            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"
                });

                // Upload file photo.jpg on drive.
                var fileMetadata = new Google.Apis.Drive.v3.Data.File()
                {
                    Name = "photo.jpg"
                };
                FilesResource.CreateMediaUpload request;
                // Create a new file on drive.
                using (var stream = new FileStream(filePath,
                           FileMode.Open))
                {
                    // Create a new file, with metadata and stream.
                    request = service.Files.Create(
                        fileMetadata, stream, "image/jpeg");
                    request.Fields = "id";
                    request.Upload();
                }

                var file = request.ResponseBody;
                // Prints the uploaded file id.
                Console.WriteLine("File ID: " + file.Id);
                return file.Id;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is FileNotFoundException)
                {
                    Console.WriteLine("File not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

HTTP

  1. أنشئ طلبًا من النوع POST إلى عنوان URI ‎ /upload الخاص بالطريقة مع مَعلمة الطلب ‎uploadType=multipart:

    POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart

  2. أنشئ نص الطلب. يجب تنسيق النص وفقًا لنوع المحتوى المتعدّد الأجزاء/المرتبط RFC 2387، والذي يحتوي على جزأين:

    • البيانات الوصفية. يجب أن تأتي البيانات الوصفية أولاً وأن يكون رأس Content-Type مضبوطًا على application/json; charset=UTF-8. أضِف البيانات الوصفية للملف بتنسيق JSON.
    • الوسائط يجب أن تأتي الوسائط في المربّع الثاني وأن تحتوي على عنوان Content-Type من أي نوع MIME. أضِف بيانات الملف إلى جزء الوسائط.

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

  3. أضِف عناوين HTTP ذات المستوى الأعلى التالية:

    • Content-Type. اضبط القيمة على multipart/related وأدرِج سلسلة الحدود التي تستخدمها لتحديد الأجزاء المختلفة من الطلب. على سبيل المثال: Content-Type: multipart/related; boundary=foo_bar_baz
    • Content-Length. يتم ضبطه على إجمالي عدد وحدات البايت في نص الطلب.
  4. أرسِل الطلب.

لإنشاء جزء البيانات الوصفية فقط أو تعديله بدون البيانات المرتبطة، أرسِل طلب POST أو PATCH إلى نقطة نهاية المورد العادية: https://www.googleapis.com/drive/v3/files إذا نجح الطلب، سيعرض الخادم رمز الحالة HTTP 200 OK مع البيانات الوصفية للملف.

عند إنشاء ملفات، يجب تحديد امتداد ملف في الحقل name للملف. على سبيل المثال، عند إنشاء ملف JPEG للصور، يمكنك تحديد رمز مثل "name": "photo.jpg" في البيانات الوصفية. تعرض الطلبات اللاحقة إلى files.get السمة fileExtension للقراءة فقط التي تحتوي على الإضافة المحدّدة في الأصل في الحقل name.

إجراء عملية تحميل قابلة للاستئناف

يتيح لك التحميل القابل للاستئناف استئناف عملية التحميل بعد أن يؤدي أحد أخطاء الاتصالات إلى إيقاف تدفق البيانات. ونظرًا لأنك لست مضطرًا إلى إعادة تشغيل عمليات تحميل الملفات الكبيرة من البداية، يمكن أن تقلل عمليات التحميل القابلة للاستئناف من استخدام معدل نقل البيانات في حالة حدوث فشل في الشبكة.

تكون عمليات التحميل القابلة للاستئناف مفيدة عندما تتفاوت أحجام ملفاتك بشكل كبير أو عندما يكون هناك مهلة زمنية ثابتة للطلبات (مثل المهام التي تعمل في الخلفية لنظام التشغيل المتوافق مع الأجهزة الجوّالة وطلبات معيّنة من App Engine). يمكنك أيضًا استخدام التحميلات القابلة للاستئناف في الحالات التي تريد فيها إظهار شريط تقدم التحميل.

يتكون التحميل القابل للاستئناف من عدة خطوات عالية المستوى:

  1. أرسِل الطلب الأوّلي واسترِد معرّف الموارد المنتظم للجلسة التي يمكن استئنافها.
  2. حمِّل البيانات وتحقّق من حالة التحميل.
  3. (اختياري) إذا انقطعت عملية التحميل، استئنِفها.

إرسال الطلب الأولي

لبدء عملية تحميل قابلة للاستئناف، استخدِم طريقة files.create مع uploadType=resumable.

HTTP

  1. أنشئ طلبًا من النوع POST إلى عنوان URI ‎ /upload الخاص بالطريقة مع مَعلمة الطلب ‎uploadType=resumable:

    POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable

    إذا تمكّن طلب البدء من إكمال العملية، سيتضمّن الردّ رمز حالة HTTP‏ 200 OK. بالإضافة إلى ذلك، يتضمّن الردّ عنوان Location الذي يحدّد معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها:

    HTTP/1.1 200 OK
    Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2
    Content-Length: 0
    

    احفظ معرّف URI للجلسة التي يمكن استئنافها حتى تتمكّن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم لجلسة يمكن استئنافها بعد أسبوع واحد.

  2. إذا كانت لديك بيانات وصفية للملف، أضِف البيانات الوصفية إلى محتوى الطلب بتنسيق JSON. بخلاف ذلك، اترك نص الطلب فارغًا.

  3. أضِف رؤوس HTTP التالية:

    • X-Upload-Content-Type: اختياري يتم ضبطها على نوع MIME لبيانات الملف، والتي يتم نقلها في الطلبات اللاحقة. إذا لم يتم تحديد نوع MIME للبيانات في البيانات الوصفية أو من خلال هذا العنوان، يتم عرض العنصر على أنّه application/octet-stream..
    • X-Upload-Content-Length: اختياري يتم ضبطه على عدد وحدات البايت في بيانات الملف التي يتم نقلها في الطلبات اللاحقة.
    • Content-Type. مطلوب إذا كانت لديك بيانات وصفية للملف. اضبط النوع على application/json; charset=UTF-8.
    • Content-Length. مطلوبة ما لم تستخدم ترميز نقل مقسّمًا. يتم ضبطه على عدد وحدات البايت في نص هذا الطلب الأوّلي.
  4. أرسِل الطلب. إذا كان طلب بدء الجلسة ناجحًا، يحتوي الاستجابة على رمز الحالة 200 OK HTTP. بالإضافة إلى ذلك، يحتوي الردّ على عنوان Location يحدّد معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها. استخدِم معرّف URI لجلسة يمكن استئنافها لتحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم لجلسة يمكن استئنافها بعد أسبوع واحد.

  5. انسخ عنوان URL للجلسة التي يمكن استئنافها واحفظه.

  6. انتقِل إلى تحميل المحتوى.

تحميل المحتوى

هناك طريقتان لتحميل ملف باستخدام جلسة قابلة للاستئناف:

  • تحميل المحتوى في طلب واحد: استخدِم هذا الأسلوب عندما يمكن تحميل الملف في طلب واحد، أو إذا لم يكن هناك حدّ زمني محدّد لأي طلب واحد، أو إذا لم تكن بحاجة إلى عرض مؤشر لتقدّم عملية التحميل. وهذا الأسلوب هو الأفضل لأنّه يتطلّب عددًا أقل من الطلبات ويحقّق أداءً أفضل.
  • تحميل المحتوى في أجزاء متعددة: استخدِم هذا الأسلوب إذا كان عليك تقليل كمية البيانات المنقولة في أي طلب فردي. قد تحتاج إلى تقليل البيانات المنقولة عندما يكون هناك حدّ زمني ثابت لطلبات فردية، كما يمكن أن يكون الحال بالنسبة إلى فئات معيّنة من طلبات App Engine. يكون هذا النهج مفيدًا أيضًا إذا كان عليك تقديم مؤشر مخصّص لمحاولة عرض مستوى تقدّم التحميل.

HTTP - طلب واحد

  1. أنشئ طلبًا باستخدام PUT إلى معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها.
  2. أضِف بيانات الملف إلى محتوى الطلب.
  3. أضِف عنوان HTTP‏ Content-Length، واضبطه على عدد البايتات في الملف.
  4. أرسِل الطلب. إذا انقطع طلب التحميل أو إذا تلقّيت الردّ 5xx، اتّبِع الإجراء الموضّح في استئناف عملية تحميل متوقّفة.

HTTP - طلبات متعددة

  1. أنشئ طلبًا باستخدام PUT إلى معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها.

  2. أضِف بيانات المقطع إلى محتوى الطلب. أنشئ مقاطع متعددة بحجم 256 كيلوبايت (256 × 1024 بايت)، باستثناء المقطع النهائي الذي يكمل التحميل. يجب إبقاء حجم الجزء أكبر قدر ممكن لكي يكون التحميل فعّالاً.

  3. إضافة عناوين HTTP التالية:

    • Content-Length. يتم ضبطه على عدد وحدات البايت في الجزء الحالي.
    • Content-Range. يمكنك ضبط الإعدادات لعرض البايتات في الملف الذي تحمّله. على سبيل المثال، يشير الرمز Content-Range: bytes 0-524287/2000000 إلى أنّك تحمّل Content-Range: bytes 0-524287/2000000 بايت أولى (256 × 1024 × 2) في ملف بحجم 2,000,000 بايت.
  4. أرسِل الطلب وعالج الاستجابة. إذا تم توقّف طلب التحميل أو إذا تلقّيت الردّ 5xx، اتّبِع الإجراء الموضّح في مقالة استئناف عملية تحميل متوقّفة.

  5. كرر الخطوات من 1 إلى 4 لكل مقطع متبقٍ في الملف. استخدِم العنوان Range في الاستجابة لتحديد مكان بدء الجزء التالي. لا تفترض أنّ الخادم تلقّى جميع البايتات المُرسَلة في الطلب السابق.

عند اكتمال عملية تحميل الملفّ بالكامل، ستتلقّى الردّ 200 OK أو 201 Created، بالإضافة إلى أيّ بيانات وصفية مرتبطة بالمصدر.

استئناف عملية تحميل تمت مقاطعتها

إذا تم إنهاء طلب التحميل قبل تلقّي ردّ، أو إذا تلقّيت الردّ 503 Service Unavailable، عليك استئناف عملية التحميل المتوقّفة.

HTTP

  1. لطلب حالة التحميل، أنشِئ طلب PUT فارغًا معرّف الموارد المنتظم (URI) الخاص بالجلسة القابلة للاستئناف.

  2. أضِف عنوان Content-Range للإشارة إلى أنّ الموضع الحالي في الملف غير معروف. على سبيل المثال، اضبط Content-Range على */2000000 إذا كان إجمالي طول الملف هو 2,000,000 بايت. إذا لم تكن تعرف الحجم الكامل للملف، اضبط Content-Range على */*.

  3. أرسِل الطلب.

  4. معالجة الرد:

    • يشير الرمز 200 OK أو 201 Created إلى اكتمال عملية التحميل، وليس من الضروري اتّخاذ أي إجراء آخر.
    • يشير الرمز 308 Resume Incomplete إلى أنّه عليك مواصلةتحميل الملف.
    • تشير استجابة 404 Not Found إلى انتهاء صلاحية جلسة التحميل ويجب إعادة تشغيل التحميل من البداية.
  5. إذا تلقّيت استجابة 308 Resume Incomplete، عليك معالجة عنوان Range للاستجابة لتحديد البايتات التي تلقّاها الخادم. إذا لم يتضمّن الردّRange عنوانًا، يعني ذلك أنّه لم يتم استلام أي وحدات بايت. على سبيل المثال، يشير عنوان Rangebytes=0-42 إلى أنّه تم استلام أول 43 بايت من الملف وأنّ الجزء التالي المطلوب تحميله سيبدأ بالبايت 44.

  6. الآن بعد أن عرفت مكان استئناف التحميل، يمكنك مواصلة تحميل الملف بدءًا من البايت التالي. يمكنك تضمين عنوان Content-Range للإشارة إلى جزء الملف الذي ترسله. على سبيل المثال، يشير الرمز Content-Range: bytes 43-1999999 إلى أنّك تُرسِل البايتات من 44 إلى 2,000,000.

التعامل مع أخطاء تحميل الوسائط

عند تحميل الوسائط، اتّبِع أفضل الممارسات التالية لمعالجة الأخطاء:

  • بالنسبة إلى أخطاء 5xx، يمكنك استئناف عمليات التحميل التي تعذّر إكمالها بسبب انقطاع الاتصال أو إعادة محاولة إكمالها. لمزيد من المعلومات حول كيفية التعامل مع أخطاء 5xx، راجِع الأخطاء 500 و502 و503 و504.
  • في حال حدوث 403 rate limit خطأ، يُرجى إعادة محاولة التحميل. لمزيد من المعلومات عن التعامل مع أخطاء 403 rate limit، يُرجى الاطّلاع على الخطأ 403: rateLimitExceeded.
  • يجب إعادة بدء التحميل عند حدوث أي أخطاء في 4xx (بما في ذلك 403) أثناء عملية تحميل قابلة للاستئناف. تشير هذه الأخطاء إلى انتهاء صلاحية جلسة التحميل ويجب إعادة تشغيلها من خلال طلب معرّف موارد منتظم جديد للجلسة. تنتهي صلاحية جلسات التحميل أيضًا بعد أسبوع واحد من عدم النشاط.

الاستيراد إلى أنواع مستندات Google

عند إنشاء ملف في Drive، قد تحتاج إلى تحويل الملف إلى نوع ملف في Google Workspace، مثل "مستندات Google" أو "جداول بيانات Google". على سبيل المثال، قد تريد تحويل مستند من معالج النصوص المفضّل لديك إلى "مستندات Google" للاستفادة من ميزاته.

لتحويل ملف إلى نوع ملف معيّن في Google Workspace، حدِّد Google Workspace mimeType عند إنشاء الملف.

في ما يلي كيفية تحويل ملف CSV إلى جدول بيانات في Google Workspace:

Java

drive/snippets/drive_v3/src/main/java/UploadWithConversion.java
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.FileContent;
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.api.services.drive.model.File;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/* Class to demonstrate Drive's upload with conversion use-case. */
public class UploadWithConversion {

  /**
   * Upload file with conversion.
   *
   * @return Inserted file id if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static String uploadWithConversion() 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();

    // File's metadata.
    File fileMetadata = new File();
    fileMetadata.setName("My Report");
    fileMetadata.setMimeType("application/vnd.google-apps.spreadsheet");

    java.io.File filePath = new java.io.File("files/report.csv");
    FileContent mediaContent = new FileContent("text/csv", filePath);
    try {
      File file = service.files().create(fileMetadata, mediaContent)
          .setFields("id")
          .execute();
      System.out.println("File ID: " + file.getId());
      return file.getId();
    } 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/upload_with_conversion.py
import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaFileUpload


def upload_with_conversion():
  """Upload file with conversion
  Returns: ID of the file uploaded

  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_metadata = {
        "name": "My Report",
        "mimeType": "application/vnd.google-apps.spreadsheet",
    }
    media = MediaFileUpload("report.csv", mimetype="text/csv", resumable=True)
    # pylint: disable=maybe-no-member
    file = (
        service.files()
        .create(body=file_metadata, media_body=media, fields="id")
        .execute()
    )
    print(f'File with ID: "{file.get("id")}" has been uploaded.')

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

  return file.get("id")


if __name__ == "__main__":
  upload_with_conversion()

Node.js

drive/snippets/drive_v3/file_snippets/upload_with_conversion.js
/**
 * Upload file with conversion
 * @return{obj} file Id
 * */
async function uploadWithConversion() {
  const fs = require('fs');
  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});
  const fileMetadata = {
    name: 'My Report',
    mimeType: 'application/vnd.google-apps.spreadsheet',
  };
  const media = {
    mimeType: 'text/csv',
    body: fs.createReadStream('files/report.csv'),
  };

  try {
    const file = await service.files.create({
      requestBody: fileMetadata,
      media: media,
      fields: 'id',
    });
    console.log('File Id:', file.data.id);
    return file.data.id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveUploadWithConversion.php
use Google\Client;
use Google\Service\Drive;
function uploadWithConversion()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $fileMetadata = new Drive\DriveFile(array(
            'name' => 'My Report',
            'mimeType' => 'application/vnd.google-apps.spreadsheet'));
        $content = file_get_contents('../files/report.csv');
        $file = $driveService->files->create($fileMetadata, array(
            'data' => $content,
            'mimeType' => 'text/csv',
            'uploadType' => 'multipart',
            'fields' => 'id'));
        printf("File ID: %s\n", $file->id);
        return $file->id;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/UploadWithConversion.cs
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate Drive's upload with conversion use-case.
    public class UploadWithConversion
    {
        /// <summary>
        /// Upload file with conversion.
        /// </summary>
        /// <param name="filePath">Id of the spreadsheet file.</param>
        /// <returns>Inserted file id if successful, null otherwise.</returns>
        public static string DriveUploadWithConversion(string filePath)
        {
            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"
                });

                // Upload file My Report on drive.
                var fileMetadata = new Google.Apis.Drive.v3.Data.File()
                {
                    Name = "My Report",
                    MimeType = "application/vnd.google-apps.spreadsheet"
                };
                FilesResource.CreateMediaUpload request;
                // Create a new drive.
                using (var stream = new FileStream(filePath,
                           FileMode.Open))
                {
                    // Create a new file, with metadata and stream.
                    request = service.Files.Create(
                        fileMetadata, stream, "text/csv");
                    request.Fields = "id";
                    request.Upload();
                }

                var file = request.ResponseBody;
                // Prints the uploaded file id.
                Console.WriteLine("File ID: " + file.Id);
                return file.Id;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is FileNotFoundException)
                {
                    Console.WriteLine("File not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

لمعرفة ما إذا كانت الإحالة الناجحة متاحة، راجِع مصفوفة importFormats للمورد about قبل إنشاء الملف. تتوفّر الإحالات الناجحة المتوافقة ديناميكيًا في هذا المصفوفة. في ما يلي بعض التنسيقات الشائعة لاستيراد البيانات:

منإلى
Microsoft Word وOpenDocument Text وHTML وRTF والنص العاديمستندات Google
Microsoft Excel وOpenDocument Spreadsheet وCSV وTSV والنصوص العاديةجداول بيانات Google
Microsoft PowerPoint وOpenDocument Presentationالعروض التقديمية من Google
JPEG أو PNG أو GIF أو BMP أو PDF"مستندات Google" (تُضمِّن الصورة في مستند)
نص عادي (نوع MIME خاص)، JSONلغة برمجة تطبيقات Google

عند تحميل الوسائط وتحويلها أثناء طلب update إلىملف "مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google"، يتم استبدال المحتوى الكامل للمستند.

عند تحويل صورة إلى ملف في "مستندات Google"، يستخدم تطبيق Drive ميزة التعرّف البصري على الأحرف (OCR) لتحويل الصورة إلى نص. يمكنك تحسين جودة خوارزمية التعرّف البصري على الحروف من خلال تحديد رمز لغة BCP 47 الساري في المَعلمة ocrLanguage. يظهر النص المُستخرَج في المستند بجانب الصورة المضمّنة.

استخدام معرّف تم إنشاؤه مسبقًا لتحميل الملفات

تتيح لك Drive API استرداد قائمة بأرقام تعريف الملفات التي تم إنشاؤها مسبقًا والتي تُستخدَم لتحميل الموارد وإنشائها. يمكن أن تستخدم طلبات التحميل وإنشاء الملفات هذه الأرقام التعريفية التي تم إنشاؤها مسبقًا. اضبط الحقل id في البيانات الوصفية للملف.

لإنشاء أرقام تعريف منشأة مسبقًا، يمكنك طلب files.generateIds مع تضمين عدد المعرّفات التي سيتم إنشاؤها.

يمكنك إعادة محاولة عمليات التحميل بأمان باستخدام معرّفات تم إنشاؤها مسبقًا في حال حدوث خطأ أو مهلة غير محدّدة في الخادم. إذا تم إنشاء الملف بنجاح، تعرض المحاولة التالية خطأ HTTP 409 ولا تنشئ ملفات مكرّرة.

تحديد النص القابل للفهرسة لأنواع الملفات غير المعروفة

يمكن للمستخدمين استخدام واجهة مستخدم Drive للعثور على محتوى المستند. يمكنك أيضًا استخدام files.list وحقل fullText للبحث عن محتوى من تطبيقك. لمزيد من المعلومات، اطّلِع على البحث عن الملفات والمجلدات.

يعمل Drive تلقائيًا على فهرسة المستندات للبحث عند التعرّف على نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تحتوي على نص والأنواع الشائعة الأخرى. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات والفيديوهات والاختصارات)، يمكنك تحسين إمكانية العثور عليه من خلال تقديم نص قابل للفهرسة في حقل contentHints.indexableText في الملف.

لمزيد من المعلومات عن النص القابل للفهرسة، يُرجى الاطّلاع على مقالة إدارة metadata للملف.