تمت ترجمة هذه الصفحة بواسطة 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

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

}

NET.

drive/snippets/drive_v3/DriveV3Snippets/UploadBasic.cs

عرض على 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
أنشئ نص الطلب. يجب تنسيق النص الأساسي وفقًا لنوع المحتوى multipart/related 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) الخاص بالجلسة القابلة للاستئناف حتى تتمكّن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم (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) الخاص بالجلسة القابلة للاستئناف.
أضِف بيانات الملف إلى نص الطلب.
أضِف عنوان Content-Length 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 فارغًا إلى معرّف الموارد المنتظم الخاص بالجلسة القابلة للاستئناف.
أضِف العنوان 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، حدِّد 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({
      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

<?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

عرض على 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	العروض التقديمية من Google
‫JPEG أو PNG أو GIF أو BMP أو PDF	مستندات Google (تضمين الصورة في مستند)
نص عادي (نوع MIME خاص)، JSON	لغة برمجة تطبيقات Google

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

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

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

تتيح لك Drive API استرداد قائمة بمعرّفات الملفات التي تم إنشاؤها مسبقًا والتي تُستخدم لتحميل الموارد وإنشائها. يمكن أن تستخدم طلبات التحميل وإنشاء الملفات هذه المعرّفات التي تم إنشاؤها مسبقًا. اضبط الحقل 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`