You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Discovery Service is accessed through two different APIs:
22
23
23
-
A Discovery service is accessed through either the Web API or the Organization Service.
24
+
- For the OData V4 RESTful API: [Discover the URL for your organization](webapi/discover-url-organization-web-api.md)
25
+
- For the discovery API available through the 2011 (SOAP) endpoint: [Use the Discovery Service with the Microsoft.Xrm.Sdk.Discovery NameSpace](org-service/discovery-service.md)
24
26
25
-
- For the Web API: [Discover the URL for your organization using the Web API](webapi/discover-url-organization-web-api.md)
26
-
- For the Organization Service: [Use the Discovery Service with the Microsoft.Xrm.Sdk.Discovery NameSpace](org-service/discovery-service.md)
27
+
> [!NOTE]
28
+
> The *regional* Discovery Service is deprecated. More information: [Important changes (deprecations)](/power-platform/important-changes-coming.md).
27
29
28
30
### See Also
29
31
30
32
[Use the Common Data Service Web API](webapi/overview.md)<br />
31
-
[Use the Common Data Service Organization Service](org-service/overview.md)
33
+
[Modify your code to use global Discovery Service](webapi/discovery-orgsdk-to-webapi.md)
Copy file name to clipboardExpand all lines: powerapps-docs/developer/common-data-service/org-service/discovery-service.md
+12-8Lines changed: 12 additions & 8 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,14 @@
1
1
---
2
2
title: "Use the Discovery Service with the SDK Assemblies (Common Data Service) | Microsoft Docs"# Intent and product brand in a unique string of 43-59 chars including spaces
3
-
description: "Describes how to use the discovery service with the .NET SDK assemblies."# 115-145 characters including spaces. This abstract displays in the search result.
3
+
description: "Describes how to use the Discovery Service with the APIs available in the SDK assemblies."# 115-145 characters including spaces. This abstract displays in the search result.
4
4
ms.custom: ""
5
-
ms.date: 10/31/2018
6
-
ms.reviewer: ""
5
+
ms.date: 1/16/2020
6
+
ms.reviewer: "pehecke"
7
7
ms.service: powerapps
8
8
ms.topic: "article"
9
9
author: "JimDaly"# GitHub ID
10
10
ms.author: "jdaly"# MSFT alias of Microsoft employees only
11
-
manager: "ryjones"# MSFT alias of manager or PM counterpart
11
+
manager: "kvivek"# MSFT alias of manager or PM counterpart
12
12
search.audienceType:
13
13
- developer
14
14
search.app:
@@ -17,10 +17,14 @@ search.app:
17
17
---
18
18
# Use the Discovery Service with the SDK Assemblies
> Effective March 2, 2020, the *regional* Discovery Service will be [deprecated](/power-platform/important-changes-coming#regional-discovery-service-is-deprecated).
22
+
>
23
+
> For information on how to transition to use the *global* Discovery Service, see [Modify your code to use global Discovery Service](../webapi/discovery-orgsdk-to-webapi.md).
To use the discovery service using the SDK assemblies, add a reference to the `Microsoft.Xrm.Sdk.dll` assembly to your Visual Studio project, and then add a `using` statement to access the <xref:Microsoft.Xrm.Sdk.Discovery> namespace.
27
+
To access the Discovery Service using the SDK assembly APIs, add a reference to the `Microsoft.Xrm.Sdk.dll` assembly in your Visual Studio project, and then add a `using` statement to access the <xref:Microsoft.Xrm.Sdk.Discovery> namespace.
24
28
25
29
The <xref:Microsoft.Xrm.Sdk.WebServiceClient.DiscoveryWebProxyClient> implements the <xref:Microsoft.Xrm.Sdk.Discovery.IDiscoveryService> interface.
26
30
@@ -33,7 +37,7 @@ When you instantiate the <xref:Microsoft.Xrm.Sdk.WebServiceClient.DiscoveryWebPr
> If you do not know the user's region, you need to loop through the available regions until you get results. The Web API provides a single global discovery service. More information: [Discover the URL for your organization using the Web API](../webapi/discover-url-organization-web-api.md)
40
+
> If you do not know the user's region, you need to loop through the available regions until you get results. A single global Discovery Service is also available. More information: [Discover the URL for your organization](../webapi/discover-url-organization-web-api.md)
With the Web API discovery service, you can use standard `$filter` and `$select` parameters to a Web API service request to customize the returned list of instance data.
29
-
<!-- TODO should only talk about the global discovery service -->
28
+
When accessing the Discovery Service using the OData V4 RESTful API, you can add standard `$filter` and `$select` parameters to the service request to customize the returned list of instance data.
30
29
31
-
## Global Discovery service
32
-
33
-
In addition to datacenter specific Discovery services, that are available on the 2011 (SOAP) endpoint and through the Web API, there is also a Web API only Global Discovery service that spans all operational datacenters. For more information about the Discovery service on the 2011 endpoint see [Discovery Service](../org-service/discovery-service.md)
34
-
35
-
> [!NOTE]
36
-
> It is recommended that users switch from the legacy regional discovery service (`https://disco.crm.dynamics.com`) to global discovery service (`https://globaldisco.crm.dynamics.com`).
37
-
>
38
-
> For Dynamics 365 US Government users, the global discovery service is available for the **GCC** and **GCC High** users, and the URL is different from the regular global discovery service URL. More information: [Dynamics 365 Government URLs](https://docs.microsoft.com/dynamics365/customer-engagement/admin/government/microsoft-dynamics-365-government#dynamics-365-us-government-urls).
30
+
> [!IMPORTANT]
31
+
> - Effective March 2, 2020, the *regional* Discovery Service will be [deprecated](/power-platform/important-changes-coming#regional-discovery-service-is-deprecated). Applications must use the global Discovery Service that is documented in this topic.
32
+
> - For Dynamics 365 US Government users, a *global* Discovery Service endpoint is available for the **GCC** and **GCC High** users, and the URL is different from the regular global Discovery Service URL. More information: [Dynamics 365 Government URLs](https://docs.microsoft.com/dynamics365/customer-engagement/admin/government/microsoft-dynamics-365-government#dynamics-365-us-government-urls).
39
33
40
34
41
-
## Information provided by the Discovery service
35
+
## Information provided by the Discovery Service
42
36
43
-
Organization information is stored in the `Instance` entity of the Discovery service. To see the kind of information contained in that entity, send an HTTP GET request to the service for one of your instances.
37
+
Organization information is stored in the `Instance` entity of the Discovery Service. To see the kind of information contained in that entity, send an HTTP GET request to the service for one of your instances.
44
38
45
39
```http
46
40
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(UniqueName='myorg')
47
41
```
48
42
49
-
In the above example, the global Discovery service of Common Data Service is used to obtain the organization information of the instance with a unique name of "myorg". More details about this request is expanded upon later in this topic.
43
+
In the above example, the global Discovery Service is used to obtain the organization information of the instance with a unique name of "myorg". More details about this request is provided later in this topic.
50
44
51
-
52
-
53
-
54
45
### Scope of the returned information
55
46
56
-
For the global Discovery service, the `Instances` entity set, returns the set of instances that the user has access to across all geographies, when no filters are applied. The returned data has a scope as described below.
47
+
For the global Discovery Service, the `Instances` entity set, returns the set of instances that the user has access to across all geographies, when no filters are applied. The returned data has a scope as described below.
57
48
58
49
- Includes all instances in the commercial cloud where the user is provisioned and enabled, except sovereign clouds instances are not returned
59
50
- Does not include instances where the user's account is disabled
60
51
- Does not include instances where users have been filtered out based on an instance security group
61
52
- Does not include instances where the user has access as a result of being a delegated administrator
62
53
- If the calling user has access to no instances, the response simply returns an empty list
63
54
64
-
## How to access the Discovery services
55
+
## How to access the Discovery Service
65
56
66
-
In general, the Web API address of the Discovery service has the following format: `<service base address>/api/discovery/`. The addresses for each deployment type are identified below. You can easily find the Web API addresses and version number for your deployment in the Common Data Service web application by navigating to **Settings > Customization > Developer Resources**
57
+
In general, the Web address of the Discovery Service has the following format: `<service base address>/api/discovery/`. You can easily find the Web address and version number for your deployment in the Common Data Service Web application by navigating to **Settings > Customization > Developer Resources**
67
58
68
59
### Common Data Service Discovery services
69
60
70
-
The service base address of the global Discovery service is : `https://globaldisco.crm.dynamics.com/`. This results in the service address of `https://globaldisco.crm.dynamics.com/api/discovery/`.
61
+
The service base address of the global Discovery Service is : `https://globaldisco.crm.dynamics.com/`. This results in the service address of `https://globaldisco.crm.dynamics.com/api/discovery/`.
71
62
72
63
## Using the Discovery service
73
64
74
65
An entity set named `Instances` is used to obtain instance information. You can use `$select` and `$filter` with the Instances entity set to filter the returned data. You can also use `$metadata` to obtain the metadata document of the service.
75
66
76
67
### Authentication
77
68
78
-
Common Data Service Web API instances of the Discovery service require authentication with OAuth access tokens.
69
+
Accessing the Discovery Service requires authentication with an OAuth access token.
70
+
71
+
When the Discovery Service is configured for OAuth authentication, a request sent to the service without an access token triggers a bearer challenge with the authority of the “common” endpoint and the resource ID of the service.
79
72
80
-
When the Discovery service is configured for OAuth authentication, a request sent to the service Web API without an access token triggers a bearer challenge with the authority of the “common” endpoint and the resource ID of the service.
81
73
### CORS support
82
74
83
-
The Discovery service Web API supports the CORS standard for cross-origin access as does the Web API. For more information about CORS support see [Use OAuth with Cross-Origin Resource Sharing to connect a Single Page Application](../oauth-cross-origin-resource-sharing-connect-single-page-application.md).
75
+
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](../oauth-cross-origin-resource-sharing-connect-single-page-application.md).
84
76
85
77
### Examples
86
78
87
79
- Get the details of a specific instance. If you leave out the GUID, all instances that the authenticated user has access to are returned.
88
80
89
81
```http
90
82
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(<guid>)
91
-
GET https://disco.crm.dynamics.com/api/discovery/v9.0/Instances(<guid>)
92
83
```
93
84
94
85
- You can use the UniqueName attribute as an alternate key.
@@ -103,13 +94,7 @@ The Discovery service Web API supports the CORS standard for cross-origin access
103
94
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0
104
95
```
105
96
106
-
- Retrieve a specific instance's ID property value.
107
-
108
-
```http
109
-
GET https://disco.crm.dynamics.com/api/discovery/v9.0/Instances(UniqueName='myorg')/Id/$value
110
-
```
111
-
112
97
## See also
113
98
114
-
[Web API Global Discovery Service sample (C#)](samples/global-discovery-service-csharp.md)
99
+
[Discovery Service sample (C#)](samples/global-discovery-service-csharp.md)
title: "Modify your code to use global Discovery Service (Common Data Service) | Microsoft Docs"# Intent and product brand in a unique string of 43-59 chars including spaces
3
+
description: "Update your application code to make Discovery Service calls using a modern RESTful API."
4
+
ms.custom: ""
5
+
ms.date: 1/16/2020
6
+
ms.reviewer: "pehecke"
7
+
ms.service: powerapps
8
+
ms.topic: "article"
9
+
author: "bpevans"# GitHub ID
10
+
ms.author: "bevans"# MSFT alias of Microsoft employees only
11
+
manager: "kvivek"# MSFT alias of manager or PM counterpart
12
+
search.audienceType:
13
+
- developer
14
+
search.app:
15
+
- PowerApps
16
+
- D365CE
17
+
---
18
+
19
+
# Modify your code to use global Discovery Service
20
+
21
+
The Discovery Service APIs can be used by your application to discover business organization instances that the application user has access to. If your application currently uses the Organization Service API on the 2011 SOAP endpoint to discover organization instances, you can follow the steps in this topic and convert your application to access organization details using the OData V4 RESTful API with the global Discovery Service URL. If your application accesses the Discovery Service using the regional Discovery Service URL, you will need to change the application code from using the regional URL to the global Discovery Service URL.
22
+
23
+
A detailed description of using the Discovery Service with the RESTful API can be found on the [Discover the URL for your organization](/powerapps/developer/common-data-service/webapi/discover-url-organization-web-api) page.
24
+
25
+
> [!IMPORTANT]
26
+
> When accessing the Discovery Service, it is strongly recommended that your application use the *global* Discovery Service endpoint (https://globaldisco.crm.dynamics.com) and not the *regional* Discovery Service endpoint, which is [deprecated](/power-platform/important-changes-coming#regional-discovery-service-is-deprecated). The global Discovery Service is only available when using the RESTful API.
27
+
28
+
The rest of this document describes the changes that may be needed to call the Discovery Service using the RESTful API.
29
+
30
+
## Authentication
31
+
Accessing the Discovery Service using the RESTful API requires authentication with an OAuth 2.0 access token.
32
+
If your application code uses WS-Trust SAML tokens for authentication, you need to change your application code to acquire an OAuth 2.0 token from Azure Active Directory (AD), and then add that token in the Authorization header of the Discovery Service API calls. More information: [Use OAuth with Common Data Service](../authenticate-oauth.md).
33
+
34
+
## OData API calls
35
+
The example HTTP requests shown below are supported by the Discovery Service RESTful API. These examples use the Instances API to return the same organization data as the <xref:Microsoft.Xrm.Sdk.Discovery.RetrieveOrganizationsRequest> and <xref:Microsoft.Xrm.Sdk.Discovery.RetrieveOrganizationRequest> message requests of the Organization Service API.
36
+
37
+
- Get all instances for the user in all regions.
38
+
```http
39
+
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances
40
+
```
41
+
- Get all instances for the user in a specific region.
42
+
```http
43
+
GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(Region={region})
The table shown below shows the field mapping in the responses returned from the Discovery Service when using the two APIs. These are applicable to all above example calls.
88
+
89
+
Response field (SOAP endpoint) | Response field (OData V4 RESTful endpoint)
0 commit comments