داده های فایل را آپلود کنید

API گوگل درایو به شما امکان می‌دهد هنگام ایجاد یا به‌روزرسانی یک File داده‌های فایل را آپلود کنید. برای اطلاعات بیشتر در مورد نحوه ایجاد یک فایل فقط فراداده، مانند یک پوشه، به بخش ایجاد فایل‌های فقط فراداده مراجعه کنید.

سه نوع آپلود وجود دارد که می‌توانید انجام دهید:

  • آپلود ساده ( uploadType=media ) : از این نوع آپلود برای انتقال یک فایل رسانه‌ای کوچک (۵ مگابایت یا کمتر) بدون ارائه فراداده استفاده کنید. برای انجام آپلود ساده، به انجام آپلود ساده مراجعه کنید.

  • آپلود چندبخشی ( uploadType=multipart ) : "از این نوع آپلود برای انتقال یک فایل کوچک (5 مگابایت یا کمتر) به همراه فراداده‌ای که فایل را توصیف می‌کند، در یک درخواست واحد استفاده کنید. برای انجام آپلود چندبخشی، به انجام آپلود چندبخشی مراجعه کنید."

  • آپلود از سرگیری‌پذیر ( uploadType=resumable ) : از این نوع آپلود برای فایل‌های بزرگ (بزرگتر از ۵ مگابایت) و زمانی که احتمال قطع شبکه زیاد است، مانند هنگام ایجاد فایل از یک برنامه تلفن همراه، استفاده کنید. آپلودهای از سرگیری‌پذیر همچنین انتخاب خوبی برای اکثر برنامه‌ها هستند زیرا برای فایل‌های کوچک نیز با حداقل هزینه یک درخواست HTTP اضافی برای هر آپلود کار می‌کنند. برای انجام آپلود از سرگیری‌پذیر، به انجام آپلود از سرگیری‌پذیر مراجعه کنید.

کتابخانه‌های کلاینت API گوگل حداقل یکی از این نوع آپلودها را پیاده‌سازی می‌کنند. برای جزئیات بیشتر در مورد نحوه استفاده از هر یک از این انواع، به مستندات کتابخانه کلاینت مراجعه کنید.

استفاده از PUT در مقابل PATCH

به عنوان یادآوری، فعل HTTP PATCH از به‌روزرسانی جزئی منبع فایل پشتیبانی می‌کند در حالی که فعل HTTP PUT از جایگزینی کامل منبع پشتیبانی می‌کند. توجه داشته باشید که PUT می‌تواند هنگام اضافه کردن یک فیلد جدید به یک منبع موجود، تغییرات جزئی ایجاد کند.

هنگام آپلود فایل، از دستورالعمل‌های زیر استفاده کنید:

  • برای درخواست اولیه آپلود قابل از سرگیری یا برای تنها درخواست آپلود ساده یا چند قسمتی، از فعل HTTP مستند شده در مرجع API استفاده کنید.
  • PUT برای همه درخواست‌های بعدی برای آپلود قابل از سرگیری پس از شروع درخواست استفاده کنید. این درخواست‌ها صرف نظر از متدی که فراخوانی می‌شود، محتوا را آپلود می‌کنند.

انجام یک آپلود ساده

برای انجام یک آپلود ساده، از متد create روی منبع files با uploadType=media استفاده کنید.

در زیر نحوه انجام یک آپلود ساده نشان داده شده است:

اچ‌تی‌پی

  1. یک درخواست POST به آدرس /upload متد با پارامتر کوئری uploadType=media ایجاد کنید:

    POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media

  2. داده‌های فایل را به بدنه درخواست اضافه کنید.

  3. این هدرهای HTTP را اضافه کنید:

    • Content-Type ): نوع رسانه MIME شیء در حال آپلود را تنظیم می‌کند.
    • Content-Length . روی تعداد بایت‌هایی که آپلود می‌کنید تنظیم می‌شود. اگر از کدگذاری انتقال تکه‌ای (chunked transfer encoding) استفاده می‌کنید، این هدر لازم نیست.
  4. درخواست را ارسال کنید. اگر درخواست موفقیت‌آمیز باشد، سرور کد وضعیت HTTP 200 OK را به همراه فراداده‌های فایل برمی‌گرداند. {HTTP}

وقتی یک آپلود ساده انجام می‌دهید، متادیتای اولیه ایجاد می‌شود و برخی ویژگی‌ها از فایل استنباط می‌شوند، مانند نوع MIME یا modifiedTime . می‌توانید در مواردی که فایل‌های کوچکی دارید و متادیتای فایل مهم نیست، از آپلود ساده استفاده کنید.

انجام آپلود چند قسمتی

درخواست آپلود چندبخشی به شما امکان می‌دهد ابرداده و داده‌ها را در یک درخواست آپلود کنید. اگر داده‌هایی که ارسال می‌کنید به اندازه‌ای کوچک هستند که در صورت قطع اتصال، می‌توان دوباره آنها را به طور کامل آپلود کرد، از این گزینه استفاده کنید.

برای انجام آپلود چندبخشی، از متد create روی منبع files با uploadType=multipart استفاده کنید.

در ادامه نحوه انجام آپلود چند قسمتی نشان داده شده است:

جاوا

‎drive/snippets/drive_v3/src/main/java/UploadBasic.java‎‏
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.FileContent;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/* Class to demonstrate use of Drive insert file API */
public class UploadBasic {

  /**
   * Upload new file.
   *
   * @return Inserted file metadata if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static String uploadBasic() throws IOException {
    // Load pre-authorized user credentials from the environment.
    // TODO(developer) - See https://developers.google.com/identity for
    // guides on implementing OAuth2 for your application.
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();
    // Upload file photo.jpg on drive.
    File fileMetadata = new File();
    fileMetadata.setName("photo.jpg");
    // File's content.
    java.io.File filePath = new java.io.File("files/photo.jpg");
    // Specify media type and file-path for file.
    FileContent mediaContent = new FileContent("image/jpeg", filePath);
    try {
      File file = service.files().create(fileMetadata, mediaContent)
          .setFields("id")
          .execute();
      System.out.println("File ID: " + file.getId());
      return file.getId();
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to upload file: " + e.getDetails());
      throw e;
    }
  }
}

پایتون

‎drive/snippets/drive-v3/file_snippet/upload_basic.py‎‏ ...
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()

نود جی اس

‎drive/snippets/drive_v3/file_snippets/upload_basic.js‎‏
import fs from 'node:fs';
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Uploads a file to Google Drive.
 * @return {Promise<string|null|undefined>} The ID of the uploaded file.
 */
async function uploadBasic() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // The request body for the file to be uploaded.
  const requestBody = {
    name: 'photo.jpg',
    fields: 'id',
  };

  // The media content to be uploaded.
  const media = {
    mimeType: 'image/jpeg',
    body: fs.createReadStream('files/photo.jpg'),
  };

  // Upload the file.
  const file = await service.files.create({
    requestBody,
    media,
  });

  // Print the ID of the uploaded file.
  console.log('File Id:', file.data.id);
  return file.data.id;
}

پی اچ پی

‎drive/snippets/drive_v3/src/DriveUploadBasic.php‎‏
<?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;
    } 

}

دات نت

‎drive/snippets/drive_v3/DriveV3Snippets/UploadBasic.cs‎‏
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate use of Drive insert file API
    public class UploadBasic
    {
        /// <summary>
        /// Upload new file.
        /// </summary>
        /// <param name="filePath">Image path to upload.</param>
        /// <returns>Inserted file metadata if successful, null otherwise.</returns>
        public static string DriveUploadBasic(string filePath)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                // Upload file photo.jpg on drive.
                var fileMetadata = new Google.Apis.Drive.v3.Data.File()
                {
                    Name = "photo.jpg"
                };
                FilesResource.CreateMediaUpload request;
                // Create a new file on drive.
                using (var stream = new FileStream(filePath,
                           FileMode.Open))
                {
                    // Create a new file, with metadata and stream.
                    request = service.Files.Create(
                        fileMetadata, stream, "image/jpeg");
                    request.Fields = "id";
                    request.Upload();
                }

                var file = request.ResponseBody;
                // Prints the uploaded file id.
                Console.WriteLine("File ID: " + file.Id);
                return file.Id;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is FileNotFoundException)
                {
                    Console.WriteLine("File not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

اچ‌تی‌پی

  1. یک درخواست POST به آدرس /upload متد با پارامتر کوئری uploadType=multipart ایجاد کنید:

    POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart

  2. بدنه درخواست را ایجاد کنید. بدنه را مطابق با نوع محتوای چندبخشی/مرتبط RFC 2387 قالب‌بندی کنید، که شامل دو بخش است:

    • فراداده. فراداده باید اول بیاید و باید سرآیند Content-Type header) آن روی application/json; charset=UTF-8 تنظیم شده باشد. فراداده فایل را با فرمت JSON اضافه کنید.
    • رسانه. رسانه باید در جایگاه دوم قرار گیرد و باید دارای سرآیند Content-Type از هر نوع MIME باشد. داده‌های فایل را به بخش رسانه اضافه کنید.

    هر بخش را با یک رشته مرزی مشخص کنید که قبل از آن دو خط تیره قرار دارد. علاوه بر این، دو خط تیره بعد از آخرین رشته مرزی اضافه کنید.

  3. این هدرهای HTTP سطح بالا را اضافه کنید:

    • Content-Type . روی multipart/related تنظیم کنید و رشته مرزی (boundary string) که برای شناسایی بخش‌های مختلف درخواست استفاده می‌کنید را نیز در آن قرار دهید. برای مثال: Content-Type: multipart/related; boundary=foo_bar_baz
    • Content-Length . تعداد کل بایت‌های موجود در بدنه درخواست را تنظیم می‌کند.
  4. درخواست را ارسال کنید.

برای ایجاد یا به‌روزرسانی بخش فراداده، بدون داده‌های مرتبط، یک درخواست POST یا PATCH به نقطه پایانی منبع استاندارد ارسال کنید: https://www.googleapis.com/drive/v3/files اگر درخواست موفقیت‌آمیز باشد، سرور کد وضعیت HTTP 200 OK را به همراه فراداده فایل برمی‌گرداند.

هنگام ایجاد فایل‌ها، باید پسوند فایل را در فیلد name فایل مشخص کنید. برای مثال، هنگام ایجاد یک فایل JPEG عکس، می‌توانید چیزی شبیه به "name": "photo.jpg" را در متادیتا مشخص کنید. فراخوانی‌های بعدی به متد get ، خاصیت fileExtension فقط خواندنی را برمی‌گرداند که حاوی پسوندی است که در ابتدا در فیلد name مشخص شده است.

انجام آپلود با قابلیت از سرگیری

آپلود قابل از سرگیری به شما امکان می‌دهد عملیات آپلود را پس از قطع شدن جریان داده‌ها به دلیل قطع ارتباط، از سر بگیرید. از آنجا که لازم نیست آپلود فایل‌های بزرگ را از ابتدا دوباره شروع کنید، آپلودهای قابل از سرگیری می‌توانند در صورت بروز مشکل در شبکه، استفاده از پهنای باند شما را نیز کاهش دهند.

آپلودهای قابل از سرگیری زمانی مفید هستند که اندازه فایل‌های شما ممکن است بسیار متفاوت باشد یا زمانی که محدودیت زمانی ثابتی برای درخواست‌ها وجود دارد (مانند وظایف پس‌زمینه سیستم عامل موبایل و درخواست‌های خاص موتور برنامه). همچنین می‌توانید از آپلودهای قابل از سرگیری برای موقعیت‌هایی که می‌خواهید نوار پیشرفت آپلود را نشان دهید، استفاده کنید.

آپلود قابل از سرگیری شامل چندین مرحله سطح بالا است:

  1. درخواست اولیه را ارسال کنید و URI جلسه قابل از سرگیری را بازیابی کنید.
  2. داده‌ها را آپلود کنید و وضعیت آپلود را زیر نظر داشته باشید.
  3. (اختیاری) اگر آپلود با مشکل مواجه شد، آپلود را از سر بگیرید.

ارسال درخواست اولیه

برای شروع آپلود با قابلیت از سرگیری، از متد create روی منبع files با uploadType=resumable استفاده کنید.

اچ‌تی‌پی

  1. یک درخواست POST به آدرس /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) جلسه قابل از سرگیری پس از یک هفته منقضی می‌شود.

  2. اگر برای فایل، متادیتا دارید، آن را با فرمت JSON به بدنه درخواست اضافه کنید. در غیر این صورت، بدنه درخواست را خالی بگذارید.

  3. این هدرهای HTTP را اضافه کنید:

    • X-Upload-Content-Type . اختیاری. نوع MIME داده‌های فایل را که در درخواست‌های بعدی منتقل می‌شوند، تنظیم می‌کند. اگر نوع MIME داده‌ها در متادیتا یا از طریق این هدر مشخص نشده باشد، شیء به صورت application/octet-stream.
    • X-Upload-Content-Length . اختیاری. روی تعداد بایت‌های داده فایل که در درخواست‌های بعدی منتقل می‌شوند، تنظیم می‌شود.
    • Content-Type . اگر برای فایل، فراداده (metadata) دارید، الزامی است. روی application/json; charset=UTF-8 تنظیم کنید.
    • Content-Length . مگر اینکه از کدگذاری انتقال تکه‌ای استفاده کنید، الزامی است. روی تعداد بایت‌های موجود در بدنه این درخواست اولیه تنظیم کنید.
  4. درخواست را ارسال کنید. اگر درخواست شروع جلسه موفقیت‌آمیز باشد، پاسخ شامل یک کد وضعیت 200 OK HTTP . علاوه بر این، پاسخ شامل یک هدر Location است که URI جلسه قابل از سرگیری را مشخص می‌کند. از URI جلسه قابل از سرگیری برای آپلود داده‌های فایل و پرس و جو در مورد وضعیت آپلود استفاده کنید. URI جلسه قابل از سرگیری پس از یک هفته منقضی می‌شود.

  5. آدرس اینترنتی (URL) جلسه قابل از سرگیری را کپی و ذخیره کنید.

  6. به بارگذاری محتوا ادامه دهید.

محتوا را بارگذاری کنید

دو روش برای آپلود فایل با قابلیت از سرگیری جلسه وجود دارد:

  • بارگذاری محتوا در یک درخواست واحد : زمانی از این رویکرد استفاده کنید که فایل بتواند در یک درخواست بارگذاری شود، محدودیت زمانی ثابتی برای هر درخواست واحد وجود نداشته باشد، یا نیازی به نمایش نشانگر پیشرفت بارگذاری نداشته باشید. این رویکرد بهترین گزینه است زیرا به درخواست‌های کمتری نیاز دارد و منجر به عملکرد بهتری می‌شود.
  • محتوا را در چند بخش بارگذاری کنید : اگر باید میزان داده‌های منتقل شده در هر درخواست واحد را کاهش دهید، از این رویکرد استفاده کنید. ممکن است لازم باشد داده‌های منتقل شده را کاهش دهید، زمانی که محدودیت زمانی ثابتی برای درخواست‌های فردی وجود دارد، همانطور که می‌تواند برای دسته‌های خاصی از درخواست‌های App Engine اتفاق بیفتد. این رویکرد همچنین در صورتی مفید است که باید یک نشانگر سفارشی برای نشان دادن پیشرفت بارگذاری ارائه دهید.

HTTP - درخواست واحد

  1. یک درخواست PUT به آدرس URL قابل از سرگیری جلسه ایجاد کنید.
  2. داده‌های فایل را به بدنه درخواست اضافه کنید.
  3. یک هدر HTTP با طول محتوا (Content-Length) اضافه کنید که روی تعداد بایت‌های موجود در فایل تنظیم شده باشد.
  4. درخواست را ارسال کنید. اگر درخواست آپلود قطع شد، یا اگر پاسخ 5xx دریافت کردید، روش موجود در «از سرگیری آپلود قطع شده» را دنبال کنید.

HTTP - درخواست‌های چندگانه

  1. یک درخواست PUT به آدرس URL قابل از سرگیری جلسه ایجاد کنید.

  2. داده‌های تکه را به بدنه درخواست اضافه کنید. تکه‌هایی با اندازه مضربی از ۲۵۶ کیلوبایت (۲۵۶ × ۱۰۲۴ بایت) ایجاد کنید، به جز تکه آخر که آپلود را کامل می‌کند. اندازه تکه را تا حد امکان بزرگ نگه دارید تا آپلود کارآمد باشد.

  3. این هدرهای HTTP را اضافه کنید:

    • Content-Length . تعداد بایت‌های موجود در قطعه فعلی را تنظیم می‌کند.
    • Content-Range ). این گزینه را تنظیم کنید تا نشان دهد کدام بایت‌ها در فایلی که آپلود می‌کنید وجود دارد. برای مثال، Content-Range: bytes 0-524287/2000000 نشان می‌دهد که شما 524,288 بایت اول (256 x 1024 x 2) را در یک فایل 2,000,000 بایتی آپلود می‌کنید.
  4. درخواست را ارسال کنید و پاسخ را پردازش کنید. اگر درخواست آپلود قطع شد، یا اگر پاسخی با طول 5xx دریافت کردید، روش موجود در «از سرگیری آپلود قطع شده» را دنبال کنید.

  5. مراحل ۱ تا ۴ را برای هر تکه‌ای که در فایل باقی مانده است تکرار کنید. از سرآیند Range در پاسخ برای تعیین محل شروع تکه بعدی استفاده کنید. فرض نکنید که سرور تمام بایت‌های ارسال شده در درخواست قبلی را دریافت کرده است.

وقتی کل آپلود فایل کامل شد، شما یک پاسخ 200 OK یا 201 Created به همراه هرگونه فراداده مرتبط با منبع دریافت می‌کنید.

از سرگیری آپلود متوقف شده

اگر درخواست آپلود قبل از دریافت پاسخ خاتمه یابد، یا اگر خطای 503 Service Unavailable را دریافت کنید، باید آپلود متوقف شده را از سر بگیرید.

اچ‌تی‌پی

  1. برای درخواست وضعیت آپلود، یک درخواست PUT خالی به URI جلسه قابل از سرگیری ایجاد کنید.

  2. یک سربرگ Content-Range اضافه کنید تا نشان دهد موقعیت فعلی در فایل ناشناخته است. برای مثال، اگر طول کل فایل شما ۲،۰۰۰،۰۰۰ بایت است Content-Range را روی */2000000 تنظیم کنید. اگر اندازه کامل فایل را نمی‌دانید، Content-Range روی */* تنظیم کنید.

  3. درخواست را ارسال کنید.

  4. پردازش پاسخ:

    • پاسخ 200 OK یا 201 Created نشان می‌دهد که آپلود با موفقیت انجام شده است و هیچ اقدام دیگری لازم نیست.
    • پاسخ 308 Resume Incomplete نشان می‌دهد که شما باید به آپلود فایل ادامه دهید.
    • خطای 404 Not Found نشان می‌دهد که جلسه آپلود منقضی شده است و آپلود باید از ابتدا دوباره شروع شود.
  5. اگر پاسخ 308 Resume Incomplete دریافت کردید، سرآیند Range پاسخ را پردازش کنید تا مشخص شود سرور کدام بایت‌ها را دریافت کرده است. اگر پاسخ سرآیند Range نداشته باشد، هیچ بایتی دریافت نشده است. برای مثال، سرآیند Range bytes=0-42 نشان می‌دهد که 43 بایت اول فایل دریافت شده است و بخش بعدی برای آپلود با بایت 44 شروع می‌شود.

  6. حالا که می‌دانید آپلود را از کجا از سر بگیرید، آپلود فایل را از بایت بعدی شروع کنید. یک سربرگ Content-Range اضافه کنید تا مشخص شود کدام بخش از فایل را ارسال می‌کنید. برای مثال، Content-Range: bytes 43-1999999 نشان می‌دهد که شما بایت‌های ۴۴ تا ۲۰۰۰۰۰۰ را ارسال می‌کنید.

مدیریت خطاهای آپلود رسانه

هنگام آپلود رسانه، برای مدیریت خطاها، این بهترین شیوه‌ها را دنبال کنید:

  • برای خطاهای 5xx ، آپلودهایی که به دلیل قطع اتصال با شکست مواجه می‌شوند را از سر بگیرید یا دوباره امتحان کنید. برای اطلاعات بیشتر در مورد مدیریت خطاهای 5xx ، به خطاهای 500، 502، 503، 504 مراجعه کنید.
  • برای خطاهای 403 rate limit ، آپلود را دوباره امتحان کنید. برای اطلاعات بیشتر در مورد مدیریت خطاهای 403 rate limit ، به خطای ۴۰۳: rateLimitExceeded مراجعه کنید.
  • برای هرگونه خطای 4xx (از جمله 403 ) در طول آپلود قابل از سرگیری، آپلود را مجدداً راه‌اندازی کنید. این خطاها نشان می‌دهند که جلسه آپلود منقضی شده است و باید با درخواست یک URI جلسه جدید مجدداً راه‌اندازی شود. جلسات آپلود نیز پس از یک هفته عدم فعالیت منقضی می‌شوند.

انواع داده را به Google Docs وارد کنید

وقتی فایلی را در درایو ایجاد می‌کنید، ممکن است بخواهید آن را به یک نوع فایل Google Workspace مانند Google Docs یا Sheets تبدیل کنید. به عنوان مثال، شاید بخواهید یک سند را از پردازشگر متن مورد علاقه خود به Docs تبدیل کنید تا از ویژگی‌های آن بهره‌مند شوید.

برای تبدیل یک فایل به یک نوع فایل خاص Google Workspace، هنگام ایجاد فایل، mimeType Google Workspace را مشخص کنید.

در ادامه نحوه تبدیل فایل CSV به برگه Google Workspace نشان داده شده است:

جاوا

‎drive/snippets/drive_v3/src/main/java/UploadWithConversion.java‎‏
import com.google.api.client.googleapis.json.GoogleJsonResponseException;
import com.google.api.client.http.FileContent;
import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.DriveScopes;
import com.google.api.services.drive.model.File;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;
import java.io.IOException;
import java.util.Arrays;

/* Class to demonstrate Drive's upload with conversion use-case. */
public class UploadWithConversion {

  /**
   * Upload file with conversion.
   *
   * @return Inserted file id if successful, {@code null} otherwise.
   * @throws IOException if service account credentials file not found.
   */
  public static String uploadWithConversion() throws IOException {
    // Load pre-authorized user credentials from the environment.
    // TODO(developer) - See https://developers.google.com/identity for
    // guides on implementing OAuth2 for your application.
    GoogleCredentials credentials = GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList(DriveScopes.DRIVE_FILE));
    HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(
        credentials);

    // Build a new authorized API client service.
    Drive service = new Drive.Builder(new NetHttpTransport(),
        GsonFactory.getDefaultInstance(),
        requestInitializer)
        .setApplicationName("Drive samples")
        .build();

    // File's metadata.
    File fileMetadata = new File();
    fileMetadata.setName("My Report");
    fileMetadata.setMimeType("application/vnd.google-apps.spreadsheet");

    java.io.File filePath = new java.io.File("files/report.csv");
    FileContent mediaContent = new FileContent("text/csv", filePath);
    try {
      File file = service.files().create(fileMetadata, mediaContent)
          .setFields("id")
          .execute();
      System.out.println("File ID: " + file.getId());
      return file.getId();
    } catch (GoogleJsonResponseException e) {
      // TODO(developer) - handle error appropriately
      System.err.println("Unable to move file: " + e.getDetails());
      throw e;
    }
  }
}

پایتون

‎drive/snippets/drive-v3/file_snippet/upload_with_conversion.py‎‏ (درایو/قطعه قطعه/درایو-v3/فایل_قطعه/آپلود_با_تبدیل.پی)‎‏
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()

نود جی اس

‎drive/snippets/drive_v3/file_snippets/upload_with_conversion.js‎‏
import fs from 'node:fs';
import {GoogleAuth} from 'google-auth-library';
import {google} from 'googleapis';

/**
 * Uploads a file to Google Drive and converts it to a Google Sheet.
 * @return {Promise<string|null|undefined>} The ID of the uploaded file.
 */
async function uploadWithConversion() {
  // Authenticate with Google and get an authorized client.
  // TODO (developer): Use an appropriate auth mechanism for your app.
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });

  // Create a new Drive API client (v3).
  const service = google.drive({version: 'v3', auth});

  // The metadata for the file to be uploaded and converted.
  const fileMetadata = {
    name: 'My Report',
    // The MIME type to convert the file to.
    mimeType: 'application/vnd.google-apps.spreadsheet',
  };

  // The media content to be uploaded.
  const media = {
    mimeType: 'text/csv',
    body: fs.createReadStream('files/report.csv'),
  };

  // Upload the file with conversion.
  const file = await service.files.create({
    requestBody: fileMetadata,
    media,
    fields: 'id',
  });

  // Print the ID of the uploaded file.
  console.log('File Id:', file.data.id);
  return file.data.id;
}

پی اچ پی

‎drive/snippets/drive_v3/src/DriveUploadWithConversion.php‎‏
<?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;
    }

}

دات نت

‎drive/snippets/drive_v3/DriveV3Snippets/UploadWithConversion.cs‎‏
using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

namespace DriveV3Snippets
{
    // Class to demonstrate Drive's upload with conversion use-case.
    public class UploadWithConversion
    {
        /// <summary>
        /// Upload file with conversion.
        /// </summary>
        /// <param name="filePath">Id of the spreadsheet file.</param>
        /// <returns>Inserted file id if successful, null otherwise.</returns>
        public static string DriveUploadWithConversion(string filePath)
        {
            try
            {
                /* Load pre-authorized user credentials from the environment.
                 TODO(developer) - See https://developers.google.com/identity for
                 guides on implementing OAuth2 for your application. */
                GoogleCredential credential = GoogleCredential.GetApplicationDefault()
                    .CreateScoped(DriveService.Scope.Drive);

                // Create Drive API service.
                var service = new DriveService(new BaseClientService.Initializer
                {
                    HttpClientInitializer = credential,
                    ApplicationName = "Drive API Snippets"
                });

                // Upload file My Report on drive.
                var fileMetadata = new Google.Apis.Drive.v3.Data.File()
                {
                    Name = "My Report",
                    MimeType = "application/vnd.google-apps.spreadsheet"
                };
                FilesResource.CreateMediaUpload request;
                // Create a new drive.
                using (var stream = new FileStream(filePath,
                           FileMode.Open))
                {
                    // Create a new file, with metadata and stream.
                    request = service.Files.Create(
                        fileMetadata, stream, "text/csv");
                    request.Fields = "id";
                    request.Upload();
                }

                var file = request.ResponseBody;
                // Prints the uploaded file id.
                Console.WriteLine("File ID: " + file.Id);
                return file.Id;
            }
            catch (Exception e)
            {
                // TODO(developer) - handle error appropriately
                if (e is AggregateException)
                {
                    Console.WriteLine("Credential Not found");
                }
                else if (e is FileNotFoundException)
                {
                    Console.WriteLine("File not found");
                }
                else
                {
                    throw;
                }
            }
            return null;
        }
    }
}

برای بررسی اینکه آیا تبدیلی در دسترس است یا خیر، قبل از ایجاد فایل، فیلد importFormats از منبع about را بررسی کنید. تبدیل‌های پشتیبانی‌شده به‌صورت پویا در این آرایه در دسترس هستند. برخی از قالب‌های رایج برای وارد کردن عبارتند از:

از به
مایکروسافت ورد، متن سند باز، HTML، RTF، متن ساده اسناد گوگل
مایکروسافت اکسل، صفحه گسترده OpenDocument، CSV، TSV، متن ساده صفحات گوگل
مایکروسافت پاورپوینت، ارائه متن باز اسلایدهای گوگل
JPEG، PNG، GIF، BMP، PDF اسناد گوگل (تصویر را در یک سند جاسازی می‌کند)
متن ساده (نوع MIME ویژه)، JSON اسکریپت برنامه‌های گوگل

وقتی در طول درخواست update ، رسانه را آپلود و به فایل Docs، Sheets یا Slides تبدیل می‌کنید، کل محتوای سند جایگزین می‌شود.

وقتی تصویری را به سند تبدیل می‌کنید، درایو از تشخیص نوری کاراکتر (OCR) برای تبدیل تصویر به متن استفاده می‌کند. می‌توانید کیفیت الگوریتم OCR را با مشخص کردن کد زبان BCP 47 مربوطه در پارامتر ocrLanguage بهبود بخشید. متن استخراج شده در سند در کنار تصویر جاسازی شده ظاهر می‌شود.

برای آپلود فایل‌ها از یک شناسه از پیش تولید شده استفاده کنید

رابط برنامه‌نویسی کاربردی درایو (Drive API) به شما امکان می‌دهد فهرستی از شناسه‌های فایل از پیش تولید شده را بازیابی کنید که می‌توانند برای ایجاد، کپی و آپلود منابع استفاده شوند. برای اطلاعات بیشتر، به بخش «شناسه‌های تولید شده برای استفاده با فایل‌هایتان» مراجعه کنید.

در صورت بروز خطای نامشخص سرور یا اتمام زمان، می‌توانید با خیال راحت آپلودها را با شناسه‌های از پیش تولید شده دوباره امتحان کنید. اگر عملیات فایل موفقیت‌آمیز باشد، تلاش‌های بعدی با کد وضعیت HTTP 409 Conflict مواجه می‌شوند و فایل‌های تکراری ایجاد نمی‌شوند.

توجه داشته باشید که شناسه‌های از پیش تولید شده برای ایجاد فایل‌های Google Workspace پشتیبانی نمی‌شوند، به جز انواع MIME مربوط به application/vnd.google-apps.drive-sdk و application/vnd.google-apps.folder . به طور مشابه، آپلودهایی که به تبدیل به فرمت فایل Google Workspace اشاره می‌کنند، پشتیبانی نمی‌شوند.

تعریف متن قابل فهرست‌بندی برای انواع فایل‌های ناشناخته

کاربران می‌توانند از رابط کاربری Drive برای یافتن محتوای سند استفاده کنند. همچنین می‌توانید از متد list در منبع files و فیلد fullText برای جستجوی محتوا از برنامه خود استفاده کنید. برای اطلاعات بیشتر، به بخش «جستجوی فایل‌ها و پوشه‌ها» مراجعه کنید.

درایو به طور خودکار اسناد را برای جستجو فهرست می‌کند وقتی نوع فایل، از جمله اسناد متنی، PDFها، تصاویر دارای متن و سایر انواع رایج را تشخیص دهد. اگر برنامه شما انواع دیگری از فایل‌ها (مانند نقاشی‌ها، ویدیو و میانبرها) را ذخیره می‌کند، می‌توانید با ارائه متن قابل فهرست‌بندی در فیلد contentHints.indexableText فایل، قابلیت کشف آن را بهبود بخشید.

برای اطلاعات بیشتر در مورد متن قابل فهرست‌بندی، به مدیریت فراداده فایل مراجعه کنید.