使用 Web API 发现组织的 URL

项目
07/06/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

Microsoft Dynamics 365 Web API 的发现服务使您的应用程序能够在运行时确定登录的用户所属的组织，也称为实例。您可以检索有关这些实例的详细信息，例如实例服务 URL、Dynamics 365 发行版本、实例 ID 等。您可以对 Web API 服务请求使用标准 $filter 和 $select 自定义实例数据的返回列表。发现服务受所有 Dynamics 365 部署类型的支持：联机、本地和 IFD。

客户端应用程序可能需要实例 URL 可能随着时间的推移而更改的 Dynamics 365 实例的访问权限。例如，当一个 Dynamics 365 实例从一个 Microsoft Dynamics 365 (online) 数据中心移到另一个时。发现服务允许客户端实例继续保留实例 ID 或实例的唯一名称，再使用发现服务查找当前实例的访问 URL。

除了数据中心特定发现服务，这可在 2011 (SOAP) 终结点，并且通过 Web API 可用，还提供了跨所有操作数据中心的 Web API 仅全局发现服务。有关 2011 终结点上的发现服务的详细信息，请参阅使用组织服务发现您的组织的 URL。

发现服务提供的信息

组织信息存储在发现服务的 Instance 实体中。若要查看该实体中包含的信息类型，请发送 HTTP GET 请求至其中一个实例的服务。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

在上面的示例中，Microsoft Dynamics 365 (online) 全局发现服务用于获取唯一名称为“myorg”的实例的组织信息。有关此请求的详细信息稍后将在此主题中加以扩展。

返回信息的范围

有关全局发现服务，Instances 实体集，返回用户在不使用筛选器时在所有地域均可访问的实例集。返回的数据具有以下描述的范围。

包含对用户配置和启用的商务云中的所有实例，但未返回自主云实例。
不包括禁用用户帐户的实例
不包括基于实例安全组筛选掉用户的实例
不包括用户作为委派管理员而具有访问权限的实例
如果调用用户没有任何实例的访问权限，则响应仅返回一个空列表

如何访问发现服务

一般来说，发现服务 Web API 地址具有以下格式：<service base address>/api/discovery/。每个部署类型的地址确定如下。您可用通过导航到“设置 > 自定义 > 开发人员资源”在 Dynamics 365 Web 应用程序中轻松找到部署的 Web API 地址和版本号

Dynamics 365（联机）发现服务

全局发现服务的服务基址是：https://globaldisco.crm.dynamics.com/。这会导致 https://globaldisco.crm.dynamics.com/api/discovery/ 服务地址。

数据中心发现服务的服务基址是：https://disco.crm[N].dynamics.com/。这会导致 https://disco.crm[N].dynamics.com/api/discovery/ 发现服务地址。每个数据中心都有一个与之关联的 N 号码。有关可用 Microsoft Dynamics 365 (online) 数据中心的完整列表及其 N 号码，请参阅使用 Microsoft Dynamics 365 开发人员资源页面下载终结点。

本地和 IFD 发现服务

本地或 IFD 部署发现服务的服务基址是：http[s]://{servername}/ 或 http[s]://dev.{servername}/。这会导致 http[s]://{servername}/api/discovery/ 或 http[s]://dev.{servername}/api/discovery/ 服务地址。

使用发现服务

名为 Instances 的实体集用于获取实例信息。您可以将 $select 和 $filter 与实例实体集一起使用来筛选返回的数据。还可以使用 $metadata 获取服务的元数据文档。

身份验证

Microsoft Dynamics 365 (online) 发现服务的 Web API 实例要求使用 OAuth 访问令牌进行身份验证。本地或 IFD 发现 Web API 实例采用其部署的身份验证模式，支持集成 Windows 身份验证 (IWA) 或受信任的令牌提供商的 OAuth 令牌。 Web 应用程序会话身份验证不受支持。

发现服务配置为 OAuth 身份验证时，向服务 Web API 发送的不具有访问令牌的请求触发持有者挑战“通用”终结点和服务资源 ID 的权威。同样，本地部署配置为 OAuth 时，持有者挑战返回本地权威 URL 和服务资源 ID。

Web API 版本控制

数据中心或本地/IFD的发现服务版本控制受组织服务使用的版本编号的支持并与之保持一致。但是，Microsoft Dynamics 365 (online) 的全局发现服务尚未关联到 Dynamics 365 部署的版本号。相反，全局服务使用自己的版本编号。截至本文件编制日期为止，Microsoft Dynamics 365 (online) 的全局发现服务为版本 1.0 (v1.0)。例如：

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

CORS 支持

发现服务 Web API 同组织服务 Web API 一样支持跨起源访问的 CORS 标准。有关 CORS 支持的详细信息，请参阅使用 OAuth 和跨源资源共享将单页应用程序连接到 Microsoft Dynamics 365。

示例

获取特定实例的详细信息。如果您忽略 GUID，则经过身份验证的用户有权访问的所有实例都将返回。

GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(<guid>)
GET https://dev.crm.external.contoso.com/api/discovery/v8.1/Instances(<guid>)

您可以使用 UniqueName 属性作为备用键。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')

检索按照生产类型筛选的可用实例的列表。

GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0

检索特定实例的 ID 属性值。

GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value

Microsoft Dynamics 365