diff --git a/powerapps-docs/developer/common-data-service/TOC.yml b/powerapps-docs/developer/common-data-service/TOC.yml index 2baabd78a2..da4055d29e 100644 --- a/powerapps-docs/developer/common-data-service/TOC.yml +++ b/powerapps-docs/developer/common-data-service/TOC.yml @@ -412,6 +412,8 @@ href: xrm-tooling/ - name: Discover user organizations href: discovery-service.md + - name: Modify existing code to use the Discovery Web API + href: discovery-orgsdk-to-webapi.md - name: Best practices href: best-practices/index.md - name: Online Management API diff --git a/powerapps-docs/developer/common-data-service/discovery-orgsdk-to-webapi.md b/powerapps-docs/developer/common-data-service/discovery-orgsdk-to-webapi.md new file mode 100644 index 0000000000..6b7b9643fc --- /dev/null +++ b/powerapps-docs/developer/common-data-service/discovery-orgsdk-to-webapi.md @@ -0,0 +1,83 @@ +# Modify existing code to use Discovery Web API + +The Discovery Service Web API can be used to discover instances for your users. If you currently use Organization Service SDK to discover your instances, you can follow the steps in this document to start consuming the Web API. +A detailed description of the Web API can be found on the [Discovery Service Web API](/powerapps/developer/common-data-service/webapi/discover-url-organization-web-api) page. + +If you currently use the Web API, it is recommended that you make sure to point to the global Discovery service endpoint (https://globaldisco.crm.dynamics.com) of the Discovery service. +The rest of this document describes the changes that might be needed to use the Web API + +## Authentication +The Discovery Service Web API supports authentication with OAuth 2.0 access tokens. +If your code uses WS-Trust SAML tokens, you will need to change code acquire OAuth 2.0 token from Azure AD, and pass it to the Discovery Service Web API call. + +## OData API calls +The calls below are supported by the Web API. These follow the OData v4 standard and +The Instances API replaces both RetrieveOrganizations and RetrieveOrganization based on the desired scenario and returns the same data. + +- Get all instances for the user. +```http +GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances +``` +Response +```javascript +{ + "value":[ + { + "Id":"", + "UniqueName":"myorg", + "UrlName":"orgurlname", + "FriendlyName":"My Org", + "State":0, + "Version":"", + "Url":"https://orgurlname.crm.dynamics.com", + "ApiUrl":"https://orgurlname.api.crm.dynamics.com" + } + ] +} +``` + +- Get a single instance by id +```http +GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances() +``` +- Get a single instance by unique name +```http +GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(UniqueName='myorg') +``` + +Response +```javascript +{ + "Id":"", + "UniqueName":"myorg", + "UrlName":"orgurlname", + "FriendlyName":"My Org", + "State":0, + "Version":"", + "Url":"https://orgurlname.crm.dynamics.com", + "ApiUrl":"https://orgurlname.api.crm.dynamics.com" +} +``` + +## Mapping of fields +The fields from the response of the WCF discovery service endpoint can be mapped as below to the Web API endpoint, these are applicable to all above calls. + +Organization Service response field | Discovery Web API response field +------------------------------------|--------------------------------- +Endpoints[WebApplication] | Url +Endpoints[OrganizationService] | {ApiUrl}/XRMServices/2011/Organization.svc +Endpoints[OrganizationDataService] |{ApiUrl}//XRMServices/2011/OrganizationData.svc +FriendlyName|FriendlyName +OrganizationId|Id +OrganizationVersion|Version +State | State
  • 0: Enabled
  • 1: Disabled
      • +UniqueName|UniqueName +UrlName|UrlName + +## Deprecated API call +The Organization Service SDK call GetUserIdByExternalId is not supported in the Web API. + +## See Also +[Discovery Services](/powerapps/developer/common-data-service/discovery-service) + +[Use the Common Data Service Web API](/powerapps/developer/common-data-service/webapi/discover-url-organization-web-api) diff --git a/powerapps-docs/developer/common-data-service/discovery-service.md b/powerapps-docs/developer/common-data-service/discovery-service.md index 913e648f45..4c8a5ffed4 100644 --- a/powerapps-docs/developer/common-data-service/discovery-service.md +++ b/powerapps-docs/developer/common-data-service/discovery-service.md @@ -20,12 +20,15 @@ search.app: [!INCLUDE [cc-discovery-service-description](includes/cc-discovery-service-description.md)] -A Discovery service is accessed through either the Web API or the Organization Service. +A Discovery service is accessed through the Web API. - For the Web API: [Discover the URL for your organization using the Web API](webapi/discover-url-organization-web-api.md) - For the Organization Service: [Use the Discovery Service with the Microsoft.Xrm.Sdk.Discovery NameSpace](org-service/discovery-service.md) +> [!NOTE] +> The legacy Discovery service that was accessible via the Organization Service SDK has been deprecated along with the regional Discovery WebAPI endpoints. See [Important changes (deprecations)](/power-platform/important-changes-coming.md) for more details. + ### See Also [Use the Common Data Service Web API](webapi/overview.md)
      -[Use the Common Data Service Organization Service](org-service/overview.md) \ No newline at end of file +[Modify existing code to use Discovery Service Web API endpoint](discovery-orgsdk-to-webapi.md) diff --git a/powerapps-docs/developer/common-data-service/org-service/discovery-service.md b/powerapps-docs/developer/common-data-service/org-service/discovery-service.md index 79f62be689..24bf0c28da 100644 --- a/powerapps-docs/developer/common-data-service/org-service/discovery-service.md +++ b/powerapps-docs/developer/common-data-service/org-service/discovery-service.md @@ -17,6 +17,9 @@ search.app: --- # Use the Discovery Service with the SDK Assemblies +> [!IMPORTANT] +> Effective Decempber 1, 2019, the Discovery service that is accessible via the Organization Service SDK has been deprecated along with the regional Discovery WebAPI endpoints. More information: [Important changes (deprecations)](/power-platform/important-changes-coming/). See [Discovery WebAPI](/powerapps/developer/common-data-service/webapi/discover-url-organization-web-api) and [Modify existing code to use Discovery Web API](../discovery-orgsdk-to-webapi.md) for migration details. + [!INCLUDE [cc-discovery-service-description](../includes/cc-discovery-service-description.md)] diff --git a/powerapps-docs/developer/common-data-service/webapi/discover-url-organization-web-api.md b/powerapps-docs/developer/common-data-service/webapi/discover-url-organization-web-api.md index a5520d9228..32d329b67e 100644 --- a/powerapps-docs/developer/common-data-service/webapi/discover-url-organization-web-api.md +++ b/powerapps-docs/developer/common-data-service/webapi/discover-url-organization-web-api.md @@ -25,28 +25,24 @@ search.app: [!INCLUDE [cc-discovery-service-description](../includes/cc-discovery-service-description.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. - +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. -## Global discovery service - -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) +## Discovery service > [!NOTE] -> 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`). -> -> 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). +> The regional Discovery service Web API endpoints are deprecated and users must switch to using the global Discovery service endpoint (documented in this page). +> For Dynamics 365 US Government users, a global Discovery Web API 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). -## Information provided by the Discovery service +## Information provided by the Discovery service Web API - 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. +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. ```http -GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg') +GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(UniqueName='myorg') ``` -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. +In the above example, the 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. @@ -87,29 +83,22 @@ The Discovery service Web API supports the CORS standard for cross-origin access - Get the details of a specific instance. If you leave out the GUID, all instances that the authenticated user has access to are returned. ```http - GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances() - GET https://disco.crm.dynamics.com/api/discovery/v9.0/Instances() + GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances() ``` - You can use the UniqueName attribute as an alternate key. ```http - GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg') + GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances(UniqueName='myorg') ``` - Retrieve a list of available instances, filtered by production type. ```http - GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0 + GET https://globaldisco.crm.dynamics.com/api/discovery/v2.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0 ``` -- Retrieve a specific instance's ID property value. - - ```http - GET https://disco.crm.dynamics.com/api/discovery/v9.0/Instances(UniqueName='myorg')/Id/$value - ``` - ## See also -[Web API Global Discovery Service sample (C#)](samples/global-discovery-service-csharp.md) +[Web API Discovery Service sample (C#)](samples/global-discovery-service-csharp.md) diff --git a/powerapps-docs/developer/common-data-service/webapi/samples/global-discovery-service-csharp.md b/powerapps-docs/developer/common-data-service/webapi/samples/global-discovery-service-csharp.md index 06610b4fb0..791dc9758e 100644 --- a/powerapps-docs/developer/common-data-service/webapi/samples/global-discovery-service-csharp.md +++ b/powerapps-docs/developer/common-data-service/webapi/samples/global-discovery-service-csharp.md @@ -15,9 +15,9 @@ search.app: - PowerApps - D365CE --- -# Web API Global Discovery Service Sample (C#) +# Discovery Service Web API Sample (C#) -This sample shows how to use the Web API Global discovery Service +This sample shows how to use the Discovery Service Web API ## How to run this sample @@ -34,13 +34,13 @@ Instead, it will just use the user credentials and the clientid. ### Demonstrates -This sample uses a HttpClient to authenticate using ADAL (v2.29) and call the global discovery service to return information about available instances the user can connect to. +This sample uses a HttpClient to authenticate using ADAL (v2.29) and call the Discovery service to return information about available instances the user can connect to. The sample depends on the `GetInstances` method and the `Instance` class below: ```csharp /// - /// Uses the global web api discovery service to return instances + /// Uses the web api discovery service to return instances /// /// The Azure AD client (app) registration /// The user name