The Dropbox SDK uses the Core API which exposes the fundamental building blocks that make up Dropbox. It's based on HTTP and OAuth, so it should be very familiar to most developers.
You can get the Dropbox SDK here.
If you want to follow along, first register a new app on the App Console to get an App Key and App Key Secret. You'll need these app keys to use the SDK.
Save the SDK as Class DBox.ahk, either in the same folder as your project or in one of the standard libraries. Include the SDK in your script using one of the following statements:
#Include Class DBox.ahk ; If the SDK is in the same folder as your project
#Include <Class DBox> ; If the SDK is in one of the standard libraries
The Core API uses OAuth v1, but the SDK will take care of most of it so you don't have to start from scratch.
You'll need to provide your app key and secret as well as the access level, you selected when creating the app.
Pass all three values to the new operator:
MyDB := new DBox("wysh39uunwovz6", "z8u4w3lr1zswro", "dropbox")
Now we're all set to start the OAuth flow. The OAuth flow has three parts:
- Get a request token.
- Ask the user to authorize linking your app to their Dropbox account.
- Once authorized, exchange the request token for an access token, which will be used for calling the Core API.
MyDBox
object to get a request tokens via the GetAuthorizationTokens()
method.MyDB.GetAuthorizationTokens()
This will add the OauthToken and OauthTokenSecret members to the MyDB object. These are used in the next authorization step.
Now that you have the request tokens, you can ask the user to authorize your app. To do this you have two choices:
- open https://www2.dropbox...ze?oauth_token=" this.OauthToken and have the user authorize manually.
- Use the
GetUserAuthorization(UserEmail, UserPassword)
for a more automated approach.
Once the user has granted permission to your app, we can upgrade the now-authorized request token to an access token. We'll do that by using the
GetAccessTokens()
method.; This will fail if the user didn't visit the above URL and hit 'Allow' MyDB.GetAccessTokens()This will replace the values for OauthToken and OauthTokenSecret with true access tokens.
These access tokens are all you'll need to make API requests on behalf of this user, so you should store them away for safe-keeping (even though we don't for this tutorial). By storing the access tokens, you won't need to go through these steps again unless the user reinstalls your app or you revoke access via the Dropbox website. Just pass the access keys as the last two parameters of the new operator:
MyDB := new DBox("wysh39duunwovz6", "z8u4w3alr1zswro", "dropbox", "df7sdfsd8g7df7", "jh34jh34h45j")
Those five parameters are what you need to save.
Now the hard part is done and you have all you need to use the SDK. To test that we've got access to the Core API, try calling:
GetAccountInfo(Locale := "en")
which will return an object containing information about the user's linked account:
AccountInfo := MyDB.GetAccountInfo() MsgBox % AccountInfo.emailIf you've made it this far, you have a simple app that uses the Core API to link to a Dropbox account and your first API call for account info. Next, we'll upload a file to Dropbox, get its metadata, and then download it back to our app.
Uploading files
Let's say we're building a text editing app and we want to use it to save your latest magnum opus to Dropbox. Let's browse the methods in the SDK to see which one will do that for us. All of the available methods are listed a the top of the source of the SDK. Looking there you should find:
PutFile() - Uploads a file.
The function definition for PutFile is:
PutFile(Source, Destination, OverWrite := true, ParentRev := "", Locale := "en")
The parameters are all explained in the source code, but for now we are only concerned with the Source and Destination parameters.
Source - The path and file name to upload. This is relative to A_WorkingDir unless a full path is specified. This should NOT point to a folder. Destination - The path to the file you want to write to. This is relative to the app folder or the Dropbox root depending on the AccessLevel. This parameter should NOT point to a folder.
FileInfo := MyDB.PutFile("working-draft.txt", "/magnum-opus.txt")
If all goes well, working-draft.txt will now be in the root of your app folder (or Dropbox folder, depending on your app's access type) and it will be called magnum-opus.txt. The variable
FileInfo
will be an object containing the metadata of the newly uploaded file. It will look something like this:{ 'bytes': 77, 'icon': 'page_white_text', 'is_dir': False, 'mime_type': 'text/plain', 'modified': 'Wed, 20 Jul 2011 22:04:50 +0000', 'path': '/magnum-opus.txt', 'rev': '362e2029684fe', 'revision': 221922, 'root': 'dropbox', 'size': '77 bytes', 'thumb_exists': False }Listing folders
If you peruse the various entries in the metadata above, you'll get a good sense for all info we can gather from the file. You can get this info for an entire folder by using the
GetMetadata()
method.FolderInfo := GetMetadata("/Sample Folder")
The returned object will contain information about the files and folders in the path given. It looks something like this:
{'bytes': 0, 'contents': [{'bytes': 0, 'icon': 'folder', 'is_dir': True, 'modified': 'Thu, 25 Aug 2011 00:03:15 +0000', 'path': '/Sample Folder', 'rev': '803beb471', 'revision': 8, 'root': 'dropbox', 'size': '0 bytes', 'thumb_exists': False}, {'bytes': 77, 'icon': 'page_white_text', 'is_dir': False, 'mime_type': 'text/plain', 'modified': 'Wed, 20 Jul 2011 22:04:50 +0000', 'path': '/magnum-opus.txt', 'rev': '362e2029684fe', 'revision': 221922, 'root': 'dropbox', 'size': '77 bytes', 'thumb_exists': False}], 'hash': 'efdac89c4da886a9cece1927e6c22977', 'icon': 'folder', 'is_dir': True, 'path': '/', 'root': 'app_folder', 'size': '0 bytes', 'thumb_exists': False}In the example above, the app folder root contains a directory named Sample Folder and the file we just uploaded named magnum-opus.txt. You'll also see other various but vital bits of information such as the exact location of the file (
path
), file sizes (bytes
), last modified date (modified
), and more. If you want to tell if something has changed in the directory, you'll want to store and compare the hash
parameter. Similarly, a file's rev
parameter tells you if the file has changed. It's useful to keep track of the status of your files, as we'll see in the following example.Downloading files
Some time has passed and you're ready to start editing that magnum opus of yours again. We'll need the
GetFile()
method to download the file.FileInfo := MyDB.GetFile("magnum-opus.txt", "working-draft.txt")
In addition to the file, the method also returns the file's metadata at its current revision. Every time a change is made to the file, the
rev
field of the file's metadata changes as well. By saving the revision when you download the file, you'll be able to tell if that file has been updated by another computer or device and choose to download the newer revision of that file.
The complete code
For those keeping score at home, here's the full source to this guide. Make sure to create a magnum-opus.txt file to get it to work fully. Also remember to insert your app key, app secret, and access type.
; AutoExecute #NoEnv #SingleInstance force #Include Class DBox.ahk MyDB := new DBox("APP_KEY", "APP_SECRET", "ACCESS_TYPE") SplashTextOn , , , Getting Request Tokens MyDB.GetAuthorizationTokens() SplashTextOn , , , Getting User Authorization MyDB.GetUserAuthorization("[email protected]") ; Your email address goes here SplashTextOn , , , Getting Access Tokens MyDB.GetAccessTokens() SplashTextOff FileInfo := MyDB.PutFile("working-draft.txt", "/magnum-opus.txt") Display(FileInfo) FolderInfo := GetMetadata("/Sample Folder") Display(FolderInfo) FileInfo := MyDB.GetFile("magnum-opus.txt", "working-draft.txt") Display(FileInfo) return ; Everything below here is just used to display the returned object ; This wouldn't typically be necessary. ;Convert the returned object to a string for display ObjToStr(Obj, Indent="`t", Rows="`n", Equal=" = ", Depth=7, CurIndent="") { ; converts object to string For k,v in Obj ToReturn .= CurIndent . k . (IsObject(v) && depth>1 ? Rows . ObjToStr(v, Indent, Rows, Equal, Depth-1, CurIndent . Indent) : Equal . v) . Rows return RTrim(ToReturn, Rows) } ; http://www.autohotkey.com/forum/post-426623.html#426623 Display(Obj) { global MyDB Result := MyDB.LastResponse "`n" . ObjToStr(Obj, " ") MsgBox % Result }SDK Documentation
I encourage you to browse the SDK source code. I've tried to document all of the methods and parameters fully. Also be sure to take a look at the official reference for the Core API.
Next steps
And with that you should be equipped with most everything you need to get started with the Core API. If you're still not sure about something, post your question here. Good luck!