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

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

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

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

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

ספריות הלקוח של 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 מסוג Content-Length, שמוגדרת למספר הבייטים בקובץ.
שולחים את הבקשה. אם בקשת ההעלאה הופסקה או התקבלה תגובה 5xx, פועלים לפי התהליך שמתואר במאמר המשך העלאה של הפרעה.

HTTP – בקשות מרובות

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

כדי להמיר קובץ לסוג קובץ ספציפי ב-Google Workspace, צריך לציין את השדה mimeType של Google Workspace כשיוצרים אותו.

בטבלה הבאה מוסבר איך להמיר קובץ CSV לגיליון ב-Google Workspace:

Java

drive/snippets/drive_v3/src/main/java/UploadWithConversion.java

הצגת הקוד ב-GitHub

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

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

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

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

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

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

Python

drive/snippets/drive-v3/file_snippet/upload_with_conversion.py

הצגת הקוד ב-GitHub

import google.auth
from googleapiclient.discovery import build
from googleapiclient.errors import HttpError
from googleapiclient.http import MediaFileUpload


def upload_with_conversion():
  """Upload file with conversion
  Returns: ID of the file uploaded

  Load pre-authorized user credentials from the environment.
  TODO(developer) - See https://developers.google.com/identity
  for guides on implementing OAuth2 for the application.
  """
  creds, _ = google.auth.default()

  try:
    # create drive api client
    service = build("drive", "v3", credentials=creds)

    file_metadata = {
        "name": "My Report",
        "mimeType": "application/vnd.google-apps.spreadsheet",
    }
    media = MediaFileUpload("report.csv", mimetype="text/csv", resumable=True)
    # pylint: disable=maybe-no-member
    file = (
        service.files()
        .create(body=file_metadata, media_body=media, fields="id")
        .execute()
    )
    print(f'File with ID: "{file.get("id")}" has been uploaded.')

  except HttpError as error:
    print(f"An error occurred: {error}")
    file = None

  return file.get("id")


if __name__ == "__main__":
  upload_with_conversion()

Node.js

drive/snippets/drive_v3/file_snippets/upload_with_conversion.js

הצגת הקוד ב-GitHub

/**
 * Upload file with conversion
 * @return{obj} file Id
 * */
async function uploadWithConversion() {
  const fs = require('fs');
  const {GoogleAuth} = require('google-auth-library');
  const {google} = require('googleapis');
  // Get credentials and build service
  // TODO (developer) - Use appropriate auth mechanism for your app
  const auth = new GoogleAuth({
    scopes: 'https://www.googleapis.com/auth/drive',
  });
  const service = google.drive({version: 'v3', auth});
  const fileMetadata = {
    name: 'My Report',
    mimeType: 'application/vnd.google-apps.spreadsheet',
  };
  const media = {
    mimeType: 'text/csv',
    body: fs.createReadStream('files/report.csv'),
  };

  try {
    const file = await service.files.create({
      resource: fileMetadata,
      media: media,
      fields: 'id',
    });
    console.log('File Id:', file.data.id);
    return file.data.id;
  } catch (err) {
    // TODO(developer) - Handle error
    throw err;
  }
}

PHP

drive/snippets/drive_v3/src/DriveUploadWithConversion.php

הצגת הקוד ב-GitHub

use Google\Client;
use Google\Service\Drive;
function uploadWithConversion()
{
    try {
        $client = new Client();
        $client->useApplicationDefaultCredentials();
        $client->addScope(Drive::DRIVE);
        $driveService = new Drive($client);
        $fileMetadata = new Drive\DriveFile(array(
            'name' => 'My Report',
            'mimeType' => 'application/vnd.google-apps.spreadsheet'));
        $content = file_get_contents('../files/report.csv');
        $file = $driveService->files->create($fileMetadata, array(
            'data' => $content,
            'mimeType' => 'text/csv',
            'uploadType' => 'multipart',
            'fields' => 'id'));
        printf("File ID: %s\n", $file->id);
        return $file->id;
    } catch(Exception $e) {
        echo "Error Message: ".$e;
    }

}

‎.NET

drive/snippets/drive_v3/DriveV3Snippets/UploadWithConversion.cs

הצגת הקוד ב-GitHub

using Google.Apis.Auth.OAuth2;
using Google.Apis.Drive.v3;
using Google.Apis.Services;

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

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

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

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

כדי לראות אם יש המרה זמינה, צריך לבדוק את המערך importFormats של המשאב about לפני שיוצרים את הקובץ. ההמרות הנתמכות זמינות באופן דינמי במערך הזה. הנה כמה פורמטים נפוצים של ייבוא:

מאת	אל
Microsoft Word, OpenDocument Text, HTML, RTF, טקסט פשוט	Google Docs
Microsoft Excel, OpenDocument sheets, CSV, TSV, טקסט פשוט	Google Sheets
Microsoft PowerPoint, OpenDocument presentation	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`