דף זה תורגם על ידי Cloud Translation API.

העלאת נתוני הקובץ

Google Drive API מאפשר להעלות נתוני קבצים כשיוצרים או מעדכנים File לקבלת מידע על האופן שבו ניתן ליצור קובץ מטא-נתונים בלבד, כמו תיקייה, ראו יצירת קבצים של מטא-נתונים בלבד.

יש שלושה סוגי העלאות שאפשר לבצע:

העלאה פשוטה (uploadType=media): השתמשו בסוג ההעלאה הזה כדי להעביר קובץ מדיה קטן (עד 5MB) ללא ציון מטא-נתונים. כדי לבצע להעלאה פשוטה, קראו את המאמר ביצוע העלאה פשוטה.
העלאה מרובת חלקים (uploadType=multipart): "יש להשתמש בסוג ההעלאה הזה כדי להעביר קובץ קטן (עד 5MB) ביחד עם מטא-נתונים שמתארים את בבקשה אחת. כדי לבצע העלאה מרובת חלקים, קראו את המאמר ביצוע העלאה מרובת חלקים.
העלאה שניתן להמשיך (uploadType=resumable): צריך להשתמש בסוג ההעלאה הזה כדי קבצים גדולים (מעל 5MB) וכשיש סיכוי גבוה לרשת הפרעות, למשל, במהלך יצירת קובץ מאפליקציה לנייד. ניתן להמשיך הן גם אפשרות טובה לרוב האפליקציות, כי הן גם פועלות לקבצים קטנים בעלות מינימלית של בקשת HTTP אחת נוספת לכל העלאה. כדי לבצע העלאה שניתן להמשיך, קראו את המאמר ביצוע העלאה שניתן להמשיך upload.

ספריות הלקוח של Google API מטמיעות לפחות אחד מהסוגים הבאים של העלאות. מידע נוסף זמין בספריית הלקוח תיעוד לפרטים נוספים על משתמשים בכל אחד מהסוגים.

שימוש ב-`PATCH` לעומת `PUT`

תזכורת: פועל ה-HTTP PATCH תומך בעדכון חלקי של משאבי קובץ ואילו פועל ה-HTTP PUT תומך בהחלפה מלאה של משאבים. הערה: PUT יכולות לגרום לשינויים שעלולים לגרום לכשל כשמוסיפים שדה חדש למשאב קיים.

כשמעלים משאב של קובץ, יש לפעול לפי ההנחיות הבאות:

משתמשים בפועל HTTP שמתועד בהפניה ל-API עבור הבקשה הראשונית של העלאה שניתן להמשיך או בקשה אחת בלבד של העלאה פשוטה או מרובת חלקים.
בכל הבקשות הבאות להעלאה שניתן להמשיך, צריך להשתמש ב-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 של הסשן שניתן להמשיך.
מוסיפים את נתוני המקטע לגוף הבקשה. יצירת מקטעים בכפולות של גודל של 256KB (256x1,024 בייטים), מלבד המקטע הסופי שמשלים של ההעלאה. חשוב שגודל המקטע יהיה גדול ככל האפשר כדי שההעלאה תהיה יעיל.
מוסיפים את כותרות ה-HTTP הבאות:
- Content-Length מוגדר למספר הבייטים במקטע הנוכחי.
- Content-Range מגדירים את הבייטים בקובץ שמעלים. עבור לדוגמה, Content-Range: bytes 0-524287/2000000 מראה שהעליתם את 524,288 הבייטים הראשונים (256x1,024 x 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 Docs

כשיוצרים קובץ ב-Drive, כדאי להמיר את את הקובץ בסוג קובץ של Google Workspace, כמו Google Docs או גיליונות לדוגמה, אולי תרצו להמיר מסמך את מעבד התמלילים המועדף עליכם ב-Docs כדי לנצל לבינה מלאכותית גנרטיבית.

כדי להמיר קובץ לסוג קובץ ספציפי ב-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 Docs
Microsoft Excel, OpenDocument sheet, CSV, TSV, טקסט פשוט	Google Sheets
Microsoft PowerPoint, OpenDocument מצגת	Google Slides
JPEG, PNG, GIF, BMP, PDF	Google Docs (מטמיע את התמונה במסמך)
טקסט פשוט (סוג MIME מיוחד), JSON	Google Apps Script

כשמעלים וממירים מדיה במהלך בקשת update אל בקובץ Docs, Sheets או Slides, כל התוכן של המסמך יוחלף.

כשממירים תמונה למסמך Docs, מערכת Drive משתמשת זיהוי תווים אופטי (OCR) להמרת התמונה לטקסט. אפשר לשפר את האיכות של אלגוריתם ה-OCR על ידי ציון ה-BCP הרלוונטי קוד שפה 47 ב ocrLanguage הפרמטר. הטקסט שחולץ יופיע במסמך לצד התמונה המוטמעת.

שימוש במזהה שנוצר מראש כדי להעלות קבצים

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 Docs

Java

Python

Node.js

PHP

‎.NET

שימוש במזהה שנוצר מראש כדי להעלות קבצים

הגדרת טקסט שניתן להוסיף לאינדקס לסוגי קבצים לא ידועים

שימוש ב-`PATCH` לעומת `PUT`