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

<?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;
    } 

}

‎.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
יוצרים את גוף הבקשה. הפורמט של הגוף צריך להיות תואם לסוג התוכן multipart/related 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 של הסשן שניתן להמשיך.
מוסיפים את נתוני החלק לגוף הבקשה. יוצרים מקטעים בגודל של כפולה של ‎256KB (כלומר, ‎256x1024 בייטים), למעט המקטע האחרון שמשלים את ההעלאה. כדאי להגדיר את גודל החלקים לגדול ככל האפשר כדי שההעלאה תהיה יעילה.
מוסיפים את כותרות ה-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 כדי לציין שהמיקום הנוכחי בקובץ לא ידוע. לדוגמה, אם האורך הכולל של הקובץ הוא 2,000,000 בייטים, צריך להגדיר את הערך Content-Range ל-*/2000000. אם לא יודעים מה הגודל המלא של הקובץ, צריך להגדיר את 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

<?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;
    }

}

‎.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 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`