דף זה תורגם על ידי 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

אם בקשת ההתחלה תתבצע בהצלחה, התשובה תכלול קוד סטטוס HTTP‏ 200 OK. בנוסף, היא כוללת כותרת Location שמציינת את ה-URI של הסשן שניתן להמשיך:
```
HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0
```
שומרים את ה-URI של הסשן שניתן להמשיך כדי שתוכלו להעלות את נתוני הקובץ ולבצע שאילתה לגבי סטטוס ההעלאה. התוקף של ה-URI של סשן שניתן להמשיך יפוג אחרי שבוע.

הערה: כדי לעדכן קובץ קיים, משתמשים ב-PUT.
אם יש לכם מטא-נתונים של הקובץ, מוסיפים את המטא-נתונים לגוף הבקשה בפורמט JSON. אחרת, משאירים את גוף הבקשה ריק.
מוסיפים את כותרות ה-HTTP הבאות:
- X-Upload-Content-Type. אופציונלי. מוגדר לסוג ה-MIME של נתוני הקובץ, שמועברים בבקשות הבאות. אם סוג ה-MIME של הנתונים לא מצוין במטא-נתונים או דרך הכותרת הזו, האובייקט מוצג כ-application/octet-stream.
- X-Upload-Content-Length. אופציונלי. הערך מוגדר למספר הבייטים של נתוני הקובץ, שמועבר בבקשות הבאות.
- Content-Type. חובה אם יש לכם מטא-נתונים לקובץ. מגדירים את הערך application/json; charset=UTF-8.
- Content-Length. חובה, אלא אם משתמשים בקידוד של מקטעים בהעברה. הערך מוגדר למספר הבייטים בגוף הבקשה הראשונית.
שולחים את הבקשה. אם הבקשה להפעלת הסשן מצליחה, התשובה תכלול קוד סטטוס 200 OK HTTP. בנוסף, התשובה כוללת כותרת Location שמציינת את ה-URI של הסשן שניתן להמשיך. משתמשים ב-URI של הסשן שניתן להמשיך כדי להעלות את נתוני הקובץ ולשלוח שאילתות לגבי סטטוס ההעלאה. התוקף של ה-URI של סשן שניתן להמשיך יפוג אחרי שבוע.
מעתיקים ושומרים את כתובת ה-URL של הסשן שניתן להמשיך.
ממשיכים אל העלאת התוכן.

מעלים את התוכן

יש שתי דרכים להעלות קובץ עם סשן שניתן להמשיך:

העלאת תוכן בבקשה אחת: כדאי להשתמש בגישה הזו אם אפשר להעלות את הקובץ בבקשה אחת, אם אין מגבלת זמן קבועה לבקשה אחת או אם אין צורך להציג אינדיקטור של התקדמות ההעלאה. הגישה הזו היא הטובה ביותר כי היא דורשת פחות בקשות ומניבה ביצועים טובים יותר.
העלאת התוכן במספר מקטעים: כדאי להשתמש בגישה הזו אם צריכים להפחית את כמות הנתונים שמועברת בבקשה אחת. יכול להיות שתצטרכו לצמצם את נפח הנתונים המועברים אם יש מגבלה זמן קבועה לבקשות ספציפיות, כמו במקרים של סיווגים מסוימים של בקשות ב-App Engine. הגישה הזו שימושית גם אם אתם צריכים לספק מדד מותאם אישית כדי להציג את התקדמות ההעלאה.

HTTP – בקשה יחידה

יוצרים בקשת PUT ל-URI של הסשן שניתן להמשיך.
מוסיפים את נתוני הקובץ לגוף הבקשה.
מוסיפים כותרת HTTP באורך התוכן, המוגדרת למספר הבייטים בקובץ.
שולחים את הבקשה. אם בקשת ההעלאה הופסקה או אם מקבלים תשובה מסוג 5xx, אפשר להיעזר בהוראות שבקטע המשך של העלאה שהופסקה.

HTTP – מספר בקשות

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