Découvrir l'URL de votre organisation à l'aide de l'API Web
Date de publication : janvier 2017
S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online
Le service de découverte pour l'API Web Microsoft Dynamics 365 permet à vos applications de déterminer au moment de l'exécution les organisations (instances) auxquelles appartient l'utilisateur connecté. Vous pouvez extraire des informations détaillées sur ces instances, telles que l'URL du service de l'instance, la version commerciale Dynamics 365, l'ID d'instance, etc. Vous pouvez utiliser $filter standard et les paramètres $select dans une demande de service API Web pour personnaliser la liste de données d'instance renvoyée. Le service de découverte est pris en charge par tous les types de déploiement Dynamics 365 : en ligne, local et IFD.
Les applications clientes peuvent avoir besoin d'accéder à une instance Dynamics 365 dont l'URL peut changer au fil du temps. Par exemple, si une instance Dynamics 365 est déplacée d'un centre de données Microsoft Dynamics 365 (Online) à un autre. Le service de découverte permet aux instances clientes de persister l'ID d'instance ou le nom unique de l'instance, puis d'utiliser le service de découverte pour rechercher l'URL d'accès de l'instance actuelle.
Outre les services de découverte spécifiques du centre de données, disponibles dans le point de terminaison 2011 (SOAP) et via l'API Web, il existe également un service de découverte global API uniquement Web qui traite les centres de données opérationnels. Pour plus d'informations sur le service de découverte sur le point de terminaison 2011 voir Découvrir l'URL de votre organisation à l'aide du service d'organisation.
Informations fournies par le service de découverte
Les informations sur l'organisation sont stockées dans l'entité Instance du service de découverte. Pour afficher le type d'informations contenues dans cette entité, envoyer une demande HTTP GET au service pour l'une de vos instances.
GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')
Dans l'exemple ci-dessus, le service de découverte global de Microsoft Dynamics 365 (Online) est utilisé pour obtenir les informations d'organisation de l'instance avec un nom unique : « monorg ». Des informations supplémentaires sur cette requête seront développées ultérieurement dans cette rubrique.
Étendue des informations renvoyées
Pour le service de découverte global, l'ensemble d'entités Instances, renvoie l'ensemble des instances auxquelles l'utilisateur a accès partout, si aucun filtre n'est appliqué. Les données renvoyées ont une étendue comme décrit ci-dessous.
Inclut toutes les instances dans le cloud commercial où l'utilisateur est activé et mis en service, sauf si des instances de cloud souveraines ne sont pas retournées
N'inclue pas les instances où le compte d'utilisateur est désactivé
N'inclue pas les instances où les utilisateurs ont été filtrés selon un groupe de sécurité d'instance
Ne comprend pas les instances auxquelles l'utilisateur a accès car il est administrateur délégué
Si l'utilisateur appelant n'a accès à aucune instance, la réponse renvoie simplement une liste vide
Comment accéder aux services de découverte
En général, l'adresse API Web du service de découverte est au format suivant : <service base address>/api/discovery/. Les adresses pour chaque type de déploiement sont identifiées ci-dessous. Vous pouvez facilement rechercher les adresses de l'API Web et le numéro de version de votre déploiement dans l'application Web de Dynamics 365 en allant dans Paramètres > Personnalisation > Ressources du développeur
Services de découverte Dynamics 365 (en ligne)
L'adresse de base du service de découverte global est : https://globaldisco.crm.dynamics.com/. Ceci aboutit à l'adresse du service https://globaldisco.crm.dynamics.com/api/discovery/.
L'adresse de base du service de découverte global pour un centre de données est : https://disco.crm[N].dynamics.com/. Ceci aboutit à l'adresse du service de découverte de https://disco.crm[N].dynamics.com/api/discovery/. Chaque centre de données a un numéro N associé. Pour obtenir la liste complète des centres de données Microsoft Dynamics 365 (Online) disponibles et leurs numéros N, voir Télécharger les points de terminaison à l’aide de la page de ressources du développeur Microsoft Dynamics 365.
Service de découverte IFD et sur site
L'adresse de base du service de découverte pour un déploiement IFD et sur site est : http[s]://{servername}/ ou http[s]://dev.{servername}/. Ceci aboutit à l'adresse du service http[s]://{servername}/api/discovery/ ou http[s]://dev.{servername}/api/discovery/.
Utilisation du service de découverte
Un ensemble d'entités nommé Instances est utilisé pour obtenir des informations sur les instances. Vous pouvez utiliser $select et $filter avec l'ensemble d'entités Instances pour filtrer les données retournées. Vous pouvez également utiliser $metadata pour obtenir le document des métadonnées du service.
Authentification
les instances d'API WebMicrosoft Dynamics 365 (Online) du service de découverte requièrent une authentification avec les jetons d'accès OAuth. Les instances IFD ou sur site de l'API Web de découverte adoptent le modèle d'authentification de leur déploiement, en prenant en charge les jetons IWA (authentification Windows intégrée) ou OAuth d'un fournisseur de jeton approuvé. L'authentification de session d'application Web n'est pas prise en charge.
Si le service de découverte est configuré pour l'authentification OAuth, une requête envoyé à l'API Web de service sans jeton d'accès, déclenche une stimulation de support avec l'autorité du point de terminaison « commun » et l'ID de ressource du service. De même, si un déploiement sur site est configuré pour OAuth, une stimulation de support retourne l'URL d'autorité sur site et l'ID de ressource du service.
Contrôle de version API Web
Le contrôle de version du service de découverte pour un centre de données ou sur site/IFD est pris en charge et est cohérent avec le numéro de version utilisé par le service de l'organisation. Toutefois, le service de découverte global Microsoft Dynamics 365 (Online) n'est pas lié au numéro de version du déploiement Dynamics 365. En revanche, le service global utilise sa propre version de numérotation. Jusqu'à présent, le service de découverte global Microsoft Dynamics 365 (Online) a la version 1.0 (v1.0). Par exemple :
GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')
Prise en charge de CORS
L'API Web du service de découverte prend en charge CORS standard pour l'accès entre origine, tout comme l'API Web de service de l'organisation. Pour plus d'informations sur la prise en charge de CORS, voir Utilisez OAuth avec le partage des ressources cross-origin pour connecter une application sur une seule page à Microsoft Dynamics 365.
Exemples
Accédez aux détails d'une instance spécifique. Si vous excluez le GUID, toutes les instances auxquelles l'utilisateur authentifié a accès sont retournées.
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>)Vous pouvez utiliser l'attribut UniqueName comme clé secondaire.
GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances(UniqueName='myorg')Récupérez la liste d'instances disponibles, filtrée par le type de production.
GET https://globaldisco.crm.dynamics.com/api/discovery/v1.0/Instances?$select=DisplayName,Description&$filter=Type+eq+0Récupérez la valeur d'une propriété spécifique de l'ID d'une instance.
GET https://disco.crm.dynamics.com/api/discovery/v8.1/Instances(UniqueName='myorg')/Id/$value
Microsoft Dynamics 365
© 2017 Microsoft. Tous droits réservés. Copyright