تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

تتيح لك 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

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

POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
أضِف بيانات الملف إلى محتوى الطلب.
أضِف رؤوس HTTP التالية:
- Content-Type. اضبطه على نوع وسائط MIME للعنصر الذي يتم uploadه.
- Content-Length. اضبط هذا الخيار على عدد البايتات التي تحمّلها. إذا كنت تستخدِم ترميز نقل مجزّأ، لن يكون هذا العنوان مطلوبًا.
أرسِل الطلب. إذا نجح الطلب، يعرض الخادم رمز الحالة HTTP 200 OK مع البيانات الوصفية للملف. {HTTP}

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

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

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

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

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

Java

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

العرض على GitHub

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

العرض على GitHub

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

العرض على GitHub

/**
 * 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

العرض على GitHub

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

العرض على GitHub

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

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

POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
أنشئ نص الطلب. يجب تنسيق النص وفقًا لنوع المحتوى المتعدّد الأجزاء/المرتبط RFC 2387، والذي يحتوي على جزأين:
- البيانات الوصفية. يجب أن تظهر البيانات الوصفية أولاً وأن يكون لها Content-Type عنوان تم ضبطه على application/json; charset=UTF-8. أضِف البيانات الوصفية للملف بتنسيق JSON.
- الوسائط يجب أن تأتي الوسائط في المرّة الثانية وأن تحتوي على عنوان Content-Type من أي نوع MIME. أضِف بيانات الملف إلى جزء الوسائط.
حدِّد كل جزء باستخدام سلسلة حدودية يسبقها شرطة سفلية مزدوجة. بالإضافة إلى ذلك، أضِف واصلة بعد سلسلة الحدود النهائية.
أضِف عناوين HTTP ذات المستوى الأعلى التالية:
- Content-Type. اضبط القيمة على multipart/related وأدرِج سلسلة الحدود التي تستخدمها لتحديد الأجزاء المختلفة من الطلب. على سبيل المثال: Content-Type: multipart/related; boundary=foo_bar_baz
- Content-Length. يتم ضبطه على إجمالي عدد وحدات البايت في نص الطلب.
أرسِل الطلب.

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

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

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

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

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

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

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

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

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

HTTP

أنشئ طلبًا من النوع 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 للجلسة التي يمكن استئنافها حتى تتمكّن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم لجلسة يمكن استئنافها بعد أسبوع واحد.

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

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

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

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

HTTP - طلب واحد

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

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

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

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

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

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

HTTP

لطلب حالة التحميل، أنشئ طلبًا فارغًا من النوع PUT إلى معرّف الموارد المنتظِم للجلسة التي يمكن استئنافها.
أضِف عنوان Content-Range للإشارة إلى أنّ الموضع الحالي في الملف غير معروف. على سبيل المثال، اضبط Content-Range على */2000000 إذا كان طول الملف الإجمالي هو 2,000,000 بايت. إذا لم تكن تعرف الحجم الكامل للملف، اضبط Content-Range على */*.
أرسِل الطلب.
معالجة الردّ:
- يشير الرمز 200 OK أو 201 Created إلى اكتمال عملية التحميل، وليس من الضروري اتّخاذ أي إجراء آخر.
- يشير الرمز 308 Resume Incomplete إلى أنّه عليك مواصلةتحميل الملف.
- يشير الرمز 404 Not Found إلى انتهاء صلاحية جلسة التحميل ويجب إعادة التحميل من البداية.
إذا تلقّيت استجابة 308 Resume Incomplete، عليك معالجة عنوان Range للاستجابة لتحديد البايتات التي تلقّاها الخادم. إذا لم يتضمّن الردّRange عنوانًا، يعني ذلك أنّه لم يتم استلام أي وحدات بايت. على سبيل المثال، يشير عنوان Range‏bytes=0-42 إلى أنّه تم استلام أول 43 بايت من الملف وأنّ الجزء التالي المطلوب تحميله سيبدأ بالبايت 44.
الآن بعد أن عرفت مكان استئناف التحميل، يمكنك مواصلة تحميل الملف بدءًا من البايت التالي. أدرِج عنوانًا 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

العرض على GitHub

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

العرض على GitHub

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

العرض على GitHub

/**
 * 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

العرض على GitHub

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

العرض على GitHub

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) لتحويل الصورة إلى نص. يمكنك تحسين جودة خوارزمية OCR من خلال تحديد رمز لغة BCP 47 الساري في المَعلمة ocrLanguage. يظهر النص المستخرَج في "مستند Google" بجانب الصورة المضمّنة.

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

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

لإنشاء أرقام تعريف تم إنشاؤها مسبقًا، اتصل برقم files.generateIds مع تحديد عدد أرقام التعريف المطلوب إنشاؤها.

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

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

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

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

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

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

استخدام PATCH مقارنةً بـ PUT

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

HTTP

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

Java

Python

Node.js

PHP

NET.

HTTP

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

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

HTTP

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

HTTP - طلب واحد

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

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

HTTP

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

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

Java

Python

Node.js

PHP

NET.

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

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

استخدام `PATCH` مقارنةً بـ `PUT`