纵览OneDrive的GraphAPI

Sun 24 February 2019 / In categories Platform

Microsoft Graph, OneDrive

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,然后时不时去查询,看是否有新的改动。

其他

Load Disqus Comments