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

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

يمكنك إجراء 3 أنواع من عمليات التحميل:

  • التحميل البسيط (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) للطريقة /upload باستخدام مَعلمة طلب البحث 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
from __future__ import print_function

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

‫2,999

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/Upload Basic.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. أرسل الطلب الأولي واسترد معرف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.
  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
    

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

  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 للجلسة القابلة للاستئناف لتحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية عنوان URL للجلسة القابلة للاستئناف بعد أسبوع واحد.

  5. انسخ عنوان URL للجلسة القابلة للاستئناف واحفظه.

  6. تابع تحميل المحتوى.

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

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

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

HTTP - طلب واحد

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

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

  1. أنشئ طلب PUT لمعرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.

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

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

    • Content-Length. اضبط عدد وحدات البايت في المقطع الحالي.
    • Content-Range. يتم ضبطه لإظهار وحدات البايت في الملف الذي ستحمّله. على سبيل المثال، تُظهر السمة Content-Range: bytes 0-524287/2000000 أنّك تحمّل أول 524,288 بايت (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، لن يتم تلقّي أي بايت. على سبيل المثال، يشير رأس Range للسمة bytes=0-42 إلى أنّه تم استلام أول 43 بايت من الملف وأنّ المقطع التالي المطلوب تحميله سيبدأ بالبايت 44.

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

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

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

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

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

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

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

يوضّح ما يلي كيفية تحويل ملف 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
from __future__ import print_function

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({
      resource: fileMetadata,
      media: media,
      fields: 'id',
    });
    console.log('File Id:', file.data.id);
    return file.data.id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

‫2,999

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 قبل إنشاء الملف. تتوفّر الإحالات الناجحة المدعومة بشكل ديناميكي في هذه المصفوفة. بعض تنسيقات الاستيراد الشائعة هي:

منإلى
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 إلى مستند أو جدول بيانات أو عرض تقديمي، يتم استبدال المحتوى الكامل للمستند.

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

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

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

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

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

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

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

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

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