发现用户组织

客户端应用程序可以连接到多个 Dataverse 环境。 使用全局发现服务查找应用程序用户可以访问的环境。

在Power Apps中，可以从可用的环境列表中选择。 全局发现服务是该数据的源。 在你自己的应用中，你可以提供一个选择控件，允许用户选择要使用的环境。 他们的选择决定了应用必须连接到的环境。

借助 Dataverse，服务器和组织分配可以在数据中心管理和负载均衡过程中发生更改。 因此，全局发现服务提供了一种方法来发现哪个服务器在给定时间为实例提供服务。

更多信息：

全局发现服务

全局发现服务（有时称为 GDS）是一组可用于五个不同的云的 OData v4.0 终结点。

注释

虽然 Dataverse Web API 和全局发现服务都是 OData v4.0 终结点，但它们是具有不同行为的单独终结点。

下表提供了每个云的 GDS 位置。

云 URL 和说明
商用 https://globaldisco.crm.dynamics.com
私营部门公司使用。 此云是最常用的云。
GCC https://globaldisco.crm9.dynamics.com
政府社区云。 由美国公共部门员工和承包商使用。
USG https://globaldisco.crm.microsoftdynamics.us
供美国联邦政府雇员和承包商使用。 也称作 GCC High。
DOD https://globaldisco.crm.appsplatform.us
由美国国防部员工和承包商使用。
China https://globaldisco.crm.dynamics.cn
由中国公司用来遵守监管要求。

更多信息：

局限性

全局发现服务在以下情况下不返回信息：

  • 用户帐户已禁用。
  • 实例安全组会筛选出用户。
  • 用户通过作为委派的管理员获得访问权限。

如果调用用户无法访问任何实例，响应将返回空列表。

Authentication

调用用户必须从Microsoft Entra ID获取 OAuth 2.0 令牌，并在 API 调用的 Authorization 标头中添加该令牌。 有关详细信息，请参阅将 OAuth 身份验证与Microsoft Dataverse配合使用。

CORS 支持

发现服务支持跨源访问的 CORS 标准。 有关 CORS 支持的详细信息，请参阅 将 OAuth 与跨域资源共享配合使用以连接 Single-Page 应用程序。

使用 Insomnia 连接到 Global Discovery Service

使用 将 Insomnia 与 Dataverse Web API 配合使用 中针对 Dataverse Web API 所述的相同方法。 使用以下变量来访问商业云，而不是本文中所述的环境变量。

{
   "cloudUrl": "https://globaldisco.crm.dynamics.com",
   "globalDiscoUrl": "{{cloudUrl}}/api/discovery/v2.0/",
   "redirecturl": "https://localhost",
   "authurl": "https://login.microsoftonline.com/common/oauth2/authorize?resource={{cloudUrl}}",
   "clientid": "51f81489-12ee-4a9e-aaae-a2591f45987d"
}

在 “授权 ”选项卡中，选择 OAuth 2 并设置或验证以下值：

领域 价值
授权类型 隐式
AUTHORIZATION URL _.authurl
CLIENTID _.clientid
重定向 URL _.redirecturl

用作GET _.globalDiscoUrl请求 URL 并选择“发送”。

现在，您可以使用 Insomnia 查询 Global Discovery Service。

服务单据

若要访问每个云的全局发现服务，请追加 /api/discovery/v2.0/ 到 URL。 对该 URL 发出 GET 请求以查看服务文档，其中仅包含一个 EntitySet：Instances。

追加 $metadata 到云 URL，并发送一个 GET 请求以查看 CSDL （公共架构定义语言） 服务文档。 此 XML 文档提供有关 Instance 实体及为其定义的备用键的详细信息。

实例实体集

下表介绍了 $metadata CDSL 服务文档中实体的属性 Instance 。

财产 类型 说明
ApiUrl String Web 服务客户端应用程序应使用的位置。
DatacenterId String 实例所在的数据中心的 ID。
DatacenterName String 实例所在的数据中心的名称。 此值通常为 null。
EnvironmentId String 实例的 EnvironmentId。
FriendlyName String 该实例的名称，该名称会显示在 powerapps.com 和其他允许选择实例的客户端应用程序中。
Id Guid 环境的 OrganizationId。
IsUserSysAdmin 布尔 呼叫用户是否具有环境的系统管理员角色。
LastUpdated DateTimeOffset 环境上次更新的时间。
OrganizationType Int32 组织的类型。 值对应于 OrganizationType EnumType
Purpose String 创建环境时提供的用途信息。
Region String 环境所在区域的 2-3 字母代码。
SchemaType String 仅供内部使用。
State Int32 该组织是0:启用还是1:禁用。
StatusMessage Int32 以下值之一：
0:InstanceLocked
1:PendingServiceInstanceMove
2:InstanceFailed
3:Provisioning
4:InActiveOrganizationStatus
5:NewInstance
6:InstancePickerReady
TenantId Guid 与实例关联的租户的 ID
TrialExpirationDate DateTimeOffset 实例的试用期到期的日期。
UniqueName String 实例的唯一名称。
UrlName String URL 使用的名称。
Version String 环境的当前版本。
Url String 该环境的应用程序 URL。

可以将这些属性名称与 OData $select 查询参数一起使用，以仅检索所需的数据。 在大多数情况下，你需要的就是属性 FriendlyName 和 ApiUrl 属性。 例如：

请求：

GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=ApiUrl,FriendlyName HTTP/1.1
Authorization: Bearer <truncated for brevity>

响应：

HTTP/1.1 200 OK
Content-Length: 625
Content-Type: application/json; odata.metadata=minimal
odata-version: 4.0

{
  "@odata.context":"https://10.0.1.76:20193/api/discovery/v2.0/$metadata#Instances(ApiUrl,FriendlyName)",
  "value":[
    {
      "ApiUrl":"https://yourorganization.api.crm.dynamics.com",
      "FriendlyName":"Your Organization"
    }
  ]
}

FriendlyName使用应用程序 UI 的属性，以便用户能够识别环境的名称。 使用 ApiUrl 连接到 Dataverse。

其余属性主要用于筛选。

Filtering

可以通过两种方式筛选返回的实例：

  • 使用键值
  • 使用 OData $filter 查询选项

使用键值

使用 Id 或 UniqueName 值筛选列表，并且仅返回指定的实例。

注释

与 Dataverse Web API 不同，全局发现服务不支持通过使用 Instance 或为该 Id 定义的任何备用键来检索特定的 Id。 GDS 始终返回值数组。

以下两个查询都返回包含单个项的数组：

GET https://globaldisco.crm.dynamics.com/Instances(6bcbf6bf-1f2a-4ab9-9901-2605b314d72d)?$select=ApiUrl,FriendlyName,Id,UniqueName

GET https://globaldisco.crm.dynamics.com/Instances(UniqueName='unq6bcbf6bf1f2a4ab999012605b314d')?$select=ApiUrl,FriendlyName,Id,UniqueName

还可以使用以下任一备用键值来筛选特定值：Region、、StateVersion。 例如，使用以下查询仅返回区域表示北美的 NA 实例。

GET https://globaldisco.crm.dynamics.com/Instances(Region='NA')?$select=FriendlyName,Region,State,Version,ApiUrl

使用 OData $filter 查询选项

您可以对任何适用的属性（包括替代键属性）使用 OData $filter 查询选项。

可以使用以下比较、逻辑和分组运算符：

Operator 说明 示例
比较运算符
eq Equal $filter=IsUserSysAdmin eq true
ne 不等于 $filter=IsUserSysAdmin ne true
gt 大于 $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z
ge 大于或等于 $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z
lt 小于 $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z
le 小于或等于 $filter=TrialExpirationDate le 2022-07-14T00:00:00Z
逻辑运算符
and 逻辑与 $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true
or 逻辑或 $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true
not 逻辑非 $filter=not contains(Purpose,'test')
分组运算符
( ) 优先分组 (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z

可以使用以下字符串查询函数：

Function 示例
contains $filter=contains(Purpose,'test')
endswith $filter=endswith(FriendlyName,'Inc.')
startswith $filter=startswith(FriendlyName,'A')

注释

与 Dataverse Web API 不同，全局发现服务搜索字符串区分大小写。

使用 Dataverse ServiceClient

对于.NET应用程序，请使用 Dataverse.Client.ServiceClient。DiscoverOnlineOrganizationsAsync 方法调用 Global Discovery Services。

 // Set up user credentials
var creds = new System.ServiceModel.Description.ClientCredentials();
creds.UserName.UserName = userName;
creds.UserName.Password = password;

//Call DiscoverOnlineOrganizationsAsync
DiscoverOrganizationsResult organizationsResult = await ServiceClient.DiscoverOnlineOrganizationsAsync(
        discoveryServiceUri: new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"),
        clientCredentials: creds,
        clientId: clientId,
        redirectUri: new Uri(redirectUrl),
        isOnPrem: false,
        authority: "https://login.microsoftonline.com/organizations/",
        promptBehavior: PromptBehavior.Auto);

return organizationsResult;

虽然 DiscoverOnlineOrganizationsAsync 方法使用相同的 OData 终结点，并支持将其传入 discoveryServiceUri 参数，但它返回的数据并不是 Instance 的形式。 它将数据作为 DiscoverOrganizationsResult 类 返回，该类包含 OrganizationDetailCollection 属性 ，该属性包含 OrganizationDetail 类 实例的集合。 此类包含的信息与 OData 服务返回的 Instance 类型相同。

注释

虽然参数 DiscoverOnlineOrganizationsAsync.discoveryServiceUri 接受全局发现服务的 URL，但该方法将忽略任何 $select 或 $filter 查询选项。 参数 DiscoverOnlineOrganizationsAsync.discoveryServiceUri 是可选的。 如果未提供，该方法默认为商业云。

使用 CrmServiceClient

对于 .NET Framework 应用程序，请继续使用 CrmServiceClient.DiscoverGlobalOrganizations 方法调用 Global Discovery Service。

  // Set up user credentials
  var creds = new System.ServiceModel.Description.ClientCredentials();
  creds.UserName.UserName = userName;
  creds.UserName.Password = password;

  // Call to get organizations from global discovery
  var organizations = CrmServiceClient.DiscoverGlobalOrganizations(
        discoveryServiceUri:new Uri($"{cloudRegionUrl}/api/discovery/v2.0/Instances"), 
        clientCredentials: creds, 
        user: null, 
        clientId: clientId,
        redirectUri: new Uri(redirectUrl), 
        tokenCachePath: "",
        isOnPrem: false,
        authority: string.Empty, 
        promptBehavior: PromptBehavior.Auto);

  return organizations.ToList();

与ServiceClient.DiscoverOnlineOrganizationsAsync方法一样，CrmServiceClient.DiscoverGlobalOrganizations方法也不会返回Instance形式的数据。 它返回一个 OrganizationDetailCollection ，其中包含 OrganizationDetail 类 实例的集合。 此集合包含的信息与 Instance OData 服务返回的类型相同。

另请参阅

示例：全局发现服务示例 （C#）
示例：使用 CrmServiceClient 访问发现服务
示例：带全局发现功能的 Blazor WebAssembly

  • Last updated on