发现服务 REST API 参考

项目
06/05/2018

适用于：Office 365

备注

自2018年1月10日起不推荐使用 Office 365 发现服务和SDK for .NET ，并将在 2019年11月1日完全退出使用。开始使用 Microsoft Graph 访问单个端点中的 Office 365 数据。有关详细信息，请参阅我们的通知。

使用 Office 365 发现服务

要与发现服务 API 进行交互，请发送 HTTP 和 OData 请求。发现服务支持发现日历、联系人、邮件、我的文件（适用于 OneDrive 和 OneDrive for Business 服务端点），笔记（适用于 OneNote）以及 RootSite（适用于 SharePoint）。

发现服务的资源 ID：ResourceId = https://api.office.com/discovery/。

有关如何使用发现服务 API 查找使用 Office 365 API 访问的服务端点的代码示例，请参阅Office 365 API：如何使用发现服务和 Office 365 发现服务示例。

备注

发现服务仅为 Office 365 联机环境提供功能，不适用于本地部署。

版本控制

以下是发现服务的版本。

发现服务 API 端点	说明
https://api.office.com/discovery/v1.0/me	支持 Office 365 API 发布版本每个服务的单个 API 端点。默认返回 OData v4（https://www.odata.org/documentation/odata-version-4-0/) 。
https://api.office.com/discovery/v2.0/me	支持 Office 365 API 发布版本每个服务的多个 API 端点。默认返回 OData v4（https://www.odata.org/documentation/odata-version-4-0/) 。

发现服务操作

其让客户端进入用户输入帐户信息的网页。它将返回继续发现服务所需的端点。这是用户第一次尝试您的应用程序时使用的。

它告诉您的应用程序：

用户属于哪个云端
应用程序让用户在哪里登录
去哪里获取令牌

参数	类型	说明
`scope`	字符串	以空格分隔的 capability.operation 令牌列表。这是 Office 365 条款中的作用域。实例：我的文件、写邮件或发送邮件、阅读信息
`redirect_uri`	字符串	授权完成后重定向到的 URI。示例： https://contoso.com/continue
`lcid`	字符串	可选。用于本地化电子邮件 HRD UI 的十进制 LCID。示例：1031 注意此 API 无意接受用户电子邮件，因为这可能会在当前域之外发送用户电子邮件，从而危害用户隐私。

响应	说明
`302` 已找到	响应正文包含有关应用程序和用户的值

响应正文项	说明
位置：重定向_URI	授权完成后重定向到的 URI。
?用户_电子邮箱=...	用户输入的电子邮件地址。
&账户 _ 类型 = ...	1 – Microsoft 帐户 (Live) 2 - 组织帐户（Office 365）
&授权 _ 服务 = ...	客户端可在其中获取授权代码的终结点 URL。
&令牌 _ 服务 = ...	客户端可交换授权代码以获取访问令牌和刷新令牌的终结点 URL。
&作用域=...	原始作用域翻译为目标领域。客户只需要知道 Office 365 作用域条款。如果目标领域为 Live，则原始的 Office 365 作用域将转换为 Live 条款。
&未支持_作用域 = ...	如果存在无法翻译的作用域项目，则它们将被编译到未支持_作用域中而不会发生变化。这是必要的，因为每个授权服务仅以其自己的术语理解作用域。由于 off365short 授权服务不接受作用域参数，所以作用域和未支持_作用域将返回为空。
&发现_服务 = ...	客户端可以发现目标服务的终结点 URL。
&发现_资源 = ...	发现服务的资源标识。必须作为发现服务的令牌请求的一部分传递到令牌服务。

备注

所有这些信息对于此用户帐户都是静态的。因此客户端应将其缓存，然后重新使用以避免用户使用不必要的 UI 造成烦扰。

示例

var firstSignInUri = new Uri(string.Format("https://api.office.com/discovery/v1.0/me/FirstSignIn?redirect_uri={0}&scope={1}", TerminalUriText, Scope));
var terminalUri = new Uri(TerminalUriText);

//Starting authorization
var webAuthResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, firstSignInUri, terminalUri)
   .AsTask().ConfigureAwait(continueOnCapturedContext: true);

//Authorization finished
If (webAuthResult.ResponseStatus == WebAuthenticationStatus.Success)
{
var userEmail = MyExtractParamter("user_email",webAuthResult.ResponseData);
var accountType = MyExtractParamter("account_type",webAuthResult.ResponseData);
var authorizationService = MyExtractParamter("authorization_service",webAuthResult.ResponseData);
var tokenService = MyExtractParamter("token_service", webAuthResult.ResponseData);
var discoveryService = MyExtractParamter("discovery_service", webAuthResult.ResponseData);
var scope = MyExtractParamter("scope",webAuthResult.ResponseData);
var unsupportedScope = MyExtractParamter("unsupported_scope", webAuthResult.ResponseData);

MyCacheUserInfo(...);
}

发现特定的服务

使用 /服务API 获得特定服务的端点。

标头	说明
`Authorization`	在授权阶段获取的访问令牌。示例：授权：BEARER 2YotnFZFEjr1zCsicMWpAA ...
`Accept`	可选。此标头控制响应有效负载的格式：对于 Atom：application/atom+xml 对于 JSON：application/json;odata=verbose 如果省略此标头，则默认为 Atom。实例：接受：application/json；odata=verbose

参数	类型	说明
`$select`	字符串	可选。对象属性的逗号分隔列表。使服务仅投影选定的属性。它用于通过不下载应用程序未使用的属性来节省带宽。请参阅 https://www.odata.org/docs/。例如：Capability，ServiceUri
`$filter`	字符串	可选。一个 OData 谓词，用于过滤原始结果集。不下载应用程序未使用的对象实例，用于节省带宽。可参阅位于可用谓词函数的 Documentation 选项卡下的 https://www.odata.org 。

响应	含义	说明
`200`	确定	响应主体包含一个根据 OData 请求预测、过滤和编码的 ServiceInfo 架构条目列表。可参阅 ServiceInfo schema 架构的定义。

示例

var url = string.Format("https://api.office.com/discovery/v1.0/me/services", discoveryService);

var request = HttpWebRequest.CreateHttp(url);
request.Method = "GET";
request.Headers["Authorization"] = "Bearer " + accessToken;

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

了解可以发现哪些服务

使用 /AllServices API 以了解所有可发现的功能和实现功能的服务。 / AllServices 接受匿名请求，因此不需要访问令牌。

标头	说明
`Accept`	可选。此标头控制响应有效负载的格式：对于 Atom：application/atom+xml 对于 JSON：application/json;odata=verbose 如果省略此标头，则默认为 Atom。实例：接受：application/json；odata=verbose

参数	类型	说明
`$select`	字符串	可选。对象属性的逗号分隔列表。使服务仅投影选定的属性。它用于通过不下载应用程序未使用的属性来节省带宽。请参阅 https://www.odata.org/docs/。例如：Capability，ServiceUri
`$filter`	字符串	可选。一个 OData 谓词，用于过滤原始结果集。不下载应用程序未使用的对象实例，用于节省带宽。可参阅位于可用谓词函数的 Documentation 选项卡下的 https://www.odata.org 。

响应	含义	说明
`200`	确定	响应主体包含一个根据 OData 请求预测、过滤和编码的 ServiceInfo 架构条目列表。可参阅 ServiceInfo schema 架构的定义。

示例

var request = HttpWebRequest.CreateHttp("https://api.office.com/discovery/v1.0/me/services");
request.Method = "GET";
request.Headers["Accept"] = "application/json;odata=verbose";

var response = await request.GetResponseAsync().ConfigureAwait(continueOnCapturedContext: true) as HttpWebResponse;

ServiceInfo 架构

/services API 和 /allservices API API 在响应正文中使用 ServiceInfo 条目。

属性	类型	示例
性能	字符串	我的文件
服务 Id	字符串
服务名称	字符串	O365_SHAREPOINT
服务端点 Uri	字符串	https://contoso-my.sharepoint.com/personal/alexd_contoso_com
服务资源 ld	字符串	https://contoso-my.sharepoint.com

通过

发现服务 REST API 参考

使用 Office 365 发现服务

版本控制

发现服务操作

示例

发现特定的服务

示例

了解可以发现哪些服务

示例

ServiceInfo 架构

另请参阅

其他资源

通过

发现服务 REST API 参考

使用 Office 365 发现服务

版本控制

发现服务操作

初始登录

示例

发现特定的服务

示例

了解可以发现哪些服务

示例

ServiceInfo 架构

另请参阅

其他资源