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

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

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

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

لبدء عملية تحميل قابلة للاستئناف، استخدِم طريقة 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 للجلسة القابل للاستئناف حتى تتمكن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف بعد أسبوع واحد.

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

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

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

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

HTTP - طلب واحد

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

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

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

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

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

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

HTTP

لطلب حالة التحميل، أنشِئ طلب PUT فارغًا لمعرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.
أضِف عنوان 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 إلى 2000000.

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

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

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

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

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

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

يوضّح ما يلي كيفية تحويل ملف 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({
      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;
  }
}

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. يظهر النص المُستخرَج في المستند بجانب الصورة المضمّنة.

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

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

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

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

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

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

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

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

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

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

نفِّذ عملية تحميل بسيطة

HTTP

إجراء تحميل متعدد الأجزاء

Java

Python

Node.js

PHP

NET.

HTTP

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

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

HTTP

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

HTTP - طلب واحد

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

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

HTTP

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

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

Java

Python

Node.js

PHP

NET.

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

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

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