File object

Article
03/30/2015

The File object contains info about a user's files in Microsoft OneDrive.

The Live SDK REST API supports creating, reading, updating, and deleting File objects.

Use the wl.skydrive scope to read File objects. Use the wl.contacts_skydrive scope to read any files that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete File objects.

Valid object paths

/FILE_ID

A File object can be returned as part of /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared, /me/skydrive/shared/files, or /USER_ID/skydrive/files.

Structures

The File object contains the following structures.

Structure	Type	R/W	Description
data	array	R	An array of File objects, if a collection of objects is returned.
id	string	R	The File object's ID.
from	object	R	Info about the user who uploaded the file.
name (from object)	string	R	The name of the user who uploaded the file.
id (from object)	string	R	The ID of the user who uploaded the file.
name	string	RW	The name of the file. Required.
description	string/null	RW	A description of the file, or null if no description is specified.
parent_id	string	R	The ID of the folder the file is currently stored in.
size	number	R	The size, in bytes, of the file.
upload_location	string	R	The URL to upload file content hosted in OneDrive. Note that this structure is not available if the file is an Office OneNote notebook.
comments_count	number	R	The number of comments that are associated with the file.
comments_enabled	true/false	R	A value that indicates whether comments are enabled for the file. If comments can be made, this value is true; otherwise, it is false.
is_embeddable	true/false	R	A value that indicates whether this file can be embedded. If this file can be embedded, this value is true; otherwise, it is false.
source	string	R	The URL to use to download the file from OneDrive. Important: This value is not persistent. Use it immediately after making the request, and avoid caching. This structure is not available if the file is an Office OneNote notebook.
link	string	R	A URL to view the item on OneDrive.
type	string	R	The type of object; in this case, "file". Note that if the file is a Office OneNote notebook, the structure is set to "notebook".
shared_with	object	R	Object that contains permission info.
access (shared_with object)	string	R	Info about who can access the file. The options are: People I selected, Just me, Everyone (public), Friends, My friends and their friends, and People with a link. The default is Just me.
created_time	string	R	The time, in ISO 8601 format, at which the file was created.
updated_time	string	R	The time, in ISO 8601 format, that the system updated the file last.
client_updated_time	string	R	The time, in ISO 8601 format, that the client machine updated the file last.
sort_by	string	RW	Sorts the items to specify the following criteria: updated, name, size, or default.

Examples

The following is an example of a File object.

{
   "data": [
      {
         "id": "file.22688711f5410e6c.22688711F5410E6C!942", 
         "from": {
            "name": "William Flash", 
            "id": "22688711f5410e6c"
         }, 
         "name": "Processing.docx", 
         "description": null, 
         "parent_id": "folder.22688711f5410e6c.22688711F5410E6C!479", 
         "size": 12692, 
         "upload_location": "https://apis.live.net/v5.0/file.22688711f5410e6c.22688711F5410E6C!942/content/", 
         "comments_count": 0, 
         "comments_enabled": true, 
         "is_embeddable": false, 
         "source": "http://storage.live.com/s1pEwo9qzyT4_BJZqMNm-aVzgLo-WRsQGzjzFsXjyREuQG5pDYr237vKz3i2pmqFuniYPzsuIZAOCUMB_gdfKCUpLpVcaAMXGrk4T7jOWenRniCv9vex7GWfSvy-XCVBVnU/Processing.docx:Binary", 
         "link": "https://skydrive-df.live.com/redir.aspx?cid\u003d22688711f5410e6c\u0026page\u003dview\u0026resid\u003d22688711F5410E6C!942\u0026parid\u003d22688711F5410E6C!479", 
         "type": "file", 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2011-10-12T23:18:23+0000", 
         "updated_time": "2011-10-12T23:18:23+0000"
      },{
         ...
      }
   ]
}

To get properties for a File resource, make a GET request to /FILE_ID (the target file ID).

To download the content of a File resource, make a GET request to/FILE_ID/content. The file content is returned in the response body.

Note

You can instruct the user's web browser to prompt the user to save the file that's being downloaded instead of having the web browser try to download and display the file directly in the browser. To do this, add the download=true query parameter after /content (for example, FILE_ID/content?download=true). The download=true query parameter works for all calls related to OneDrive that redirect to content or to returning URLs that point to content. For example, FOLDER_ID/files?download=true causes all source and thumbnail URLs in the response to be treated also as download links when they are used.

To return a download link for a File resource, make a GET request to /FILE_ID/content with the suppress_redirects=true parameter. The URL is returned in the response body in the following format.

{
   "location": "..."
}

Note

If the client has already requested the properties for a file, the download link will be in the source field.

To create a new File resource, you can either make aPUT request with the file in the body, or you can make a POST request with the file in a multipart form body. You can make a POST request to the /UPLOAD_LOCATION for the target folder, a POST request to /FOLDER_ID/files, or a PUT request to /FOLDER_ID/files/<file name>. For a POST request, you must also format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Important

On platforms that support the PUT request, use PUT whenever possible to upload files to OneDrive to avoid errors that can occur when POST is used.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the file as the value of the filename parameter of the Content-Disposition header, as shown here.

--AaB03x
Content-Disposition: form-data; name="file"; filename="file1.txt"
Content-Type: text/plain

...contents of file1.txt...
--AaB03x--

Note

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

We support only one multipart section per request. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created file, and the response body contains the following properties.

{
   "id": "ID of the new file",
   "name": "The file's name and file extension",
   "source": "URL where the file can be downloaded from"
}

You can instruct OneDrive to return an HTML response that can be used inside a web browser after the file is created. You can also attach a unique identifier to each upload request so that you can identify a particular upload if you are uploading multiple files in quick succession, which is especially useful for <form> multipart posts. To do this, use a POST multipart/form-data request, like this.

POST https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files?state=MyNewFileState&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.htm&access_token=ACCESS_TOKEN

Content-Type: multipart/form-data; boundary=AaB03x

--AaB03x
Content-Disposition: form-data; name="file"; filename="MyNewFile.txt"
Content-Type: text/plain

These are the contents of my new file.
--AaB03x--

In this example, replace the folder ID with your target folder ID; replace the state query-string parameter value with your unique identifier; and replace the redirect_uri query-string parameter with the path to your callback page. Note that the domain portion of the path must match the redirect domain that you specified in the services using Microsoft account app management site, for the corresponding client ID.

OneDrive returns HTML-formatted code similar to the following.

<html>
    <head>
        <script type="text/javascript">
            window.location = "http://www.contoso.com/callback.htm#state=MyNewFileState&result=%7B%22id%22%3A%22file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184%22%2C%22source%22%3A%22http%3A%2F%2Fstorage.live.com%2Fs1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9%2FMyNewFile.txt%3ABinary%2CDefault%2FMyNewFile.txt%22%7D";
        </script>
    </head>
</html>

When decoded, the result response parameter is similar to this.

{
    "id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!184",
    "name: "MyNewFile.txt",
    "source": "http://storage.live.com/s1pasGKzgXFvuEQCbxGtOyIpboUVH1OCHoRzUJNDDwL0zVoidb0RRrNVk88hUrOEve5OMT7eCkuxPbop7dV9tMJQ-eE8SCQ28vFv9ZgPnDGwQMRm-0FeG3-KEY4HL9dQSw9/MyNewFile.txt:Binary,Default/MyNewFile.txt"
}

You can upload a file to an existing resource in any of the following ways.

Make a PUT request to /UPLOAD_LOCATION/FILE_NAME of the parent folder's ID.
Make a PUT request to /FOLDER_ID/files/FILE_NAME.
Make a PUT request to /UPLOAD_LOCATION for the file to update.
Make a PUT request to /FILE_ID/content.

To update the properties for a File resource, make a PUT request to /FILE_ID, and specify the changes in the request body, as shown here. In this example, both the file name and the description are updated. Note that the filename extension is required when updating the file name.

{
   "name": "UFO_Sightings_1979.docx"
   "description": "The detailed accounts of all UFO sightings in 1979."
}

To delete a file, make a DELETE request to /FILE_ID.

To move a file, make a MOVE request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a file, make a COPY request to /FILE_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Remarks

In all of the preceding cases, you can replace FILE_ID with either me/skydrive/FRIENDLY_FOLDER_NAME or USER_ID/skydrive/FRIENDLY_FOLDER_NAME, where me represents the current consenting user, USER_ID represents the consenting user's ID, and FRIENDLY_FOLDER_NAME represents an allowed friendly folder name like my_documents to represent the Documents folder.

Note

Before uploading a file, have your app check to make sure that there is enough available OneDrive storage space by making a GET call to USER_ID/skydrive/quota. For example, your app could get the size of the file in bytes and then compare it to the number of available storage bytes returned in the OneDrive quota call.

File object

Valid object paths

Structures

Examples

Remarks

See also

Additional resources