OneDrive API 终结点差异OneDrive API Endpoint Differences

可从多个不同的 API 终结点获取 OneDrive API。 Microsoft Graph 是访问 OneDrive 个人版、OneDrive for Business 和 SharePoint Online 文件的首选终结点。 在一些企业方案(如 SharePoint Server 2016)中,可能必须使用直接 API 终结点来访问 OneDrive for Business 和 SharePoint 数据,而不使用 Microsoft Graph。 下面详细说明了你可能会注意到的 Microsoft Graph 与直接 API 终结点差异。OneDrive API is available from several different API endpoints. Microsoft Graph is the preferred endpoint for accessing OneDrive personal, OneDrive for Business, and SharePoint online files. In some enterprise scenarios, like SharePoint Server 2016, it may be necessary to access OneDrive for Business and SharePoint data by using the direct API endpoint without using Microsoft Graph. The following notes provide details about differences you may notice between Microsoft Graph and the direct API endpoint.

差异:Differences:

命名空间Namespaces

方法Methods

使用直接终结点时,方法和操作名称必须有命名空间前缀。 例如,若要对直接终结点使用 sharedWithMe,必须在操作名称前面加上 oneDrive. 作为前缀。 请注意,此前缀区分大小写。When using the direct endpoint, methods and actions require a namespace prefix. For example, to use sharedWithMe on the direct endpoint, you must prefix the action name with oneDrive.. Note, this prefix is case-sensitive.

https://{server}/_api/v2.0/drive/oneDrive.sharedWithMe

使用直接终结点时,必须为以下操作或方法的名称加上前缀:The following actions or methods must be prefixed on the direct endpoint:

实例注释Instance annotations

返回的带 (@) 符号的项属性也包含命名空间。 使用 Microsoft Graph 时,命名空间始终为 microsoft.graph。 不过,如果访问的是直接 API 终结点,命名空间则不同。Properties on items returned with an at-sign (@) also include a namespace. When using Microsoft Graph, the namespace is always microsoft.graph. However, when accessing the direct API endpoint, the namespace is different.

已编档的属性名 (Microsoft Graph)Documented property name (Microsoft Graph) 直接 API 属性名Direct API property name
@microsoft.graph.downloadUrl @content.downloadUrl
@microsoft.graph.sourceUrl @content.sourceUrl
@microsoft.graph.conflictBehavior @name.conflictBehavior

属性名Property names

资源的一些属性名在从 Microsoft Graph 返回时会发生变化。 下表收录了对 Microsoft Graph 和 OneDrive API 不同的资源和属性名。Some property names on resources are changed when returned from Microsoft Graph. The following table contains resources and property names which are different between Microsoft Graph and OneDrive API.

已编档的属性名 (Microsoft Graph)Documented property name (Microsoft Graph) 直接 API 属性名Direct API property name
folder.viewfolder.view folder.folderViewfolder.folderView

发现终结点Discovering an endpoint

Microsoft Graph 为使用者和工作/学校帐户提供了一个 API 终结点(即 graph.microsoft.com)。 直接使用 OneDrive API 时,必须发现正确的 OneDrive API 终结点。Microsoft Graph provides a single API endpoint, graph.microsoft.com for consumer and work/school accounts. When using the OneDrive API directly, you must discover the correct OneDrive API endpoint.

若要发现正确的 OneDrive API 终结点,必须使用 Microsoft Graph。To discover the correct endpoint for OneDrive API, you must use Microsoft Graph.

OneDrive 个人版帐户OneDrive personal accounts

若要访问 OneDrive 个人版 OneDrive API,应用必须对所有请求使用 https://api.onedrive.com/v1.0 终结点。To access OneDrive API for OneDrive personal, your app must use the https://api.onedrive.com/v1.0 endpoint for all requests.

可以查看 id_tokentid: 9188040d-6c67-4c5b-b112-36a304b66dad,从而确定登录用户是否是 OneDrive 个人版用户。 若要详细了解如何执行此操作,请参阅 Active Directory v2 协议主题。You can determine if the signed in user is a OneDrive personal user by checking the id_token for tid: 9188040d-6c67-4c5b-b112-36a304b66dad. More information about this is available on the Active Directory v2 protocol topic.

OneDrive for Business 和 SharePointOneDrive for Business and SharePoint

若要访问 OneDrive for Business 的直接 API 终结点,应用必须先发现用户的“我的网站”URL。 可以向 Microsoft Graph 发出请求,以便返回此信息:To access the direct API endpoint for OneDrive for Business, your app must first discover the user's My Site URL. You can make a request to Microsoft Graph to return this information:

GET https://graph.microsoft.com/v1.0/me?$select=mySite
HTTP/1.1 200 OK
Content-Type: application/json

{
    "mySite": "https://contoso-my.sharepoint.com/personal/rgregg_contoso_com/"
}

然后,可以将 OneDrive API 的 API 路径 _api/v2.0/ 追加到此 URL 中,从而构造 API 终结点:You can then append the API path for the OneDrive API, _api/v2.0/ to this URL, to construct the API endpoint:

var apiEndPoint = response.mySite + '_api/v2.0';

在某些情况下,可能无法为工作/学校用户返回 mySite 值。 当帐户尚未创建 OneDrive for Business 时,就会发生这种情况。 如果是这样,应用需要通过 Microsoft Graph 请求获取驱动器的根文件夹,从而使用 Microsoft Graph 预配用户的 OneDrive。In some cases a work/school user may not have a mySite value returned. This occurs when the account has not created their OneDrive for Business yet. In this scenario, your app will need to use Microsoft Graph to provision the user's OneDrive by requesting the root folder of the drive from Microsoft Graph.

权限Permissions

对于对 SharePoint 和 OneDrive for Business 的调用,可以通过 Office 365 SharePoint Online 服务经由 Azure 门户将这些权限范围分配给应用程序。 对于 OneDrive 个人版,直接将作用域字符串传递到 OAuth 工作流,而不需要提前注册。For calls to SharePoint and OneDrive for Business, you can assign these permission scopes to your application through the Azure Portal via the Office 365 SharePoint Online service. For OneDrive Personal, the scope string is passed into the OAuth workflow directly and do not need to be registered ahead of time.

Microsoft Graph 权限Microsoft Graph Permission OneDrive 个人版OneDrive Personal Sharepoint 和 OneDrive for BusinessSharePoint and OneDrive for Business
Files.ReadFiles.Read OneDrive.ReadOneDrive.Read MyFiles.ReadMyFiles.Read
Files.ReadWriteFiles.ReadWrite OneDrive.ReadWriteOneDrive.ReadWrite MyFiles.WriteMyFiles.Write
Files.ReadWrite.AllFiles.ReadWrite.All OneDrive.ReadWriteOneDrive.ReadWrite Files.ReadWrite.AllFiles.ReadWrite.All
Files.ReadWrite.AppFolderFiles.ReadWrite.AppFolder OneDrive.AppFolderOneDrive.AppFolder Files.ReadWrite(Files.ReadWrite.AppFolder 当前不受支持Files.ReadWrite (Files.ReadWrite.AppFolder Not currently supported
Sites.Read.AllSites.Read.All 不适用N/A Sites.Read.AllSites.Read.All
Sites.ReadWrite.AllSites.ReadWrite.All 不适用N/A Sites.ReadWrite.AllSites.ReadWrite.All