OneDrive是微软推出的云存储工具，类似Dropbox以及Google Drive。同样的，OneDrive也可以通过RESTful API来访问。微软把他们家的API服务叫做Graph，OneDrive的API只是Microsoft Graph API集合中的一部分。

简介

OneDrive API其实可以用于若干不同的产品中（参考OneDrive developer platform）：

  • OneDrive for Personal
  • OneDrive for Business
  • Sharepoint document libraries

不同的产品对API的支持有些许差别。比如OneDrive for Personal允许APP有自己独立的目录，而这个功能在OneDrive for Business就没有，所以要仔细看文档。

微软在OneDrive的REST API上封装了一些工具，比如File picker，用来浏览OneDrive目录中的文件。另外还有File Handler，是给OneDrive for Business and SharePoint document libraries，用来自定义文件的内容。

基本概念

OneDrive在Graph中的资源是这么组织的：

  • Resource Root/Drive/Drive Item

第一级别是不同类型的Resource Root，可以是：

  • User，示例访问路径/v1.0/users/{id}
  • Group，示例访问路径/v1.0/groups/{id}
  • Site，示例访问路径/v1.0/sites/{id}

第二级别是Drive。这个有点像平时操作系统中使用的C盘和D盘的概念。每个OneDrive用户一般有一个默认的Drive。一些关于Drive的操作：

  • GET /drives/{drive-id} 获取一个drive的信息
  • GET /drive/root，获取默认drive的根目录
  • GET /drive/activities，获取drive的操作流
  • GET /drive/root/children，获取root目录的子项目
  • GET /drive/root/delta，获取root目录下的改动
  • GET /drive/root/search，搜索root目录
  • GET /drive/special/{name}，获取特殊目录。OneDrive沿袭Windows的传统，有特殊目录的概念，比如document就是一个特殊的目录。对于特殊目录，是默认存在的，不需要创建的。

第三级别是是Drive Item，用于表示某个Drive下面所有的项目。Drive Item可以有很多类型。一个文件可以是一个Drive Item，一个目录也是一个Drive Item，一个音频也是一个Drive Item。凡是OneDrive认识的不同的文件类型，都可以是不同的Drive Item。每个Drive Item的类型，根据其facet来区分（参考DriveItem resource type）。文件有文件的Facet；目录有目录的Facet；图片有图片的Facet等等。

所有的Drive Item都有一套用JSON表示的基本属性，这些属性有一部分是从baseItem中继承过来的。而所谓的Facet，就是这些属性之中，某种Drive Item特有的。比如目录有额外的属性用来表示所包含子项目的个数：

{
  "childCount": 1024,
  "view": { "@odata.type": "microsoft.graph.folderView" }
}

资源访问

参考Addressing resources in a drive on OneDrive

我们来直观感受以下如何访问通过URL来访问OneDrive的资源，下面是一个例子：

https://graph.microsoft.com/v1.0/me/drive/root:/Documents/MyFile.xlsx:/content
  • https://graph.microsoft.com/v1.0，graph的地址，1.0是其当前的版本
  • /me，也就是Resource Root为自己
  • /drive/root，默认的drive的根目录
  • :/Documents/MyFile.xlsx:, ::包围起来的是文件在根目录下的地址
  • /content，表示文件的内容

所以上面的整个URL表示的意思是，获取默认drive下路径为/Documents/MyFile.xlsx的内容。

注意，除了使用路径之外，还可以使用Drive Item的ID去访问它，例如/drive/items/0123456789AB/content

扫描改动

参考Track changes for a Drive

OneDrive和Dropbox类似，都是通过游标的方式来同步改动。

调用下面接口可以获取游标：

GET https://graph.microsoft.com/v1.0/me/drive/root/delta

服务器返回@odata.nextLink

HTTP/1.1 200 OK
Content-type: application/json

{
...
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/me/drive/delta(token=1230919asd190410jlka)"
}

注意，上面的@odata.nextLink就是一个游标。APP应该访问游标所指向的地址，继续获取改动。

如果当前没有其他改动了，那么服务器会返回@odata.deltaLink

HTTP/1.1 200 OK
Content-type: application/json

{
...
    "@odata.deltaLink": "https://graph.microsoft.com/v1.0/me/drive/root/delta?(token='1230919asd190410jlka')"
}

此时所有的改动都已经获取到了。APP应该保存@odata.deltaLink，然后时不时去查询，看是否有新的改动。

其他