File and folder properties on OneDrive (REST)

  • Article

Your apps can use the Live SDK REST API to read user's Microsoft OneDrive file and folder properties.

In this article
Prerequisites
Read a file's properties
Update a file's properties
Read a folder's properties
Update a folder's properties
Get links to files and folders
Get a user's total and remaining OneDrive storage quota
Get a list of OneDrive objects that are shared with the signed-in user
Use friendly names to access certain OneDrive folders

Prerequisites

We assume that the user has already signed in and consented to the wl.skydrive scope for reading file or folder properties. If you have not added user sign-in to your apps, see Signing users in with REST.

We assume that you are familiar with the REST API and JSON.

Note

In this context, a file represents a file of any supported format, including a photo, video, or audio. A folder can contain child folders and files.

Read a file's properties

To get info about a file, photo, video, or audio, use code like this. The wl.skydrive scope is required.

Note

In all examples, change folderID to a different folder ID, or fileID to a different file ID, photo ID, video ID, or audio ID, to get info about a different file, photo, video, or audio.

GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126?
    access_token=ACCESS_TOKEN

Update a file's properties

To change info about a file, photo, video, or audio, use code like this. The wl.skydrive_update scope is required.

PUT https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "MyNewFileName.doc"
}

For details about the minimum required and optional structures that your app must provide to use PUT for a photo, video, or audio, see the Audio object, Photo object, or Video object from the REST API. For corresponding details regarding any other file type, see the File object.

Read a folder's properties

To read a folder's properties, use code like this. Change the folder ID to:

  • A different folder ID, to get info about another folder.

  • FOLDER_ID/files, where FOLDER_ID represents a valid folder ID, to get a list of all items in a folder. Your code can check to see whether any of these items has its type structure set to folder. Then your code can make another call that uses the item's folder ID to get that folder's info, too.

GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!114?
    access_token=ACCESS_TOKEN

Update a folder's properties

To change info for an existing folder, use code like this. The wl.skydrive_update scope is required. Change the folder ID to the folder ID (or, in certain cases, the friendly name) of the folder that you want to change.

For details about the minimum required and optional structures that your app must provide to use PUT, see Folder object.

PUT https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!114

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "name": "My example folder has changed"
}

Your apps can get the following types of links to OneDrive folders and files.

  • An embedded link, which is an HTML code snippet that you can insert into a web page to provide an interactive view of the corresponding file.

    Note

    Currently, embedded links are supported only for files owned by the user. To determine whether a given file can be embedded, check to see if the corresponding File object's is_embeddable structure is set to true. Also, some embedded links provide a rich embedding experience, while others provide only an icon and a file name. Rich embedding is supported for the following types files: .doc, .docx, .pdf, .odt, .pot, .potm, .potx, .pps, .ppsm, .ppsx, .ppt, .pptm, .pptx, .xlsb, .xlsm, and .xlsx.

  • A read-only link, which is a link to a read-only version of the folder or file.

  • A read-write link, which is a link to a read-write version of the folder or file.

Note

When your apps request a read-only or read-write link to a file, the URL to that file is the same for either request. When your apps request a read-only link for a file and then later request a read-write link for that same file, read-only permission for that link is revoked. Similarly, when your apps request a read-write link for a file and then later request a read-only link for that same file, read-write permission for that link is revoked.

To get a link to a folder or file, use code like this.

GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126/shared_read_link?
    access_token=ACCESS_TOKEN

In the preceding code, change the file ID to the folder ID or file ID that you want a link to. Also, change shared_read_link to one of these.

  • To embed for an embedded link. You get the embed HTML code snippet from the returned JavaScript Object Notation (JSON)-formatted object's embed_html structure value.

  • To shared_read_link for a read-only link. You get the read-only link from the returned JSON-formatted object's link structure value.

  • To shared_edit_link for a read-write link. You get the read-write link from the returned JSON-formatted object's link structure value.

When your app requests a file, photo, video, or audio, the returned object includes a preauthenticated URL as the value of the source attribute. Preauthenticated URLs allow access to a file without the need for additional permissions. Preauthenticated URLs expire and should not be stored or reused later. The following example shows what a preauthenticated URL looks like.

"source": "http://storage.live.com/s1pk0Hsk4twGIbzleNLcqhVhp5yvj9aPLPMHq2GD
    TRFBeuicbS27Fx5xBnmyy5J4lDSEtdvYm2FxOB0-s8Heb1l6hq3A1E2bJ9qWQ3GdIUTnnG6
    CHLTBLdCHRPUNAunekX1dnLS49vG-fUV7O8ZvrkiLTubXXFqrT1roxZ1oJjELE/Test.txt:Binary"

Get a user's total and remaining OneDrive storage quota

To get info about a user's available and unused storage space in OneDrive, make a GET call to /me/skydrive/quota or /USER_ID/skydrive/quota, where USER_ID is the signed-in user's ID.

GET https://apis.live.net/v5.0/me/skydrive/quota?access_token=ACCESS_TOKEN

The JSON-formatted object that's returned looks like this. In this example, the quota field is the user's total available storage space, in bytes; the available field is the user's remaining unused storage space, also in bytes. Your app could get the size of the file in bytes and then compare it to the number of bytes in the available field. If the file size is greater than the available field, your app should not try to upload the file.

{
    "quota": 26843545600,
    "available": 26805319016
}

Get a list of OneDrive objects that are shared with the signed-in user

To discover all OneDrive objects that are shared with the signed-in user, use the wl.contacts_skydrive scope to make a GET request to /USER_ID/skydrive/shared, where USER_ID is either me or the user ID of the sharing user. The sharing user must be one of the signed-in user's contacts, who has shared their OneDrive objects with the user. Here's an example.

GET https://apis.live.net/v5.0/me/skydrive/shared?access_token=ACCESS_TOKEN

Note

Creating, updating, or deleting files in a folder that is shared with the signed-in user is not supported by the OneDrive API. Apps can manipulate only files that are owned by the signed-in user. We don't support third-party apps that upload files to shared folders.

Use friendly names to access certain OneDrive folders

To access certain OneDrive folders, you can use friendly names instead of folder IDs. Use the following friendly names to access these corresponding folders in the OneDriveUI:

  • USER_ID/skydrive/camera_roll represents the OneDrive camera roll folder.

  • USER_ID/skydrive/my_documents represents the Documents folder.

  • USER_ID/skydrive/my_photos represents the Pictures folder.

  • USER_ID/skydrive/public_documents represents the Public folder.

In each case, replace USER_ID with either me for the signed-in user or a user ID for any other consenting user.

For example, to read the Documents folder's properties, use a REST API call to the folder's ID, like this.

GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110?access_token=ACCESS_TOKEN

But you can also read the Documents folder's properties with a REST API call to the folder's friendly name, like this:

GET https://apis.live.net/v5.0/me/skydrive/my_documents?access_token=ACCESS_TOKEN

Note

To move or copy a file into a folder with a friendly name, you provide only the friendly name as the value of the destination structure. Here's an example of how to call the REST API to move a file into the Documents folder.

MOVE https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    "destination": "my_documents"
}