Редагувати

Discover user organizations

Your client application can connect to multiple Dataverse environments. Use the Global Discovery Service to find which environments the user of your application can access.

In Power Apps, you can select from a list of environments available to you. The Global Discovery Service is the source of that data. Within your own app, you can provide a select control to allow users to choose which environment they want to use. Their choice determines which environment your app must connect to.

With Dataverse, server and organization allocation can change as part of datacenter management and load balancing. Therefore, the Global Discovery Service provides a way to discover which server is serving an instance at a given time.

More information:

Global Discovery service

The Global Discovery service, sometimes called GDS, is a set of OData v4.0 endpoints that are available for five different clouds.

Note

While both the Dataverse Web API and the Global Discovery service are OData v4.0 endpoints, they're separate endpoints with different behaviors.

The following table provides the GDS location for each cloud.

Cloud URL and Description
Commercial https://globaldisco.crm.dynamics.com
Used by private sector companies. This cloud is the most commonly used cloud.
GCC https://globaldisco.crm9.dynamics.com
Government Community Cloud. Used by public sector employees and contractors in the United States.
USG https://globaldisco.crm.microsoftdynamics.us
Used by United States Federal government employees and contractors. Also known as GCC High.
DOD https://globaldisco.crm.appsplatform.us
Used by United States Department of Defense employees and contractors.
China https://globaldisco.crm.dynamics.cn
Used by companies in China to comply with regulatory requirements.

More information:

Limitations

The Global Discovery Service doesn't return information when:

  • The user's account is disabled.
  • An instance security group filters out the user.
  • The user gains access by being a delegated administrator.

If the calling user can't access any instances, the response returns an empty list.

Authentication

The calling user must get an OAuth 2.0 token from Microsoft Entra ID and add that token in the Authorization header of the API calls. For more information, see Use OAuth authentication with Microsoft Dataverse.

CORS support

The Discovery Service supports the CORS standard for cross-origin access. For more information about CORS support, see Use OAuth with Cross-Origin Resource Sharing to connect a Single-Page Application.

Use Insomnia to connect to the Global Discovery Service

Use the same approach described for the Dataverse Web API in Use Insomnia with Dataverse Web API. Instead of the environment variables described in that article, use the following variables to access the commercial cloud.

{
   "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"
}

In the Authorization tab, choose OAuth 2 and set or verify the following values:

Field Value
GRANT TYPE Implicit
AUTHORIZATION url _.authurl
CLIENTID _.clientid
REDIRECT URL _.redirecturl

Use GET _.globalDiscoUrl as the Request URL and select Send.

You can now query the Global Discovery Service by using Insomnia.

Service documents

To access the Global Discovery Service for each cloud, append /api/discovery/v2.0/ to the URL. Perform a GET request on this URL to view the service document, which contains only a single EntitySet: Instances.

Append $metadata to the cloud URL and send a GET request to view the CSDL (Common Schema Definition Language) service document. This XML document provides details on the Instance entity and the alternate keys defined for it.

Instance EntitySet

The following table describes the properties of the Instance Entity from the $metadata CDSL Service document.

Property Type Description
ApiUrl String The location of web services client applications should use.
DatacenterId String The Id of the data center where the instance is located.
DatacenterName String The name of the data center where the instance is located. This value is typically null.
EnvironmentId String The EnvironmentId for the instance.
FriendlyName String A name for the instance that is displayed in powerapps.com and other client applications that allow selecting instances.
Id Guid The OrganizationId for the environment.
IsUserSysAdmin Boolean Whether the calling user has the system administrator role for the environment.
LastUpdated DateTimeOffset When the environment was last updated.
OrganizationType Int32 The type of the organization. Values correspond to the OrganizationType EnumType
Purpose String Information for the purpose provided when the environment was created.
Region String A 2-3 letter code for region where the environment is located.
SchemaType String For internal use only.
State Int32 Whether the organization is 0:enabled or 1:disabled.
StatusMessage Int32 One of the following values:
0:InstanceLocked
1:PendingServiceInstanceMove
2:InstanceFailed
3:Provisioning
4:InActiveOrganizationStatus
5:NewInstance
6:InstancePickerReady
TenantId Guid The Id of the tenant associated to the instance
TrialExpirationDate DateTimeOffset The date when the trial period for the instance expires.
UniqueName String The Unique Name for the instance.
UrlName String The name used for the URL.
Version String The current version of the environment.
Url String The application url for the environment.

You can use these property names with the OData $select query parameter to retrieve just the data you need. In most cases, all you will need are the FriendlyName and ApiUrl properties. For example:

Request:

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

Response:

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"
    }
  ]
}

Use the FriendlyName property for your application UI so the user will recognize the name of the environment. Use the ApiUrl to connect to Dataverse.

The rest of the properties are primarily for filtering.

Filtering

You can filter the returned instances in two ways:

  • Use key values
  • Use OData $filter query options

Use key values

Use the Id or UniqueName value to filter the list and return only the specified instance.

Note

Unlike the Dataverse Web API, the Global Discovery Service doesn't support retrieving a specific Instance by using the Id or any of the alternate keys defined for it. GDS always returns an array of values.

Both of the following queries return an array with a single item:

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

You can also use any of the following alternate key values to filter on specific values: Region, State, Version. For example, use the following query to return only those instances where the Region is NA representing North America.

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

Use OData $filter query options

You can use OData $filter query options with any of the properties that apply, including the alternate key properties.

You can use the following comparison, logical, and grouping operators:

Operator Description Example
Comparison Operators
eq Equal $filter=IsUserSysAdmin eq true
ne Not Equal $filter=IsUserSysAdmin ne true
gt Greater than $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z
ge Greater than or equal $filter=TrialExpirationDate ge 2022-07-14T00:00:00Z
lt Less than $filter=TrialExpirationDate lt 2022-07-14T00:00:00Z
le Less than or equal $filter=TrialExpirationDate le 2022-07-14T00:00:00Z
Logical Operators
and Logical and $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z and IsUserSysAdmin eq true
or Logical or $filter=TrialExpirationDate gt 2022-07-14T00:00:00Z or IsUserSysAdmin eq true
not Logical negation $filter=not contains(Purpose,'test')
Grouping Operators
( ) Precedence grouping (contains(Purpose,'sample') or contains(Purpose,'test')) and TrialExpirationDate gt 2022-07-14T00:00:00Z

You can use the following string query functions:

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

Note

Unlike the Dataverse Web API, Global Discovery Service search strings are case sensitive.

Use Dataverse ServiceClient

For .NET applications, use Dataverse.Client.ServiceClient.DiscoverOnlineOrganizationsAsync Method to call the 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;

While the DiscoverOnlineOrganizationsAsync method uses the same OData endpoint and enables that it be passed in the discoveryServiceUri parameter, it doesn't return data in the shape of an Instance. It returns data as a DiscoverOrganizationsResult Class that includes a OrganizationDetailCollection Property which contains a collection of OrganizationDetail Class instances. This class contains the same information as the Instance types returned by the OData service.

Note

While the DiscoverOnlineOrganizationsAsync.discoveryServiceUri parameter accepts a URL to the Global Discovery Service, the method ignores any $select or $filter query options. The DiscoverOnlineOrganizationsAsync.discoveryServiceUri parameter is optional. If you don't provide it, the method defaults to the Commercial cloud.

Use CrmServiceClient

For .NET Framework applications, continue to use the CrmServiceClient.DiscoverGlobalOrganizations Method to call the 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();

Like the ServiceClient.DiscoverOnlineOrganizationsAsync method, the CrmServiceClient.DiscoverGlobalOrganizations method also doesn't return data as an Instance. It returns a OrganizationDetailCollection which contains a collection of OrganizationDetail Class instances. This collection contains the same information as the Instance types returned by the OData service.

See Also

Sample: Global Discovery Service Sample (C#)
Sample: Access the Discovery service using CrmServiceClient
Sample: Blazor WebAssembly with Global Discovery

  • Last updated on