Blog : Files: insert

Files: insert


Requires authorization

Insert a new file. Try it now or see an example.

This method supports an /upload URI and accepts uploaded media with the following characteristics:

Maximum file size: 5120GB
Accepted Media MIME types: */*

Note: Apps creating shortcuts with files.insert must specify the MIME type application/vnd.google-apps.drive-sdk.

Apps should specify a file extension in the title property when inserting files with the API. For example, an operation to insert a JPEG file should specify something like "title": "cat.jpg" in the metadata.

Subsequent GET requests include the read-only fileExtension property populated with the extension originally specified in the title property. When a Google Drive user requests to download a file, or when the file is downloaded through the sync client, Drive builds a full filename (with extension) based on the title. In cases where the extension is missing, Google Drive attempts to determine the extension based on the file's MIME type.

Request

HTTP request

This method provides media upload functionality through two separate URIs. For more details, see the document on media upload.

Upload URI, for media upload requests:
POST https://www.googleapis.com/upload/drive/v2/files
Metadata URI, for metadata-only requests:
POST https://www.googleapis.com/drive/v2/files
Parameters

Parameter name   Value   Description
Required query parameters
uploadType   string   The type of upload request to the /upload URI. Acceptable values are:
media - Simple upload. Upload the media only, without any metadata.
multipart - Multipart upload. Upload both the media and its metadata, in a single request.
resumable - Resumable upload. Upload the file in a resumable fashion, using a series of at least two requests where the first request includes the metadata.
Optional query parameters
convert   boolean   Whether to convert this file to the corresponding Google Docs format. (Default: false)
ocr   boolean   Whether to attempt OCR on .jpg, .png, .gif, or .pdf uploads. (Default: false)
ocrLanguage   string   If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes.
pinned   boolean   Whether to pin the head revision of the uploaded file. A file can have a maximum of 200 pinned revisions. (Default: false)
timedTextLanguage   string   The language of the timed text.
timedTextTrackName   string   The timed text track name.
useContentAsIndexableText   boolean   Whether to use the content as indexable text. (Default: false)
visibility   string   The visibility of the new file. This parameter is only relevant when convert=false.

Acceptable values are:
"DEFAULT": The visibility of the new file is determined by the user's default visibility/sharing policies. (default)
"PRIVATE": The new file will be visible to only the owner.
Authorization

This request requires authorization with at least one of the following scopes (read more about authentication and authorization).

Scope
https://www.googleapis.com/auth/drive
https://www.googleapis.com/auth/drive.file
https://www.googleapis.com/auth/drive.appdata
https://www.googleapis.com/auth/drive.apps.readonly
Request body

In the request body, supply a Files resource with the following properties as the metadata. For more information, see the document on media upload.

Property name   Value   Description   Notes
Optional Properties
description   string   A short description of the file.   writable
folderColorRgb   string   Folder color as an RGB hex string if the file is a folder. The list of supported colors is available in the folderColorPalette field of the About resource. If an unsupported color is specified, it will be changed to the closest color in the palette.   writable
indexableText.text   string   The text to be indexed for this file.   writable
labels.hidden   boolean   Deprecated.   writable
labels.restricted   boolean   Whether viewers are prevented from downloading this file.   writable
labels.starred   boolean   Whether this file is starred by the user.   writable
labels.trashed   boolean   Whether this file has been trashed. This label applies to all users accessing the file; however, only owners are allowed to see and untrash files.   writable
labels.viewed   boolean   Whether this file has been viewed by this user.   writable
lastViewedByMeDate   datetime   Last time this file was viewed by the user (formatted RFC 3339 timestamp).   writable
markedViewedByMeDate   datetime   Time this file was explicitly marked viewed by the user (formatted RFC 3339 timestamp).   writable
mimeType   string   The MIME type of the file. This is only mutable on update when uploading new content. This field can be left blank, and the mimetype will be determined from the uploaded content's MIME type.   writable
modifiedDate   datetime   Last time this file was modified by anyone (formatted RFC 3339 timestamp). This is only mutable on update when the setModifiedDate parameter is set.   writable
parents[]   list   Collection of parent folders which contain this file.
Setting this field will put the file in all of the provided folders. On insert, if no folders are provided, the file will be placed in the default root folder.

writable
properties[]   list   The list of properties.   writable
title   string   The title of the file. Used to identify file or folder name.   writable
writersCanShare   boolean   Whether writers can share the document with other users.   writable
Response

If successful, this method returns a Files resource in the response body.

Examples

Note: The code examples available for this method do not represent all supported programming languages (see the client libraries page for a list of supported languages).

Java.NETPHPPythonRubyJavaScriptGoObjective-C
Uses the Java client library.

import com.google.api.client.http.FileContent;
import com.google.api.services.drive.Drive;
import com.google.api.services.drive.model.File;
import com.google.api.services.drive.model.ParentReference;

import java.io.IOException;
import java.util.Arrays;
// ...

public class MyClass {

  // ...

  /**
  * Insert new file.
  *
  * @param service Drive API service instance.
  * @param title Title of the file to insert, including the extension.
  * @param description Description of the file to insert.
  * @param parentId Optional parent folder's ID.
  * @param mimeType MIME type of the file to insert.
  * @param filename Filename of the file to insert.
  * @return Inserted file metadata if successful, {@code null} otherwise.
  */
  private static File insertFile(Drive service, String title, String description,
  String parentId, String mimeType, String filename) {
  // File's metadata.
  File body = new File();
  body.setTitle(title);
  body.setDescription(description);
  body.setMimeType(mimeType);

  // Set the parent folder.
  if (parentId != null && parentId.length() > 0) {
  body.setParents(
  Arrays.asList(new ParentReference().setId(parentId)));
  }

  // File's content.
  java.io.File fileContent = new java.io.File(filename);
  FileContent mediaContent = new FileContent(mimeType, fileContent);
  try {
  File file = service.files().insert(body, mediaContent).execute();

  // Uncomment the following line to print the File ID.
  // System.out.println("File ID: " + file.getId());

  return file;
  } catch (IOException e) {
  System.out.println("An error occured: " + e);
  return null;
  }
  }

  // ...
}
Try it!

Note: APIs Explorer currently supports metadata requests only.

Use the APIs Explorer below to call this method on live data and see the response.

Authorize requests using OAuth 2.0:

convert   
   Whether to convert this file to the corresponding Google Docs format. (boolean)
ocr   
   Whether to attempt OCR on .jpg, .png, .gif, or .pdf uploads. (boolean)
ocrLanguage   
   If ocr is true, hints at the language to use. Valid values are ISO 639-1 codes. (string)
pinned   
   Whether to pin the head revision of the uploaded file. A file can have a maximum of 200 pinned revisions. (boolean)
timedTextLanguage   
   The language of the timed text. (string)
timedTextTrackName   
   The timed text track name. (string)
useContentAsIndexableText   
   Whether to use the content as indexable text. (boolean)
visibility   
   The visibility of the new file. This parameter is only relevant when convert=false. (string)
fields   

Selector specifying which fields to include in a partial response.
Use fields editor
Request body   

{
}