Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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", 
            ...
        }
    ]
}

Top

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 consenting 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.

Important  We don't support third-party apps that upload files to shared folders.

Top

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_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"
}

Top

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

Top

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.

Tip  Before uploading a file, have your app check to make sure that there is enough available storage space. For example, 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. If your app tries to upload the file anyway, the upload request will fail and OneDrive will return the following error.

{
    "error": {
        "code": "resource_quota_exceeded", 
        "message": "The user has reached his or her storage quota limit."
    }
}

Top

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.
      GET https://apis.live.net/v5.0/file.a6b2a7e8f2515e5e.A6B2A7E8F2515E5E!131/shared_read_link?access_token=ACCESS_TOKEN
      
      
      You can find the shared link value in the JSON-formatted response object's link structure.
    • 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.
  • 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.

Top

 

 

Show:
© 2014 Microsoft. All rights reserved.