Ermitteln Sie die URL für Ihre Organisation mithilfe der Web-API.

Artikel
07/06/2017

Veröffentlicht: Januar 2017

Gilt für: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Der Ermittlungsdienst für die Microsoft Dynamics 365-Web-API aktiviert Ihre Anwendungen, um bei der Laufzeit die Organisationen zu bestimmen, auch als Instanzen bekannt, zu denen der angemeldete Benutzer gehört. Sie können detaillierte Informationen zu diesen Instanzen abrufen, beispielsweise die Instanzdienst-URL, die Dynamics 365-Freigabeversion, die Instanzkennung und Weiteres. Sie können standardmäßige $filter- und $select-Parameter zu einer Web-API-Serviceanfrage verwenden, um die zurückgegebene Liste von Instanzdaten anzupassen. Der Ermittlungsdienst wird von allen Dynamics 365-Bereitstellungstypen unterstützt: Online, lokal und IFD.

Client-Anwendungen benötigen möglicherweise Zugriff auf eine Dynamics 365-Instanz, bei dem die Instanz-URL im Laufe der Zeit möglicherweise geändert wird. Wenn beispielsweise eine Dynamics 365-Instanz von einem Microsoft Dynamics 365 (online)-Datencenter in einen anderen verschoben wird. Der Ermittlungsdienst ermöglicht es der Clients-Instanz, die Instanzkennung oder den eindeutigen Instanznamen beizubehalten und dann den Ermittlungsdienst zu verwenden, um die aktuelle Instanzzugriffs-URL zu suchen.

Zusätzlich zu Ermittlungsdiensten für bestimmte Datencenter, die für den 2011 (SOAP)-Endpunkt verfügbar sind, und durch die Web-API, gibt es auch einen globalen Ermittlungsdienst nur für Web-API, der sich über alle betriebsbereiten Datencenter erstreckt. Weitere Informationen zu dem Ermittlungsienst für den 2011-Endpunkt finden Sie unter Ermitteln der URL für Ihre Organisation mit dem Organisationsdienst.

Informationen, die vom Ermittlungsdienst bereitgestellt werden

Organisationsinformationen werden in der Entität Instance des Ermittlungsdiensts gespeichert. Um die Art der Informationen anzuzeigen, die in dieser Entität enthalten sind, senden Sie eine HTTP GET-Anforderung zum Service für eine Ihrer Instanzen.

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

Im oben genannten Beispiel wird der globale Ermittlungsdienst von Microsoft Dynamics 365 (online) verwendet, um die Organisationsinformationen der Instanz mit einem eindeutigen Namen "myorg" abzurufen. Weitere Details zu dieser Anforderung werden später in diesem Thema ausführlicher behandelt.

Umfang der zurückgegebenen Informationen

Für den globalen Ermittlungsdienst gibt der Entitätssatz Instances den Entitätssatz zurück, auf den der Benutzer an allen geografischen Orten Zugriff hat, wenn keine Filter angewendet werden. Die zurückgegebenen Daten haben einen Umfang, wie unten beschrieben.

Enthält alle Instanzen in der Handelscloud, wo der Benutzer bereitgestellt und aktiviert ist, außer dass Sovereign-Couds-Instanzen nicht zurückgegeben werden
Enthält nicht Instanzen, bei denen das Konto des Benutzers deaktiviert ist
Enthält keine Instanzen, bei denen Benutzer auf Basis einer Instanzsicherheitsgruppe gefiltert wurden
Umfasst nicht Instanzen, auf die der Benutzer Zugriff hat, da er ein stellvertretender Administrator ist
Wenn der aufrufende Benutzer Zugriff auf keine Instanzen hat, gibt die Antwort einfach eine leere Liste zurück

Wie erfolgt der Zugriff auf die Ermittlungsdienste

Im Allgemeinen hat die Web-API-Adresse des Ermittlungsdiensts das folgende Format: <service base address>/api/discovery/. Die Adressen für jeden Bereitstellungstyp werden unten identifiziert. Sie können die Web-API-Adressen und Versionsnummer für Ihre Bereitstellung einfach in der Dynamics 365-Webanwendung finden, indem Sie zu Einstellungen > Anpassung > Entwicklerressourcen navigieren

Dynamics 365 (online) – Ermittlungsdienste

Die Dienstbasisadresse des globalen Ermittlungsdiensts ist: https://globaldisco.crm.dynamics.com/. Dies führt als Ergebnis zur Serviceadresse von https://globaldisco.crm.dynamics.com/api/discovery/.

Die Dienstbasisadresse des Ermittlungsdiensts für ein Datencenter ist : https://disco.crm[N].dynamics.com/. Dies führt als Ergebnis zur Ermittlungsdienstadresse von https://disco.crm[N].dynamics.com/api/discovery/. Jedes Datencenter hat eine N-Zahl, die ihm zugeordnet ist. Eine vollständige Liste der verfügbaren Microsoft Dynamics 365 (online)-Datencenter und deren N-Zahlen finden Sie unter Endpunkte mithilfe der Microsoft Dynamics 365-Entwicklerressourcenseite herunterladen.

Lokaler und IFD-Ermittlungsdienst

Die Dienstbasisadresse des Ermittlungsdiensts für eine lokale oder eine IFD-Bereitstellung ist : http[s]://{servername}/ oder http[s]://dev.{servername}/. Dies führt als Ergebnis zur Dienstadresse von http[s]://{servername}/api/discovery/ oder http[s]://dev.{servername}/api/discovery/.

Verwenden des Suchdiensts

Ein Entitätssatz mit der Bezeichnung Instances wird zum Abrufen von Instanzinformationen verwendet. Sie können $select und $filter mit der Instanzentität verwenden, die für das Filtern der zurückgegebenen Daten festgelegt wurde. Sie können auch mithilfe $metadata das Metadatendokument des Services abrufen.

Authentifizierung

Microsoft Dynamics 365 (online)-Web-API-Instanzen des Ermittlungsdiensts benötigen die Authentifizierung mit OAuth-Zugriffstokens. Lokale oder IFD-Instanzen der Ermittlungs-Web-API übernehmen das Authentifizierungsmodell ihrer Bereitstellung. Dabei unterstützen sie entweder die Integrierte Windows-Authentifizierung (IWA) oder OAuth-Tokens von einem vertrauenswürdigen Tokenanbieter. Webanwendungssitzungs-Authentifizierung wird nicht unterstützt.

Wenn der Ermittlungsdienst für die OAuth-Authentifizierung konfiguriert ist, löst eine Anforderung, die an die Service-Web-API ohne einen Zugriffstoken gesendet wird, eine Trägerabfrage mit der Autorität des "allgemeinen" Endpunkts und der Ressourcenkennung des Service aus. Wenn in ähnlicher Weise eine lokale Bereitstellung für OAuth konfiguriert wird, gibt eine Trägerabfrage die lokale Autoritäts-URL sowie die Ressourcenkennung des Service zurück.

Web-API-Versionsverwaltung

Versionsverwaltung des Ermittlungsdiensts für ein Datencenter oder lokal/IFD wird unterstützt und ist konsistent mit Versionsnummerierung, wie sie vom Organisationsdienst verwendet wird . Der globale Ermittlungsdienst von Microsoft Dynamics 365 (online) ist jedoch nicht an die Versionsnummer der Dynamics 365-Bereitstellung gebunden. Stattdessen verwendet der globale Service seine eigene Versionsnummerierung. Ab Verfassung dieses Texts befindet sich der globale Ermittlungsdienst von Microsoft Dynamics 365 (online) bei Version 1.0 (v1.0). Beispiel:

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

CORS-Support

Die Ermittlungsdienst-Web-API unterstützt den CORS-Standard für den ursprungsübergreifenden Zugriff, wie das für die Organisationsdienst-Web-API zutrifft. Weitere Informationen zum CORS-Support finden Sie unter Verwenden von OAuth mit Cross-Origin Resource Sharing, um eine Single Page-Anwendung mit Microsoft Dynamics 365 zu verbinden.

Beispiele

Rufen Sie die Details einer bestimmten Instanz ab. Wenn Sie die GUID auslassen, werden alle Instanzen zurückgegeben, auf die der authentifizierte Benutzer Zugriff hat.
```
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>)
```

Sie können das UniqueName-Attribut als Alternativschlüssel verwenden.

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

Rufen Sie eine Liste verfügbarer Instanzen ab, die nach Produktionstyp gefiltert sind.

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

Rufen Sie den Kennungseigenschaftswert einer bestimmten Instanz ab.

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

Microsoft Dynamics 365