Common tasks in accessing Microsoft OneDrive from your app
This topic describes how to do common tasks when accessing a user's Microsoft OneDrive contents from your app.
Traversing the OneDrive directory
To use the Live Connect APIs to get info about a user's top-level folder in the OneDrive directory, you make a request to me/skydrive or USER_ID/skydrive. Here's how to make this call:
- In Representational State Transfer (REST), use GET.
- In JavaScript, use the WL.api function, specifying a method parameter of "GET".
- In C#, use the LiveConnectClient.GetAsync method.
- In Objective-C, use the LiveConnectClient getWithPath method.
- In Java, use the LiveConnectClient.getAsync method.
In the JavaScript Object Notation (JSON)-formatted object that's returned, two structures are important to note: the id structure that represents the top-level folder's folder ID, and the upload_location structure that represents the location for the top-level folder to which you can upload files, photos, videos, and audio.
If you make a request to me/skydrive/files or USER_ID/skydrive/files, the JSON-formatted object that's returned contains info about all of the child folders, child albums, and files in the user's top-level folder only.
From there, you can traverse a user's entire OneDrive directory by making a request with FOLDER_ID/files or ALBUM_ID/files, where FOLDER_ID or ALBUM_ID represents the id structure that corresponds to a folder ID or album ID, respectively, anywhere in the directory.
As with a user's top-level OneDrive folder, you can use the upload_location structure for any folder or album to upload files to that folder or album. Additionally, you can use the upload_location structure for any file, photo, video, or audio to overwrite the contents of that file, photo, video, or audio.
For example, here's what a user's OneDrive directory might look like conceptually.
GET https://apis.live.net/v5.0/me/skydrive?access_token=ACCESS_TOKEN
---
200 OK
{
"id": "folder.a6b2a7e8f2515e5e",
...
"upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files",
...
"type": "folder",
...
}
---
GET https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e/files?access_token=ACCESS_TOKEN
---
200 OK
{
"data": [
{
"id": "folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110",
...
"upload_location": "https://apis.live.net/v5.0/folder.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!110/files/"
...
"type": "folder",
...
}, {
"id": "photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131",
...
"upload_location": "https://apis.live.net/v5.0/photo.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/content/",
...
"type": "photo",
...
}, {
"id": "file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119",
...
"upload_location": "https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!119/content/",
...
"type": "file",
...
}
]
}
Getting 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
Using 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 OneDrive UI:
- USER_ID
/skydrive/camera_rollrepresents the OneDrive camera roll folder. - USER_ID
/skydrive/my_documentsrepresents the Documents folder. - USER_ID
/skydrive/my_photosrepresents the Pictures folder. - USER_ID
/skydrive/public_documentsrepresents 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
MOVE https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!126
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
{
"destination": "my_documents"
}
Getting a list of the user's most recently used documents
To get a list of OneDrive documents that the user has used most recently, use the wl.skydrive scope to make a GET request to /USER_ID/skydrive/recent_docs, where USER_ID is either me or the user ID of the consenting user. Here's an example.
GET https://apis.live.net/v5.0/me/skydrive/recent_docs?access_token=ACCESS_TOKEN
Getting 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. Here's an example using the REST API.
GET https://apis.live.net/v5.0/me/skydrive/quota?access_token=ACCESS_TOKEN
The JSON-formatted object that's returned looks like this.
{
"quota": 26843545600,
"available": 26805319016
}
In the preceding 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.
{
"error": {
"code": "resource_quota_exceeded",
"message": "The user has reached his or her storage quota limit."
}
}
Displaying a preview of a OneDrive item
To display a preview of an item in OneDrive, make a GET request to /skydrive/get_item_preview?type=TYPE&url=URL. The optional type query-string parameter is one of the following:
- thumbnail
- small (to get a maximum 100 × 100-pixel preview)
- album (maximum 200 × 200)
- normal (maximum 800 × 800)
The required url query-string parameter is a shared link to the item in OneDrive. Here are two examples, one using a longer OneDrive URL and one using a shorter sdrv.ms URL (sdrv.ms is a URL-shortening service that's unique to OneDrive).
GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=https%3A%2F%2Fskydrive.live.com%2Fredir.aspx%3Fcid%3Da6b2a7e8f2515e5e%26amp%3Bresid%3DA6B2A7E8F2515E5E!132%26amp%3Bparid%3DA6B2A7E8F2515E5E!110%26amp%3Bauthkey%3D!ACuMMo37Ju8_xw0x
GET https://apis.live.net/v5.0/skydrive/get_item_preview?type=normal&url=http%3A%2F%2Fsdrv.ms%2FLTIvcyx
Note the following:
- To make the get_item_preview request, you don't need to request any scopes or provide an access token.
- If the item is not a photo, and a preview is associated with the item, a thumbnail preview is displayed and the type parameter is ignored even if provided.
- A successful response has a responseStatus value of" 302 Found" with the link to the item preview in the "Location" response header.
- If a particular size of preview doesn't exist, the next-largest size preview that's available is displayed. If no preview is associated with the item, a 404 (Not Found) error is returned.
- You can get a shared link to an item in one of three ways:
- Make a GET request to ITEM_ID/shared_read_link, where ITEM_ID is the OneDrive item's ID. Here's an example.
You can find the shared link value in the JSON-formatted response object's link structure.
GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/shared_read_link?access_token=ACCESS_TOKEN
- In the OneDrive UI, select the item, and then click Share. Click Get a link and then, next to View only, click Create. OneDrive displays the shared link value, which you can use in your get_item_preview request. The value should look something like this:
https://onedrive.live.com/redir.aspx?cid=a6b2a7e8f2515e5e&resid=A6B2A7E8F2515E5E!132&parid=A6B2A7E8F2515E5E!110&authkey=!ACuMMo37Ju8_xw0x. - In the OneDrive UI, select the item, and then click Share. Click Post to Twitter, follow the on-screen directions, and then click Post. The newly created Twitter post includes the shared link value, which you can use in your get_item_preview request. The value should look something like this:
http://1drv.ms/LTIvcyx.
- Make a GET request to ITEM_ID/shared_read_link, where ITEM_ID is the OneDrive item's ID. Here's an example.
- The url query-string parameter's value must be URL-encoded. For example, use %3A for the colon (":") character, %2F for the forward slash ("/") character, %3F for the question mark ("?") character, and %26 for the ampersand ("&") character.