Bepaal de URL voor uw organisatie met de Web-API

Artikel
07/06/2017

Gepubliceerd: januari 2017

Is van toepassing op: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Met de Discovery-service voor de web-API Microsoft Dynamics 365 kunnen uw toepassingen tijdens runtime bepalen tot welke organisaties (exemplaren) de aangemelde gebruiker behoort. U kunt gedetailleerde informatie over die exemplaren ophalen, zoals de service-URL van het exemplaar, de Dynamics 365-versie, de exemplaar-id en meer. U kunt de standaardparameters $filter en $select gebruiken in een serviceverzoek van een web-API om de geretourneerde lijst met exemplaargegevens aan te passen. De Discovery-service wordt ondersteund door alle Dynamics 365-implementatietypen: online, on-premises en IFD.

Clienttoepassingen hebben mogelijk toegang tot een Dynamics 365-exemplaar nodig waarvan de exemplaar-URL in de loop van de tijd kan veranderen. Dit gebeurt bijvoorbeeld wanneer een Dynamics 365-exemplaar van het ene naar het andere Microsoft Dynamics 365 (online)-datacentrum wordt verplaatst. Met de Discovery-service kunnen clientexemplaren de exemplaar-id of unieke naam van het exemplaar doorzetten en vervolgens de Discovery-service gebruiken om de toegangs-URL voor het huidige exemplaar op te zoeken.

Naast datacentrumspecifieke Discovery-services, die beschikbaar zijn op het 2011 SOAP-eindpunt en via de web-API, is er ook een globale Discovery-service die alleen via de web-API beschikbaar is en alle operationele datacentra omvat. Zie Bepaal de URL voor uw organisatie met de organisatieservice voor meer informatie over de Discovery-service op het 2011-eindpunt.

Informatie wordt geleverd door de Discovery-service

Organisatie-informatie wordt opgeslagen in de Instance-entiteit van de Discovery-service. Om te zien welk type informatie is opgenomen in die entiteit, verzendt u een HTTP GET-aanvraag naar de service voor een van uw exemplaren.

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

In het bovenstaande voorbeeld wordt de algemene Discovery-service van Microsoft Dynamics 365 (online) gebruikt om de bedrijfsgegevens van het exemplaar met een unieke naam 'myorg' te verkrijgen. Meer informatie over deze aanvraag vindt u verderop in dit onderwerp.

Bereik van de geretourneerde informatie

Voor de globale Discovery-service retourneert de entiteitset Instances de reeks exemplaren waartoe de gebruiker in alle regio's toegang heeft, wanneer geen filters worden toegepast. De geretourneerde gegevens hebben een bereik zoals hieronder wordt beschreven.

Bevat alle elementen in de commerciële cloud waarbij gebruiker wordt ingericht en ingeschakeld, alleen exemplaren van soevereine clouds worden niet geretourneerd
Omvat geen exemplaren waarvoor het account van de gebruiker is uitgeschakeld
Omvat geen exemplaren waarvoor gebruikers zijn uitgefilterd op basis van een exemplaarbeveiligingsgroep
Omvat geen exemplaren waarbij de gebruiker toegang heeft omdat deze een gedelegeerde beheerder is
Als de aanroepende gebruiker geen toegang tot exemplaren heeft, wordt er een lege lijst geretourneerd

Toegang tot de Discovery-services

Over het algemeen heeft het adres van de web-API van de Discovery-service de volgende indeling: <service base address>/api/discovery/. De adressen voor elk implementatietype worden hieronder aangegeven. U kunt de adressen van de web-API en het versienummer voor uw installatie eenvoudig in de webtoepassing Dynamics 365 vinden door te navigeren naar Instellingen > Aanpassing > Resources voor ontwikkelaars

Dynamics 365 (online) Discovery-services

Het basisadres van de globale Discovery-service is: https://globaldisco.crm.dynamics.com/. Dit resulteert in het serviceadres https://globaldisco.crm.dynamics.com/api/discovery/.

Het basisadres van de Discovery-service voor een datacentrum is: https://disco.crm[N].dynamics.com/. Dit resulteert in het Discovery-serviceadres https://disco.crm[N].dynamics.com/api/discovery/. Aan elk datacentrum is een n-nummer gekoppeld. Zie De eindpunten downloaden met de pagina Resources voor ontwikkelaars van Microsoft Dynamics 365 voor een volledige lijst met beschikbare Microsoft Dynamics 365 (online)-datacentra en hun N-nummers.

On-premises en IFD Discovery-service

Het basisadres van de Discovery-service voor een on-premises of IFD-installatie is: http[s]://{servername}/ of http[s]://dev.{servername}/. Dit resulteert in het serviceadres http[s]://{servername}/api/discovery/ of http[s]://dev.{servername}/api/discovery/.

Discovery-service gebruiken

Een entiteitset genaamd Instances wordt gebruikt om exemplaarinformatie te verkrijgen. U kunt $select en $filter gebruiken met de Exemplaren-entiteitsset om de geretourneerde gegevens te filteren. U kunt ook $metadata gebruiken om het metagegevensdocument van de service te verkrijgen.

Verificatie

Microsoft Dynamics 365 (online)-exemplaren van de web-API van de Discovery-service vereisen verificatie met OAuth-toegangstokens. On-premises of IFD-exemplaren van de web-API van de Discovery-service nemen het verificatiemodel van hun installatie over, met ondersteuning voor geïntegreerde Windows-verificatie of OAuth-tokens van een vertrouwde tokenprovider. Web Application Session-verificatie wordt niet ondersteund.

Als de Discovery-service is geconfigureerd voor OAuth-verificatie, activeert een aanvraag naar de web-API van de service zonder een toegangstoken een bearer-challenge met de bevoegdheid van het 'algemene' eindpunt en de resource-id van de service. En wanneer een on-premises installatie is geconfigureerd voor OAuth, retourneert een bearer-challenge de URL voor de on-premises bevoegdheid en de resource-id van de service.

Web-API-versiebeheer

Versiebeheer van de Discovery-service voor een datacentrum of on-premises/IFD wordt ondersteund en is consistent met de versienummering zoals gebruikt door de organisatieservice. De globale Discovery-service van Microsoft Dynamics 365 (online) is echter niet gekoppeld aan het versienummer van de Dynamics 365-installatie. In plaats daarvan gebruikt de globale service een eigen versienummering. Op het moment van schrijven is versie 1.0 (v1.0) de meest recente versie van de globale Discovery-service van Microsoft Dynamics 365 (online). Bijvoorbeeld:

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

CORS-ondersteuning

De web-API van de Discovery-service ondersteunt de CORS-standaard voor domeinoverschrijdende toegang, net als de web-API van de organisatieservice. Zie Een toepassing met één pagina door middel van OAuth met Cross-Origin Resource Sharing verbinding laten maken met Microsoft Dynamics 365 voor meer informatie over CORS-ondersteuning.

Voorbeelden

Haal de details van een specifiek exemplaar op. Als u de GUID weglaat, worden alle exemplaren geretourneerd waartoe de geverifieerde gebruiker toegang heeft.
```
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>)
```

U kunt het UniqueName-kenmerk als alternatieve sleutel gebruiken.

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

Haal een lijst met beschikbare exemplaren, gefilterd op productietype, op.

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

Haal de waarde van de id-eigenschap van een bepaald exemplaar op.

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

Microsoft Dynamics 365

Delen via