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

إذا نجح طلب البدء، سيتضمّن الردّ 200 OK رمز حالة HTTP. وتتضمّن أيضًا عنوان 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 إلى 2,000,000.

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

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

بالنسبة إلى 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، حدِّد 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"، يستخدم تطبيق 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`