Module also comes with command-line tool to conveniently browse and
manipulate OneDrive contents from interactive shell or scripts.

Thanks to AntonioChen for implementing windows and unicode support (see
#3).

Service was called SkyDrive prior to 2014-02-19, when it got renamed to
OneDrive. This package similarly renamed from python-skydrive to
python-onedrive.

Command-line usage

OneDrive API requires to register an application in
DevCenter, providing you with client_id and
client_secret strings, used for authentication.

I can’t provide some static ones because according to LiveConnect ToS
“You are solely and entirely responsible for all uses of Live Connect
occurring under your Client ID” (also see notes below), and I can’t just
vouch for every module/tool user like that.

App registration in DevCenter is really straightforward and shouldn’t
take more than a few clicks. Be sure to check the “mobile client app”
box under “API settings”.

After that, create “~/.lcrc” file
(YAML) with the contents like
these:

client:
id: 00000000620A3E4A
secret: gndrjIOLWYLkOPl0QhWIliQcg-MG1SRN

(use “id” and “secret” acquired in the app registration step above,
indent these lines with spaces - indenting with tabs is not allowed in
YAML)

Then you need to perform OAuth 2.0 authorization dance by running the
onedrive-cli auth command and following printed instructions (visit
printed URL, authorize, click “Allow”, paste last URL back into
terminal). This will get you authorization_code (which will be stored
in ~/.lcrc) to use the API as a user you’ve logged-in as there. Repeat
this step to authorize with a different account, if necessary.

Then just type whatever commands you want to (and don’t forget
onedrive-cli--help):

Most commands should be self-descriptive, but use “–help” when they
aren’t.

Note that objects specified on the command-line are implicitly resolved
as human-readable paths (which are basically metadata) unless they look
like an id. This might be undesirable from performance perspective
(extra requests) and might be undesirable if non-unique “name”
attributes of objects in the same parent folder are used. Use “-p” or
“-i” (“–path” / “–id”) switches to control this explicitly. See
LiveConnect docs or notes section below for more info on how these work.

If you get HTTP error 400 right after or during “auth” command, read
this comment on
#4
(maybe with some context).

“standalone” option above enables dependency on “requests” module, which
is used as default HTTP client lib. If the plan is to extend or override
that, flag can be dropped.

Note that to install stuff in system-wide PATH and site-packages,
elevated privileges are often required. Use “install –user”,
~/.pydistutils.cfg
or virtualenv to do
unprivileged installs into custom paths.

Alternatively, ./onedrive-cli tool can be run right from the
checkout tree without any installation, if that’s the only thing you
need there.

(optional) chardet - used to
detect encoding (utf-8, gbk, koi8-r, etc) of the command-line
arguments to support workng with non-ascii (e.g. cyrillic, chinese)
names, if it’s not specified explicitly.

Known Issues

As also noted below, TLS implementation on Microsoft
public.bay.livefilestore.com seem to be broken, choking if client
advertise TLS 1.2 in “Client Hello” packet and works if client only
advertises TLS 1.0 support.

Underlying HTTP protocol implementation module - requests - of versions
earlier than 0.14.0 might have an issue with that (later versions can
either work around it or patched in this module).

So be sure to use requests 0.14.0 or higher - ideally 1.0.0 or later
versions, where no dirty workarounds are necessary.

Some proprietary formats, like “OneNote notebook” just can’t be accessed
(see #2).
OneDrive doesn’t allow GET requests for these things and they’re also
special exceptions to other API
methods,
no idea what can be done there.

LiveConnect/OneDrive API (v5.0) notes

Important: these details can (naturally) go obsolete, especially if
timestamp of this doc is older than the one of the API docs, in which
case please open an Issue pointing to the inconsistency.

It’s quite a conventional REST API with JSON encoding of structured
data, like pretty much every other trendy modern API, say, github.

Authentication is “OAuth
2.0”,
which is quite ambigous all by itself, and especially when being
implemented by well-known for it’s proprietary “cripple-everything-else”
extension creep Microsoft. It has a twist in authrization_code grant
flow for “mobile” apps, where bearer token refresh can be performed
without having to provide client_secret. Client app must be marked as
“mobile” in DevCenter for that to work.
There’s also totally LiveConnect-specific “Sign-In” auth flow. Access
tokens for OneDrive scopes (plus wl.offline) seem to be issued with ttl
of one hour.

Permissions are set per-path, are inherited for the created objects and
cannot be changed through the API, only through the Web UI (or maybe
proprietary windows interfaces as well).

Accessible to everyone URL links (of different types - embedded,
read-only, read-write, preauthenticated) to any restricted-access object
(that is reachable through the API) can be provided in
“preauthenticated” form, a bit like in tahoe-lafs, but probably without
the actual crypto keys embedded in them (not much point as they’re kept
server-side along with the files anyway).

All but a few default paths (like “my_documents”) are accessed by
file/folder IDs. All IDs seem to be in the form of
“{obj_type}.{uid_lowercase}.{uid_uppercase}!{obj_number}”, where
“obj_type” is a type of an object (e.g. “file”, “folder”, etc),
“uid_*” is some 8-byte hex-encoded value, constant for all
files/folders of the user, and “obj_number” is an integer value
counting up from one for each uploaded file.

UI-visible names come on top of these IDs as metadata, so “rename” is
essentially a metadata “name” field update and two files/folders with
the same “name” can co-exist in the same parent folder, though uploading
a file defaults to overwriting file with same “name” (disableable).

There’s a “Recycle Bin” path in web interface, which I don’t recall
seeing any way to access, which keeps all removed files (for some
limited time, presumably). Files removed through the API end up there as
well.

There are some handy special OneDrive-related API URLs for stuff like
quota, list of recent changes and a list of shared-with-me objects.

Files have a lot of metadata attached to them, parsed from their
contents (exif data for photos, office documents metadata, etc). API
allows to request image-previews of an items, links to which are also
available in file (object) metadata.

Actual fetching of files seem to be done through
https://public.bay.livefilestore.com, but TLS there doesn’t work with
curl or python “requests” module at the moment, only with browsers.
Problem seem to be broken TLS implementation on the IIS server - it
chokes if client advertise TLS 1.2 in “Client Hello” packet (e.g.
“openssl s_client -showcerts -connect
public.bay.livefilestore.com:443”) and works if client only advertises
TLS 1.0 support (“openssl s_client -tls1 -showcerts -connect
public.bay.livefilestore.com:443”). Issue is known and generic
workaround is documented as such in openssl project changelog. Newer
“requests” module seem to have workaround for the issue implemented
(0.14.0 seem to work, 0.10.8 does not).

Errors can be returned for most ops, encoded as JSON in responses and
have a human-readable “code” (like “resource_quota_exceeded”) and
descriptive “message”.

According to OneDrive interaction
guidelines,
it is discouraged (though not explicitly prohibited) to upload files in
non-conventional formats that aren’t useable to other apps (under “Use
OneDrive for the things that it’s good at”):

To support this principle, the Live Connect APIs limit the set of file formats
that apps can upload to OneDrive.