Sign in
HomeMy appsDocsInteractive SDKDownloadsSupportShowcase
Live Connect Developer Center > Docs > SkyDrive (files and photos) > SkyDrive core concepts

SkyDrive core concepts

Expand
52 out of 58 rated this helpful - Rate this topic

SkyDrive core concepts

Traversing the SkyDrive directory

To use the Live Connect APIs to get info about a user's top-level folder in the Microsoft SkyDrive 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# for Metro style apps, use the LiveConnectClient.Get method.
  • In C# for Windows Phone apps, 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 audios.

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 SkyDrive 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 SkyDrive 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 SkyDrive directory might look like conceptually.

Copy 
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

Object permissions

Users can control who can access certain objects in their SkyDrive storage location. This includes objects like folders, files, albums, photos, videos, and audio.

Object permissions in SkyDrive are inherited from their parent objects all the way up to a user's top-level folder in the SkyDrive directory.

When your code creates or updates an object in SkyDrive, your code can't set or change the object's permissions programmatically. Its permissions are inherited automatically. However, an app can allow sharing with a link to grant users read or read/write access to a file or folder. Of course, the user can change an object's permissions through the SkyDrive UI.

Your code can't change an object's permissions in a way that would restrict permissions all the way up to a user's top-level folder in the SkyDrive directory. For example, if a certain folder allows anyone to access its contents, you can't change the permissions on any of the folder's contained objects to restrict who can access them.

Your code can get a link to a folder or a file, and then you can share that link with other users so that they can access the folder or file directly. We provide several link types, including embedded, read-only, and read-write links, for publicly shared folders and files. These links will work only for users who have permission to view the file.

We also provide preauthenticated links to files; these links work regardless of file permissions. These links should be created only when the user wants to share a folder or file with specific people, because file permissions are not evaluated for these links, and anyone who clicks on the links can view the content. For more info, see the "Getting links to folders and files" section in the Folders and files topic.

Top

Get SkyDrive objects that are shared with the signed-in user

To discover all SkyDrive 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.

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

Top

File concepts

To upload a file to SkyDrive, your code can use HTTP operations such as POST or PUT. You can also use MOVE and COPY to avoid downloading, and then uploading files that you want to move or copy.

When your code uploads a file, and a file with the same name already exists in the same location in SkyDrive, the default behavior is for SkyDrive to overwrite the existing file. You can add an Overwrite header with a value of false to prevent the existing file from being overwritten.

Top

Use friendly names to access certain SkyDrive folders

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

  • USER_ID/skydrive/camera_roll represents the SkyDrive 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, reading the Documents folder's properties with a REST API call to the folder's ID looks like this.

Copy 
GET http://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:

Copy 
GET http://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.

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

Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
    destination: "my_documents"
}

Top

Get a user's total and remaining SkyDrive storage quota

To get info about a user's available and unused storage space in SkyDrive, 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.

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

The JSON-formatted object that's returned looks like this.

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

In the preceding example, the quota structure is the user's total available storage space, in bytes; the available structure is the user's remaining unused storage space, also in bytes.

Supported file formats

SkyDrive currently supports the following file formats:

  • Documents (Portable Document Format (PDF) files, text files, and Microsoft Office files)
  • Photos (common image file formats; uploading raw images is not supported)
  • Videos (H.264 and Windows Media Video (.wmv))
  • Audio (downloading any audio file type, and uploading Waveform Audio File Format (.wav) only, is supported)

Here is the full list of supported file extensions:

  • .3g2
  • .3gp
  • .ai
  • .bmp
  • .chm
  • .doc
  • .docm
  • .docx
  • .dot
  • .dotx
  • .epub
  • .gif
  • .jpeg
  • .jpg
  • .mp4
  • .one
  • .pdf
  • .png
  • .pot
  • .potm
  • .potx
  • .pps
  • .ppsm
  • .ppsx
  • .ppt
  • .pptm
  • .pptx
  • .psd
  • .tif
  • .tiff
  • .txt
  • .xls
  • .xlsb
  • .xlsm
  • .xlsx
  • .wav
  • .webp
  • .wmv

Top

Guidelines for apps that interact with SkyDrive

Apps that interact with SkyDrive must conform to these principles:

  • Upload files to SkyDrive only in response to an explicit user request or choice. Your apps must always ensure that a user intentionally chooses to save any new data to SkyDrive. Apps must not upload files to SkyDrive automatically without a user making an explicit choice to upload those files.

    Here are some examples of conforming apps:

    • Apps that display an "Upload to SkyDrive" or "Share on SkyDrive" button that a user must click before each upload of a photo, video, document, or other file.
    • Document-editing apps that require a user to click an "Upload to SkyDrive" button initially, so that the app can save that document later without further user interaction.

    Here are some examples of nonconforming apps:

    • Apps that automatically upload to SkyDrive any file added to a specific location on a user’s devices.
    • Apps that automatically back up files or folders to SkyDrive.
  • Use SkyDrive for the things that it’s good at. SkyDrive includes features both for high-quality document viewing and editing, and for creating and sharing beautiful photo albums. If possible, have your apps take advantage of these features. To support this principle, the Live Connect APIs limit the set of file formats that apps can upload to SkyDrive. In general, if your apps store file formats that are understood only by those apps, those file formats don’t belong on SkyDrive.

  • Don't undermine trust in SkyDrive. Over the years that SkyDrive has been available, users have come to trust it. Preserving that trust is critical and your apps must not undermine it by doing things that users don’t expect, especially with regard to data privacy.

    Here are some examples of conforming apps:

    • Apps that upload documents or photos to SkyDrive with user-only access as the default.
    • Apps that warn users that, when the users send a link to their content stored on SkyDrive, anyone who receives that link can read the associated files.

    Here is an example of a nonconforming app:

    • An app that makes all shared files in SkyDrive publicly accessible by default, without clearly communicating this behavior to users.

Top

 

 

Build date: 4/26/2012

Did you find this helpful?
(1500 characters remaining)
Terms of use | Trademarks | Privacy statement | Site feedback | United States (English)
© 2012 Microsoft. All rights reserved.